# Theme architecture

Amber (the default) is a normal theme extension and must use the same contract future themes use.

## Theme contract v1 (§18)

`ThemeDefinitionV1`: id, name, version, tokens (background, panel, foreground, foregroundBright, foregroundMuted, foregroundFaint, border, borderStrong, accent, positive, warning, negative, fontUi, fontBody, radius, contentMeasure), settingsSchema, assets, renderers (partial slots).

## Controlled renderer slots (§18.1)

Token-first themes are preferred; more structural themes override only defined slots: `site.shell`, `site.header`, `site.footer`, `page.home`, `page.article`, `content.post-list`, `ui.navigation`, `ui.metadata`. Themes never replace routing, authentication or persistence.

## CSS layers (§18.2)

```css
@layer reset; @layer core; @layer components; @layer extension; @layer theme; @layer site-overrides;
```

Variables use the EPPP namespace.

## Fallback (§18.3)

visitor preference → (valid + enabled + owner-permitted?) → site default → (valid + enabled?) → emergency built-in core fallback. A theme error must never cause a blank site.

## Theme naming (§18.4, v1.1)

Two v1.0 names referenced trademarks and one collided with the runtime. Approved shipping names (visual direction unchanged):

| Shipping | v1.0 name | Character |
|---|---|---|
| `amber` | Node | default; amber phosphor on near-black, status-page home |
| `bevel` | X11 | beveled window chrome, grey desktop, green phosphor |
| `warden` | Shodan | dark custodial green and red |
| `lattice` | GITS | cool cyan network topology |
| `paper` | Ledger | light, print-correct, high-contrast |

`amber` names the phosphor, not the runtime (`org.eppp.theme-amber`). "Shodan" and "GITS" must not appear in code, package IDs or the public repository. `paper` is the accessible high-contrast light option that prints correctly.

## Theme proof (Sprint 4)

Complete `ThemeRegistry` (registerTheme, listThemes, getTheme, getSiteDefaultTheme, resolveTheme), Amber extraction audit (tokens only in `theme-amber`, core cannot import it), restrained theme settings (accent override, content width, font scale), a component gallery, a deliberately different **Test Light theme** (not shipped publicly) to expose leaked assumptions, and failure scenarios (removed/disabled theme, invalid manifest, missing asset) — every public request falls back safely.