ADR-0004 Design tokens: two themes, computed contrast

Version: 1 · 2026-10-02 · accepted

Decision

Light theme: white ground, navy ink and accent. Dark theme: navy-black ground, pale blue accent, re-picked rather than inverted. Three semantic families from the product's own distinctions (ok, warn, fail), each with a soft ground. Every text-and-ground pair the app paints clears 4.5:1 in both themes; the check is a script, not an eye. Values live in spec/figures/tokens.json and generate the wireframes; the app and the sites consume the same values.

Why

The owner judged the first palette (charcoal with chip blue and amber, light mode produced by inversion) as poor in light mode and asked for white and navy. Deriving both themes from one checked token file keeps the wireframes, the landing page, the docs and the app in agreement.

Consequences

Type: Archivo for display, Instrument Sans for body, JetBrains Mono for figures and labels only. Icons: a single stroke-icon set, baked as paths.