Design systems that survive developer handoff

A design system is not a Figma file. It is an agreement about names, and it survives exactly as long as both sides keep using the same ones.

Why systems drift

Drift starts with a single one-off. A designer needs a slightly darker green for one banner and picks it with the eyedropper. A developer needs 18px of spacing where the scale offers 16 or 20, and hard-codes it. Neither decision is wrong on its own. Six months of them, and the “system” is a folder of screenshots.

The root cause is almost always that the design file and the code have separate sources of truth for the same values. Two sources of truth is one too many.

Tokens first, components second

We start every system with a small, boring set of tokens — colour, spacing, radius, type scale — defined once and consumed by both sides under identical names.

@theme {
  --color-ink: #17251f;
  --color-muted: #5a655f;
  --color-accent: #1e3932;
  --color-hairline: #e7e3db;
}

If the design file calls it accent and the stylesheet calls it accent, a conversation about “the green” cannot go wrong. If one side calls it primary and the other calls it brand-600, every conversation about it is a translation.

Components come after. A component built before its tokens exist bakes in values that then have to be excavated later.

Keep the set small. A palette of eight colours that everyone uses beats a palette of forty that people pick from at random. Constraint is the feature.

The handoff ritual

Three habits do most of the work:

Build the shared pieces first, in code, together. Button, input, card, section heading. Reviewed on a real page in a real browser, not as a screenshot. Everything after that is assembly.

Name things after their role, not their appearance. hairline survives a rebrand; light-grey-border does not. accent survives; green does not.

Treat a new value as a bug report. When a design needs a colour or a spacing step the system does not have, that is information — either the system is missing something, or the design is drifting. Both are worth five minutes. Neither is worth an eyedropper.

None of this requires tooling beyond what you already have. It requires that both sides agree the token list is the contract, and that changing it is a deliberate act rather than a side effect.