0018. A project theme is a schema-checked theme.yaml that also chooses the colour scheme
- Status: Proposed
- Date: 2026-11-14
- Decided by: Mik
- Planning item: WP7 part 1 (styling and themes)
Context
A project needs its own brand: colours, radius, shadows, type and font. Mistakes in a theme file used to surface as a deserialisation error with no path, or not at all. Some apps are dark only, or light only, whatever the device says.
Decision
theme.yamlat the project root overrides any token of the default theme and may add new ones; utilities pick new tokens up (a colourbrandgivesbg-brand,text-brand,border-brand). Colours and shadows always need both a light and a dark value.- The file is described by
spec/schemas/theme.schema.json.Theme::loadchecks it against that schema before reading it and reports every problem at once, each with its path and, for a misspelt name, the closest allowed one. YAML numbers and keys are read as text, soweight: 700and4: 18pxwork; a list or group used as a key is refused. Token names are limited to letters, digits,-,_and.(the emitter escapes.), and values may not be empty or contain; { } < \, a comment, a line break or an unclosed quote or bracket, because names and values are written straight into each target's style output. The checker incrates/styleunderstands only the keywords the schema uses; a test fails if the schema uses another. dark: system | light | darkchooses the colour scheme.system(the default) follows the device;lightnever shows dark values and dropsdark:utilities;darkalways shows dark values and appliesdark:utilities unconditionally. The web emitter receives it throughWebOptions::color_scheme.
Alternatives considered
| Option | Why not |
|---|---|
| A full JSON Schema validator crate | Pulls in a large dependency tree for a dozen keywords |
Theme in TypeScript (theme.ts) | Needs a script runtime at build time and is harder for tools to read |
| A colour with one value for both modes | Hides dark mode until someone looks; asking for both makes it a decision |
Consequences
Editors can use the schema for completion. Theme errors are still reported as project failures rather than coded diagnostics; giving them catalogue codes belongs with the diagnostics catalogue.