Designing a token system that survives dark mode

Wed, 02 Sep 2026 00:00:00 +0000

Why tiers

A colour is not one value. The blue that fills a button is not the blue that reads as text on grey, and using either in the other’s place is how a design system ships something illegible.

The four tiers

Fill, on-fill, on-surface, and states. Every hue carries all four.

:root {
 --retro-primary: #0000aa;
 --retro-primary-fg: #ffffff;
 --retro-primary-text: #000080;
}

What it buys you

One class sets both a fill and the text colour that survives on it.

Painting the right theme before the first frame

Fri, 14 Aug 2026 00:00:00 +0000

A theme flash is not a rendering quirk. It is a page admitting that it decided what colour to be after it had already been drawn.

Do it in CSS

The dark palette is emitted twice: once for [data-theme="dark"], and once under @media (prefers-color-scheme: dark) for :root:not([data-theme="light"]). A visitor whose system is dark gets dark on the first paint, before any script has run — before the bundle has even been requested.

dark-mode on Retro Dispatch

Designing a token system that survives dark mode

Why tiers #

The four tiers #

What it buys you #

Painting the right theme before the first frame

Do it in CSS #

Why tiers

The four tiers

What it buys you

Do it in CSS