Read more notes

← All journals
August 9, 2026

Green means only what you measured

A bursar working in dark mode presses Ctrl+P on a transcript and gets what looks like a blank page.

Browsers discard background colours when printing and keep text colours. Dark-mode body text in our system is #f1f5f9. On white paper that is nothing at all — and the bursar will conclude the export is broken, not the theme, because the screen looked fine a second ago.

The contrast checker passed. Three hundred and thirty-two colour pairs, zero failures. It measured light text on dark surfaces and dark text on light surfaces, and every combination cleared AA. It had no concept of a third rendering mode in which the background is thrown away and the foreground is not.

Two correct things combined into a failure. Dark mode is correct. A contrast checker that measures declared themes is correct. Nobody enumerated the mode where only half the declaration survives.

A passing check is a claim about the cases it enumerates, and its silence about everything else reads as approval.

The same shape turned up twice more in one session.

When I asked whether the component layer needed updating after the foundation had moved under it, every reference resolved — 186 of 186. Underneath that: buttons carrying drop shadows that contradicted an elevation rule written the same afternoon, and controls reading fixed heights instead of density, so on a short screen the toolbar would sit at 40px while table rows compacted to 32px. Grid and controls visibly out of line. The reference check verified that names matched. It cannot verify that meanings do.

And the checker’s first run caught four failures in the corrections themselves — values reasoned through carefully and got wrong anyway. Hand-reasoning about contrast is unreliable even when you are being deliberate about it.

The rhyme is what makes it structural rather than three bad days. Layering a system makes references verifiable and meanings unverifiable. Every boundary you add is another place where a name can stay valid while what it means moves.

The part I’d have got wrong twice

The instinct is to add more checks. That is half an answer.

The fix that actually holds is making the scope of a check visible at the point where someone would extend it. Our checker carries an explicit list of foreground/background pairs. Any pair not in that list is not being checked — and 354 of 354 will go on reading as total coverage long after it has stopped being total. So the list now says that about itself, in the file, next to the number.

The naive version enumerates the themes it knows about:

:root { @include light-tokens; }

@media (prefers-color-scheme: dark) {
  :root:not([data-theme='light']) { @include dark-tokens; }
}

[data-theme='dark'] { @include dark-tokens; }

The defensive version enumerates the modes, and print is one:

@media print {
  :root,
  [data-theme] {
    color-scheme: light;
    @include light-tokens;
    --context-elevation-overlay: none;
    --context-elevation-modal: none;
  }
}

DESIGNER BLUEPRINT

Draw a mode matrix, not a screen. One artefact per surface that leaves the building — transcript, fee receipt, register, report card — with a column for each rendering mode the browser can produce: screen light, screen dark, print, forced-colors.

Every cell shows the same surface fully rendered, not a swatch. The print column must show backgrounds discarded and text colours retained, because that is what the printer does and it is the cell nobody draws. The forced-colors column must show shadows gone, so any boundary carried only by a shadow is visibly missing.

Mark each cell owned or unowned. An unowned cell is not a gap in the design; it is a mode currently shipping undesigned.

A green check tells you what it looked at. It never tells you what it didn’t.