Add theme architecture docs

2026-08-27 08:18:10 +00:00
parent 81dad97d1d
commit b71d59675b
1 changed files with 41 additions and 0 deletions
@@ -0,0 +1,41 @@
+# 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.