# 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;
```

For SVGs only, add `image-rendering: -webkit-optimize-contrast;` for crisp edges.
For PNGs/JPEGs/WebP, do NOT apply this property — it causes pixelation on raster images.

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
