brain-of-reese/frontend/assets/themes/README.md

Themes — authoring guide (phase 62)

A theme is a small CSS file that overrides the :root palette variables. That is the entire mechanism — no component CSS is theme-aware, every color in the app reads a --* variable, so a later stylesheet wins by cascade order.

How a theme loads

1. Set BOR_THEME=<file> (a bare FILENAME, e.g. BOR_THEME=indigo.css). app/config.py validates it at startup — anything not matching ^[a-z0-9_-]+\.css$ (a path, .., uppercase, a missing extension) refuses to boot, naming the value (the phase-56 fail-loud house style).
2. The value rides the existing boot fetch: GET /api/config → frontend/assets/brand.js inserts <link rel="stylesheet" href="/assets/themes/<file>"> IMMEDIATELY AFTER the styles.css link — later wins the cascade.
3. A theme file MISSING at runtime (typo past the validator, or the file deleted after the image was built) degrades to the built-in theme — brand.js warns in the console, the page never breaks (the loadHealth house style, A5).
4. UNSET (BOR_THEME empty) ⇒ no link is inserted at all — the deployment renders byte-identical to the built-in dark-tech palette. Loading is opt-in via the env var, never by directory scanning.

The variables

A theme overrides the 8 identity variables in a single :root block. Built-in values (from frontend/assets/styles.css) for reference:

Variable	Built-in	Role
--bg	#0f0a0a	page background (text on it: --ink)
--surface	#1a0f0f	cards, panels, code blocks (text on it: --ink)
--ink	#f0e6e6	primary text
--ink-soft	#b8a8a8	secondary text (5.1:1 on --surface)
--line	#2d1a1a	decorative 1px borders (no contrast obligation)
--brand	#f43f5e	brand accent — buttons, links (text ON it is --bg)
--brand-soft	#2d0a0a	brand-tinted surface (chips, hover washes)
--brand-ink	#fca5a5	brand-tinted text (9.0:1 on --surface)

The semantic families are deliberately NOT identity — do not override them: --accent-* (deflection amber), --ok-* (success green), --err-* (error red) encode states, and they are already AA in the built-in theme. A theme that keeps them stays honest: your indigo app still tells success from error.

Rules

• Filename: ^[a-z0-9_-]+\.css$ — lowercase, bare filename, in this directory. The server validator rejects anything else at startup (naming the value), so keep the env var and the filename in lockstep.
• One :root block. No selectors, no @media, no other declarations — the file overrides variables and nothing else (the cascade does the rest). indigo.css is the reference shape.
• Every text/background pair ≥ 4.5:1 (AGENTS.md rule 5, WCAG 2.1 AA). The pairs that matter: --ink on --bg and on --surface, --ink-soft on --surface, --bg on --brand (the text on brand buttons is the DARK background ink — that is the pattern), and --brand-ink on --surface.
• Never white-on-brand. The built-in documents the trap: white on #f43f5e is 3.7:1 — it fails. Pick a --brand whose luminance carries the dark --bg ink at ≥ 4.5:1 (indigo.css: 6.5:1).
• Keep --line close to --surface (a 1px step, not a wall) — the layout reads by surfaces, not borders.

Deployment

• Dev: works immediately — the file is served from the static dir (frontend/, BOR_STATIC_DIR), so drop the file in, set BOR_THEME, restart uvicorn.
• Container: rebuild the image. Stage 1 ships the WHOLE directory (cp -r ./assets/themes /out/assets/themes — no per-file esbuild), so a new or edited theme file needs no Containerfile change (A7): whatever is in frontend/assets/themes/ at build time is what the image serves at /assets/themes/….