Themes
Themes are collections of values for the same semantic token paths. They are not a second component stylesheet or a collection of dark: exceptions.
Collections#
| Collection | Source | Selector | Purpose |
|---|---|---|---|
| Light | tokens/themes/light.tokens.json | :root, [data-theme="light"] | Default reading surface and exported diagram palette |
| Dark | tokens/themes/dark.tokens.json | [data-theme="dark"] | Dark reading surface with the same semantic API |
Both collections override color.ink, color.paper, color.line, color.accent, and the neutral scale. Components continue to use variables such as --color-paper; they do not decide which collection is active.
npm run tokens:themes generates assets/css/generated/themes.css. The header’s Theme toggle selects a collection through data-theme and stores an explicit reader choice only after the reader changes it.
Rules#
- Add a theme override only when the same semantic role needs a different value in another mode.
- Keep component geometry, typography, radius, shadow, and motion outside a colour-mode collection unless the mode genuinely changes that decision.
- Add equivalent paths to both collections. The generator rejects a collection whose override set differs from Light.
- Use a semantic role instead of a palette primitive in component CSS, Tailwind configuration, Mermaid, and documentation examples.