Duolith docs

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.yaml at the project root overrides any token of the default theme and may add new ones; utilities pick new tokens up (a colour brand gives bg-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::load checks 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, so weight: 700 and 4: 18px work; 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 in crates/style understands only the keywords the schema uses; a test fails if the schema uses another.
  • dark: system | light | dark chooses the colour scheme. system (the default) follows the device; light never shows dark values and drops dark: utilities; dark always shows dark values and applies dark: utilities unconditionally. The web emitter receives it through WebOptions::color_scheme.

Alternatives considered

OptionWhy not
A full JSON Schema validator cratePulls 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 modesHides 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.