accessibility
Contrast is asserted by the build, not by intention. The audit found a defect that had been shipping for months.
the build asserts it
design/build-tokens.py --audit prints every foreground /
background pair the system actually puts together, with its WCAG ratio and the
threshold that applies, and exits non-zero if any fall short. The list is
curated, not generated — an all-against-all would be hundreds
of rows nobody reads, flagging combinations that never occur.
It audits derived steps too, not only the raw tokens: the editor's
dim ramp and Spotify's subtext step are computed inside the theme renderers and
are as load-bearing as anything in the token source.
what it found immediately
Secondary ink had failed AA on all three light surfaces
since the palette was inverted — 3.62 / 3.94 / 3.34 against a 4.5 requirement —
and it is the ink for every subtitle in the shell. The inversion pass measured
the wallpaper shader carefully and the chrome by eye. That is the gap this
closes.
The fix kept hue and saturation and dropped lightness 0.531 → 0.446, giving
4.88 / 5.31 / 4.51, with the luminance gap to primary ink preserved so the
two-tier hierarchy still reads.
every pair, live
Rendered by the same function that gates the build, so this
table cannot advertise a ratio the build does not enforce.
| pair | fg / bg | ratio | min | grade |
|---|
| primary ink on base surface | | 7.90 | 4.5 | AAA |
| primary ink on raised chrome | | 8.60 | 4.5 | AAA |
| primary ink on hover surface | | 7.30 | 4.5 | AAA |
| secondary ink on base surface | | 4.88 | 4.5 | AA |
| secondary ink on raised chrome | | 5.31 | 4.5 | AA |
| secondary ink on hover surface | | 4.51 | 4.5 | AA |
| hairline against base surface | | 1.32 | 1.3 | ok |
| accent ink on accent | | 4.54 | 4.5 | AA |
| accent ink on accent-dim | | 5.74 | 4.5 | AA |
| accent against base surface | | 4.01 | 3.0 | ok |
| terminal text | | 12.05 | 4.5 | AAA |
| terminal cursor on background | | 8.13 | 3.0 | AAA |
| terminal ansi[1] | | 4.77 | 4.5 | AA |
| terminal ansi[2] | | 6.16 | 4.5 | AA |
| terminal ansi[3] | | 7.40 | 4.5 | AAA |
| terminal ansi[4] | | 5.89 | 4.5 | AA |
| terminal ansi[5] | | 5.36 | 4.5 | AA |
| terminal ansi[6] | | 7.02 | 4.5 | AAA |
| terminal ansi[7] | | 9.70 | 4.5 | AAA |
| terminal ansi[9] | | 6.23 | 4.5 | AA |
| terminal ansi[10] | | 8.20 | 4.5 | AAA |
| terminal ansi[11] | | 9.85 | 4.5 | AAA |
| terminal ansi[12] | | 8.13 | 4.5 | AAA |
| terminal ansi[13] | | 7.18 | 4.5 | AAA |
| terminal ansi[14] | | 9.43 | 4.5 | AAA |
| terminal ansi[15] | | 13.73 | 4.5 | AAA |
| editor comment | | 4.93 | 4.5 | AA |
| editor line number | | 3.99 | 3.0 | ok |
| editor placeholder on input | | 4.83 | 4.5 | AA |
| editor inactive tab on deep | | 5.79 | 4.5 | AA |
| editor button ink on accent | | 8.13 | 4.5 | AAA |
| spotify text on main | | 12.05 | 4.5 | AAA |
| spotify subtext on card | | 4.83 | 4.5 | AA |
| spotify subtext on main | | 5.78 | 4.5 | AA |
| spotify field subtext on main | | 7.22 | 4.5 | AAA |
| gtk ink on bg-0 | | 12.05 | 4.5 | AAA |
| gtk dim ink on bg-0 | | 7.56 | 4.5 | AAA |
| gtk ink on bg-1 | | 10.45 | 4.5 | AAA |
| gtk dim ink on bg-1 | | 6.55 | 4.5 | AA |
| gtk ink on bg-2 | | 13.28 | 4.5 | AAA |
| gtk dim ink on bg-2 | | 8.33 | 4.5 | AAA |
| gtk accent as link text | | 5.11 | 4.5 | AA |
| gtk ink on accent fill | | 6.99 | 4.5 | AA |
| gtk border against window | | 1.62 | 1.3 | ok |
colour that cannot break contrast
Spotify's field can take its hue from the album art. Recolouring naively
would undo all of the above the first time a yellow cover played: holding HSL
lightness constant lets relative luminance swing 1.70×
across the hue circle, because HSL lightness is not perceptual brightness.
So the tint rotates hue and saturation, then solves for the
lightness that reproduces the original WCAG luminance. Measured across every
hue at four saturations, the error is 0.000%. Contrast holds by
construction rather than by luck.