diff --git a/docs/02-for-app-authors/03-appdata-guidelines/01-quality-guidelines.md b/docs/02-for-app-authors/03-appdata-guidelines/01-quality-guidelines.mdx
similarity index 85%
rename from docs/02-for-app-authors/03-appdata-guidelines/01-quality-guidelines.md
rename to docs/02-for-app-authors/03-appdata-guidelines/01-quality-guidelines.mdx
index 42e6f1c9..8dc947f0 100644
--- a/docs/02-for-app-authors/03-appdata-guidelines/01-quality-guidelines.md
+++ b/docs/02-for-app-authors/03-appdata-guidelines/01-quality-guidelines.mdx
@@ -1,3 +1,5 @@
+import AppIconGrid from "./assets/app-icon-grid.svg";
+
# Quality guidelines
For the quick guidelines for the actual content (descriptions, screenshots), see the Appstream [docs](https://www.freedesktop.org/software/appstream/docs/chap-Quickstart.html).
@@ -30,6 +32,9 @@ The icon should be SVG, or a PNG with a size greater or equal to 256x256 pixels.
### Reasonable footprint
The icon shouldn't fill too much or too little of the canvas. Avoid filling the entire canvas and having the icon touch the edges of the canvas (except with small protruding elements). Similarly, avoid thin shapes that are hard to see.
+You can use the following grid to check if your icon has a reasonable footprint:
+
+
### Good contrast
@@ -53,35 +58,90 @@ The icon should be somewhat in line with the contemporary icon styles (i.e. not
The name should ideally be no longer than 15 characters, and must be shorter than 20 characters.
+:::danger Bad examples
+
+- Apostrophe Markdown
+- Minimal Markdown Editor
+ :::
+
### Just the name
-The name should be just the name, without any additional info. For example, don't append what the app does to the name (e.g. `Apostrophe - Markdown Editor`), and use the summary to provide this extra information instead.
+The name should be just the name, without any additional info. For example, don't append what the app does to the name, and use the summary to provide this extra information instead.
+
+:::danger Bad examples
+
+- Apostrophe - Markdown Editor
+- Apostrophe (Markdown Editor)
+- Apostrophe (Special Edition)
+ :::
### No weird formatting
The name should not have any weird formatting or punctuation. For example, it should not be all-lowercase, all-uppercase, camel case, or contain dashes or periods. Cases where the weird formatting is part of the brand are exempt from this (e.g. `VLC`).
+:::danger Bad examples
+
+- apostrophe
+- APOSTROPHE
+- ApostropheEditor
+- Apostrophe.org
+ :::
+
## Summary
### Not too long
The summary should ideally be between 10 and 25 characters, and no longer than 35 characters.
+:::danger Bad example
+
+- A simple markdown editor for editing files on your system
+ :::
+
### Not technical
-The summary should be understandable by a non-technical person, and not contain any technical terms (e.g. `Chat app written in Rust and GTK4/Libadwaita`). Don't mention the toolkit, programming language, or other implementation details that would not be relevant to a non-developer and explain what the app does for people instead.
+The summary should be understandable by a non-technical person, and not contain any technical terms. Don't mention the toolkit, programming language, or other implementation details that would not be relevant to a non-developer and explain what the app does for people instead.
+
+:::danger Bad examples
+
+- A GTK4 chat app written in Rust
+- An Electron Wrapper for the Telegram Web App
+- A Qt5 app for managing your Steam library
+ :::
### No weird formatting
The summary should not have any weird formatting or punctuation. It should use sentence case, rather than title case. It shouldn't end with a full stop.
+:::danger Bad example
+
+- A Simple Markdown Editor.
+ :::
+
### Don't repeat the name
The summary is usually shown next to the app name, so repeating the name looks bad.
+:::danger Bad example
+
+- Apostrophe - A simple markdown editor
+ :::
+
### Don't start with an article
-Starting summaries with an article, e.g. `An image viewer`, or `The LibreOffice suite` is almost always unnecesary. Instead, either omit the article or ideally phrase it in the imperative with a verb, e.g. `View images and videos` or `Edit documents`.
+Starting summaries with an article is almost always unnecessary. Instead, either omit the article or ideally phrase it in the imperative with a verb.
+
+:::danger Bad examples
+
+- An image viewer
+- The LibreOffice suite
+ :::
+
+:::tip Good examples
+
+- View images and videos
+- Edit documents
+ :::
## Description
diff --git a/docs/02-for-app-authors/03-appdata-guidelines/assets/app-icon-grid.svg b/docs/02-for-app-authors/03-appdata-guidelines/assets/app-icon-grid.svg
new file mode 100644
index 00000000..63182194
--- /dev/null
+++ b/docs/02-for-app-authors/03-appdata-guidelines/assets/app-icon-grid.svg
@@ -0,0 +1,58 @@
+
+
+
+
diff --git a/src/css/custom.css b/src/css/custom.css
index 37fb8b0f..7b3bc6ff 100644
--- a/src/css/custom.css
+++ b/src/css/custom.css
@@ -25,3 +25,17 @@
--ifm-color-primary-lighter: #6ea6e1;
--ifm-color-primary-lightest: #92bce8;
}
+
+[data-theme='light'] .themedDocusaurus {
+ fill: black;
+ stroke: black;
+ width: 256px;
+ height: 256px
+}
+
+[data-theme='dark'] .themedDocusaurus {
+ fill: white;
+ stroke: white;
+ width: 256px;
+ height: 256px
+}
\ No newline at end of file