Design tokens that survive contact with an engineering team
A token system fails when it describes what a colour looks like instead of what it is for. The naming decision is the whole game.
Most design systems have tokens. Most design systems still drift. The gap between having tokens and having a system that holds is almost entirely about naming.
Three layers, not one
A token called violet-500 is a primitive. It is useful, and it should never appear in a component. What components consume is a semantic token — surface-raised, text-muted, border-interactive — which points at a primitive.
The third layer is component-scoped: button-primary-bg pointing at surface-accent. You do not need this layer until you have a component that genuinely diverges, and adding it prematurely doubles the maintenance for no benefit.
The test for a good token name
Change the brand colour from violet to green in your head. If a token name is now a lie, it was named after appearance instead of purpose. brand-purple fails. text-on-accent passes.
This sounds pedantic until the rebrand arrives, at which point it is the difference between an afternoon and a quarter.
One source, generated outward
- Tokens live in one JSON file that designers and engineers both edit.
- A build step generates the Figma variables, the CSS custom properties and the native platform files.
- Nothing is hand-maintained in two places. If it is, it will disagree within a month.
- The generated files are committed, so a designer can see exactly what shipped.
What we hand over
Not a Figma file. A token package, a component library with documented states, and a page in the repository explaining how to add a new token without breaking the pipeline. If the handover cannot be understood without a call, it is not finished.
