Changing every colour without editing 31 files

Count before you start

The first thing we did was count. 972 uses of the colour tokens, in 31 of 44 component files. Editing them is not a day of work, it is a day of work plus every mistake you make in a thousand small edits.

The names were already right

The ramps were called ground, surface, ink, sand and brand. Those names describe roles, not colours, which means they were still true after the palette changed. Only the values underneath them had to move.

So we left all 972 utilities alone and re-pointed the ramps at CSS variables. One class on the root element now re-themes the whole site, and no component holds a hex.

The detail that decides it

Write the variables as RGB channels, not hex. The alpha modifier appears 108 times in this codebase, and it cannot slice an alpha out of a hex string:

--fg: 237 237 237;

ink: "rgb(var(--fg) / <alpha-value>)"

Same values as the brand document prints. Different notation, because the notation is what makes the opacity syntax keep working.

Where it did not work

Ten colours were hard-coded inside the illustration kit. They could not follow a variable, so they were cream on a near-black ground until they became tokens too. The first dark values we picked sank the objects into the background; a drawn solid has to stay above the ground it sits on, which is a judgement no variable makes for you.