Posts on Retro Dispatch

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.

Building a component that is square on purpose

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

One token

Every component routes its corners through --retro-border-radius, so one declaration rounds the whole framework.

The exceptions

Pills are named for their shape, and tables ignore border-radius outright because border-collapse: collapse merges their cell borders.

Why your div is not a button

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

A div with a click handler looks like a button and behaves like nothing.

What you lose

Tab order. Enter and Space. The implicit button role. The disabled state. Form submission. Focus visibility. Every one of those is a line of code you now own, and a line you will forget on the next component.

What it costs to get back

<div role="button" tabindex="0"
 onkeydown="if (event.key === 'Enter' || event.key === ' ') this.click()">
 Save
</div>

That is the minimum, and it still does not report a disabled state, still does not submit a form, and still needs event.preventDefault() so Space does not scroll the page.

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.

A type scale for interfaces that shout

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

Windows 95 shipped at 96 DPI with an 8pt UI font. Reproducing that number today produces text nobody can read on a phone, which is the difference between an homage and a re-enactment.

Steps, not sizes

--retro-font-size-xs through -3xl, all in rem, all derived from one body size. A component asks for a step, never a pixel value, so a site that raises the base size moves everything with it.

What we removed in 3.0, and why

Thu, 30 Jul 2026 00:00:00 +0000

The `!important` on the radius reset

It was load-bearing by accident. Dropping it woke thirty-one dormant radius declarations and rounded eleven components — which is why 3.0.0 was followed by 3.0.1 the same week.

A documentation renderer

Unmaintained since 2022, its output was never published, and it accounted for every security advisory in the dependency tree. The SassDoc comments stayed; only the renderer left.

Sign-in forms that behave when the network does not

Sat, 18 Jul 2026 00:00:00 +0000

The happy path of a sign-in form is four elements. Everything else is the interesting part.

The states worth building

Pending — the button is busy, not disabled-and-silent.
Rejected — the message is next to the field, not in a toast that vanished.
Rate-limited — say how long, not “try again later”.
Offline — the form should still hold what was typed.

The password toggle

Make it a real button with aria-pressed, keep the field type in sync, and never place it where it covers the text it reveals.

Posts on Retro Dispatch

Designing a token system that survives dark mode

Why tiers #

The four tiers #

What it buys you #

Building a component that is square on purpose

One token #

The exceptions #

Why your div is not a button

What you lose #

What it costs to get back #