2.3 KiB
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)
@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.