The motivation: one set of components at Services Australia serving many teams and frameworks, and what happens to all of them when a single value changes.
Public-level war stories only: naming, governance, versioning, and the change that broke something downstream.
Three tiers: primitive, semantic, component
Primitives are raw palette values per theme, semantics are theme-independent meaning (17 paths, including five named hues), and components alias semantics only.
The colour rule the whole site follows: CSS and the picker reference semantic or component tokens, never a primitive or a hex literal, and a test enforces it.
One source in DTCG format, four outputs
tokens/*.json in the Design Tokens Community Group 2025.10 format, and the dependency-free build-tokens.mjs that emits tokens.css, tokens.json, a manifest and the table in this post.
Why everything renders in memory first, so a contrast failure leaves the last good output untouched.
The contrast gate
Every text-on-surface pair in every theme checked at full precision, because #647a86 on white is 4.49686 and would pass at 4.5 if rounded.
What failed and how it was fixed: only foregrounds moved, by HSL lightness in steps of 0.001, so Monokai Pro pink went from 4.30 to 4.53 and Solarized pink from 3.80 to 4.50.
Themes and modes
Eight dark themes plus Paper, data-theme and data-mode defined so that a first visit with no JavaScript gets Gruvbox dark on any operating system.
Why choosing a dark theme always sets dark mode, and how system mode follows the OS only when asked.
Section tints: three layers, no pixel coloured twice
The tint contract: the theme layer, the section layer and the content layer each own different pixels, and exactly four places use the section tint.
The CSS test that counts those four rules, and the Talks heading that briefly made a fifth.
When a token changes
On this site: the line colour that failed 3:1 in all nine themes, and the ruling that borders are decorative.
Back at myGov: how a change like that is versioned and rolled out across teams.
WRITING4 posts2 minblue mountains, australia · built 2026-10-26 20:40rss