Blackcap-Safe Emoji
Audience: Developer, System Admin, Support, UI Designer
Related documentation: UI, icons, and assets, E-ink rendering, Recipe editing and cache, Backups
Why Blackcap uses a safe emoji set
Emoji are used throughout Blackcap to make recipe, meal, display, status, and navigation concepts easier to recognize. Native emoji rendering is not consistent enough for Blackcap's supported surfaces: browsers, operating systems, PDF/image renderers, Raspberry Pi font installations, and four-gray e-ink panels can produce different art, missing glyph boxes, color-only glyphs, or incorrect measurements.
Blackcap therefore maintains a curated Blackcap-safe emoji registry. An emoji is safe when Blackcap can identify it consistently, validate it before storage, and render a predictable local asset for generated images and e-ink output. The goal is not to support every Unicode emoji. The goal is a useful, deterministic set that does not silently break a recipe card or display.
Registry and asset model
The registry is the canonical list of supported emoji and associated metadata. It includes curated Food & Drink symbols, widely used interface symbols, favorites, aliases, search terms, and grouping information used by the picker and server validation.
Registry metadata is database-backed. Rendered assets are generated files, normally under emoji_cache/, with monochrome assets used for e-ink and optionally color assets for surfaces that support them. Generated files are caches, not the authoritative registry.
This separation means:
- a backup can preserve registry/configuration data independently of generated cache files;
- the cache can be regenerated when missing or invalid;
- picker search and aliases remain stable even if an asset must be rebuilt;
- one canonical validation path can be used by Admin, Mobile, API, recipe import, and rendering.
Validation and storage
User-entered or imported emoji must be normalized and validated through the shared emoji service before they are persisted in a field that promises safe rendering. Validation also inspects nested recipe or content payloads where emoji may appear.
Unsupported emoji should produce a clear validation response or remain plain text only where the field explicitly permits it. Blackcap must not replace an unsupported symbol with an unrelated “close enough” icon. That would change user meaning and make troubleshooting difficult.
Picker behavior
The emoji picker reads canonical registry metadata and supports category browsing, favorites, names, and aliases. UI code should consume the shared picker/registry APIs rather than maintaining a second JavaScript-only list.
When adding an emoji:
- add or update its registry metadata;
- give it clear names and search aliases;
- verify monochrome generation;
- inspect it at e-ink size and contrast;
- verify browser and generated-image placement;
- update tests for normalization, validation, and cache behavior.
Asset generation
Blackcap can obtain suitable source art through the configured emoji asset pipeline and prepare a monochrome local asset. A local emoji-capable font may be used as a fallback when supported. Asset creation should be deterministic and must not depend on a browser's current native emoji font.
The generator should:
- preserve the requested emoji identity;
- crop and scale without clipping important detail;
- create strong black/white or supported-gray shapes for e-ink;
- avoid thin light-gray lines that disappear on the physical panel;
- write atomically so a partial file is not treated as valid;
- record or expose generation failures for support diagnostics.
E-ink rendering
Generated recipe, Meal Planner, Menu, Let’s Cook, and other display images should use prepared monochrome assets rather than asking Pillow or the panel environment to render native emoji glyphs. The renderer measures the asset, scales it to the layout, and pastes it into the image before e-ink conversion.
This is especially important for the Waveshare 13.3-inch Type K panel. Fine gray outlines can vanish, and a color emoji converted at the last moment may become an indistinct dark block. Blackcap-safe assets are designed and tested for the constrained output.
Documentation and navigation emoji
Documentation uses emoji as visual wayfinding, but it does not use an independent ad hoc set. Application UI and documentation must follow the same canonical mappings in UI, Icons, and Documentation Assets. In particular, use 🧑🍳 for Let’s Cook/guided cooking, 🤖 for AI, 🎮 for Games, 🧩 for the Chrome Extension, and 🧺 for Kitchen Inventory. Do not substitute older or merely related symbols in feature navigation or headings.
Documentation and UI navigation symbols are not automatically valid recipe/content emoji. When a symbol is persisted as user data or rendered into a recipe PDF, preview, cached image, Menu, Meal Planner, Let’s Cook screen, or e-ink transport, it must also exist in the runtime registry and use the shared validation and generated-asset path described here.
UI icon versus content emoji
An emoji used as recipe/content data is not automatically the correct choice for an application control. Controls should follow the canonical icon/action mappings in UI, icons, and assets, include accessible text or labels, and avoid relying on the symbol alone for destructive or ambiguous actions.
Use emoji to reinforce meaning, not to hide the action name.
Administration and cache maintenance
The System Admin emoji tools can inspect registry groups, items, aliases, and generated assets. Cache maintenance may regenerate missing assets or remove invalid generated files while retaining registry entries.
When a cache problem affects one recipe or display, verify the registry entry and source emoji first. Rebuilding every asset should be a deliberate maintenance action, not the default response to one failed file.
Backup and restore
Registry data and organization/user choices are durable. Generated emoji assets may be included in a backup for faster restore, but they must remain reproducible. Restore should not accept cache files as proof that the corresponding registry entry is valid.
Privacy and licensing
Do not commit proprietary emoji font files or redistribute assets whose license does not permit it. Keep source attribution and licensing requirements in the asset pipeline or project notices where required. Generated documentation screenshots must not expose private recipe, user, or organization data.
Troubleshooting
A square or missing glyph appears
Confirm the renderer used the Blackcap asset path rather than native font rendering. Verify the emoji exists in the registry and the expected cached asset exists and is readable.
The wrong image appears
Treat this as a cache/identity defect. Remove or rebuild the incorrect asset and verify key normalization. Do not accept a visually similar substitute.
An emoji looks good in the browser but poor on e-ink
Inspect the monochrome asset at its actual rendered size. Increase shape weight, simplify detail, or choose another safe emoji. Do not use light-gray one-pixel strokes for essential detail.
Imported content contains unsupported emoji
Keep the original text available for review, identify the unsupported symbol, and require a supported choice where the field needs deterministic rendering. Import processing must not invent a replacement.
Development rules
- Use the shared registry, validation, and cache services.
- Do not create feature-specific emoji allowlists.
- Do not embed a large binary emoji pack in application code.
- Keep generated assets out of database blobs unless a reviewed architecture change requires it.
- Preserve organization scoping for preferences and favorites.
- Test browser, image/PDF, and physical e-ink behavior for new high-use symbols.