Design tokens that survive engineering handoff

Every design system demo looks the same: a tidy palette, a Figma frame full of swatches, a JSON file with two hundred names. Then a developer asks for the hover state of a destructive button on a dark surface, and the whole thing folds like a paper chair. Tokens do not fail in the palette. They fail at the seams — naming, composition, and the moment of handoff.

Name the decision, not the color

The root mistake is naming tokens after what they look like instead of what they decide. blue-500 tells a developer nothing about when to use it; accent tells them exactly. We keep two strict layers: a primitive scale nobody references directly, and a semantic layer that maps decisions onto it.

/* primitives — private vocabulary */
--color-brand-500: #2e90fa;
--color-gray-900: #111827;

/* semantics — public decisions */
--color-accent: var(--color-brand-500);
--color-ink: var(--color-gray-900);
--color-line: var(--color-gray-200);

When the brand shifts, primitives change and semantics hold. When dark mode arrives, semantics remap and components never know. Every token a component touches should survive both events without a rename.

The four rules we never break

• No component references a primitive. Ever. The linter enforces it, not the style guide.
• Every semantic token must answer “when would I use this?” in one sentence — if the sentence needs the word “or”, split the token.
• States compose by suffix (accent-hover, not hover-blue): the base name carries the decision, the suffix carries the state.
• Tokens ship in the same PR as the Figma change. A token that exists in one tool is a rumor, not a system.

A token is a promise between two disciplines. If either side can break it silently, you do not have a system — you have a mood board.

Surviving the handoff

Handoff is where systems die because handoff is where the missing tokens surface. Our fix is unglamorous: the triplet test. Before any component ships, design and engineering walk its hover, active, and disabled states together, on light and dark surfaces. Five minutes per component. It has caught a gap every single time.