Themes

Three read-only presets live in src/themes/presets/ (DEC-0002): Ledger (Stripe-inspired light, the default), Foundry (Linear-inspired dark), and Gazette (warm editorial serif). Each defines the same token set under [data-northstar-theme='<id>']: color roles (--bg, --surface, --ink, --muted, --line, --accent, --ok/--warn/--danger + soft variants), radii, shadow depth, type scale, and spacing density.

How switching works

The default ships in src/themes/config.ts (DEFAULT_THEME) and is stamped on <html data-northstar-theme> at build time. (Plain data-theme belongs to Starlight’s light/dark chrome and is derived from the preset’s mode.)
The workbench theme popover (DEC-0018) previews any theme instantly: it sets data-northstar-theme and persists to localStorage. Previewing never edits files — committing a choice means changing DEFAULT_THEME.
Marketing pages and every live screenshot consume the same tokens, so a theme switch moves everything together.

Fork-on-change

The moment a design change is requested, the agent copies the active preset’s tokens into src/themes/custom.css under [data-northstar-theme='custom'] and edits the copy. Presets stay pristine; “switch back” always works; the fork persists so you can return to it. Custom appears in the toolbar only once the fork exists.

States & edge cases

No fork yet — custom.css is comment-only; the workbench hides the Custom option.
Unknown data-northstar-theme value — no token set matches; the agent must never invent theme ids outside config.ts.
Production — the workbench ships, so previewing works there too; fresh visitors see DEFAULT_THEME.
Docs pages — /docs wears the active theme too: starlight-bridge.css maps the tokens onto Starlight’s variables, and each preset’s mode forces the matching light/dark chrome (code blocks, search). Starlight’s own light/dark toggle is hidden — the preset decides.