UI, Icons, and Documentation Assets
Audience: Developer, Support Related: Eink Rendering
Shared UI symbols, field-specific emoji controls, country flags, Noun Project assets, recipe thumbnails, e-ink images, and documentation previews should use descriptive filenames, accessible labels, and the established asset services. Do not expose credentials or personal data in screenshots.
Country flag assets remain documented beside the generated files. E-ink-specific grayscale rules are documented with display rendering.
Blackcap uses emoji/icons as quick visual anchors, but actions should still keep accessible text, labels, titles, or tooltips.
Feature and documentation navigation mappings
Use these mappings consistently in both the application UI and documentation. This includes Admin and Mobile navigation, feature cards, feature headings, assignment controls, README capabilities, the documentation index, feature catalogs, and overview pages. The written label remains required.
| Concept | Emoji |
|---|---|
| Blackcap / product identity | 🫐 |
| Feature catalog / major capabilities | ✨ |
| Recipes / Recipe Library | 🍽️ |
| Meal Planner | 📅 |
| Shopping Lists / Shop a List | 🛒 |
| Kitchen Inventory | 🧺 |
| Displays | 🖥️ |
| Let’s Cook / guided cooking | 🧑🍳 |
| AI | 🤖 |
| Chrome Extension / browser workflows | 🧩 |
| Users and security | 🔐 |
| Configuration / development | ⚙️ |
| Administration and operations | 🛠️ |
| Performance | 📊 |
| Job Status | 🧰 |
| Integrations | 🔌 |
| Backup / GCP / cloud storage | ☁️ |
| Maintenance and purge | 🧹 |
| Games | 🎮 |
| Architecture / platform | 🧱 |
| Deployment | 🚀 |
| Raspberry Pi | 🥧 |
| Updates / refresh / synchronization | 🔄 |
| Navigation / quick links | 🧭 |
| Documentation | 📚 |
| Repository / package / assets | 📦 |
| Troubleshooting | ⚠️ |
| Diagnostic clone / safe reproduction | 🧪 |
| Support Request | 🆘 |
| GeoIP / country access | 🌎 |
| Noun Project / visual assets | 🎨 |
| Emoji tools | 🙂 |
The functional-topic mappings apply wherever the feature itself is being represented:
- 🧑🍳 Let’s Cook / guided cooking
- 🤖 AI
- 🎮 Games
- 🧩 Chrome Extension
- 🧺 Kitchen Inventory
Do not use the older canned-food symbol for Kitchen Inventory feature navigation or headings. The canonical feature symbol is 🧺 because the feature represents a household collection of on-hand items rather than one canned ingredient. The 🥫 symbol remains valid for a Pantry storage location or an actual canned-food concept.
Related symbols may still be used when they represent a different action or concept. For example, 🍳 may represent breakfast or a Render Recipe action, 🧠 may represent a trivia character or Noun Project matching concept, 🎉 may represent successful completion, and 🌐 may represent a generic web source. They must not replace the canonical feature symbols in navigation, headings, feature cards, or feature-selection controls.
Canonical mappings
| Concept | Icon | Rule |
|---|---|---|
| Saved recipes / recipe search / choose a meal recipe | 🍽️ | Use for saved recipe panels and Meal Planner recipe-picking contexts. |
| Recipe Discovery | 🕵 | Use for the Recipe Discovery page, nav, and discovery launch actions. |
| Search action | 🔎 | Use for literal search/apply-search actions. Do not reuse it for Recipe Discovery. |
| Details / information panel | ℹ️ | Use for detail popups, explanatory information, and metadata panels. |
| Preview / visual view | 👀 | Reserve for visual preview/view actions. |
| Edit | ✏️ | Use for editing an existing item. |
| Delete/remove | 🗑️ | Use for destructive remove/delete actions. |
| Refresh/reload/update | 🔄 | Use for refresh/update actions. |
| Retry | 🔁 | Use for retrying a failed job/action. |
| Sync | 🔄 | Use with explicit Sync text where the action pulls/pushes external state. |
| Job Status | 🧰 | Use for background operations/job health. |
| Performance | 📊 / 📈 | 📊 for overview metrics, 📈 for graph/trend actions. |
| Nutrition | 🧾 | Use through the recipe metadata UI helper. |
| Total time | ⏱️ | Use through the recipe metadata UI helper. |
| Cleanup score | 🛁 | Use through the recipe metadata UI helper. |
| Emoji tools / emoji management | 🙂 | Use for the System Admin Emoji Tools page and emoji-cache/registry management. |
Prefer shared helpers or constants when a template or script is being touched for related UI work. Avoid changing unrelated icons just because they are nearby.
Emoji registry and generated assets
Blackcap-safe emoji metadata is stored in the application database so pickers, validation, and display rendering use one supported registry. Generated image assets remain on disk under paths such as:
emoji_cache/monochrome/
emoji_cache/color/
The database registry/cache metadata and generated files have different responsibilities: the database is the searchable/configurable source of supported emoji state, while the PNG assets are filesystem render artifacts. Full/platform backup behavior may include the emoji cache according to the backup scope.
Useful maintenance commands include:
/home/pi/inky_env/bin/python3 tools/sync_emoji_cache_to_sqlite.py --json
/home/pi/inky_env/bin/python3 tools/audit_json_runtime_usage.py
Do not add arbitrary Unicode emoji to user-visible e-ink content without registering/validating it through the existing emoji support path.