rule: theming — never hardcode visual assets, always use theme system

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

.claude/rules/theming.md

+# Theming Rule — NEVER hardcode visual assets
+
+## The Rule
+
+Every visual element in the EL3AB player app MUST go through the theming system. Never hardcode:
+
+- **Emojis** → Use `emoji(key, fallback, size)` from `core/theme.js`
+- **Icons/Images** → Use `assetImg(slot, fallback, width, height)` from `core/theme.js`
+- **Colors** → Use CSS variables from `tokens.css` (e.g., `var(--gold)`, `var(--bg-card)`)
+- **Gradients** → Use CSS variables or reference theme.json keys
+- **Animation durations** → Use `var(--dur-fast)`, `var(--dur-normal)`, `var(--dur-slow)`
+- **Border radii** → Use `var(--r-sm)`, `var(--r-md)`, `var(--r-xl)`, `var(--r-full)`
+- **Button styles** → Use `var(--btn-press-scale)`, `var(--btn-min-height)`, etc.
+
+## How To Add New Visual Assets
+
+1. Add the slot to `/admin/branding.php` in the appropriate section
+2. Add the CSS variable to `tokens.css` if it's a color/size
+3. Use `assetImg()` or `emoji()` in the component code
+4. Update `ASSET_REGISTRY.json` (run the sweep script or add manually)
+
+## How To Add New Emojis
+
+1. Add entry to the `emojiSlots` array in `/admin/branding.php`
+2. In the component, import `{ emoji }` from `core/theme.js`
+3. Replace the hardcoded emoji string with `emoji('key', '🎁', 24)`
+
+## Pixelation Prevention
+
+All asset rendering MUST use:
+```
+width: {exact}px;
+height: {exact}px;
+object-fit: contain;
+image-rendering: -webkit-optimize-contrast;
+```
+
+Never use `width: 100%` or `auto` for themed assets — always explicit pixel dimensions.
+
+## Files That Control Theming
+
+- `/public/js/core/theme.js` — Runtime loader, applies CSS vars, provides `emoji()` and `assetImg()`
+- `/public/css/tokens.css` — CSS custom properties (colors, spacing, radii, fonts)
+- `/admin/branding.php` — Admin UI for editing all values
+- `/public/assets/brand/theme.json` — Persisted theme values (written by admin)
+- `/ASSET_REGISTRY.json` — Complete inventory of all visual assets in the platform