Design tokens are the contract between design and engineering

Ask an engineer to implement a mockup and you're asking for a translation. The designer meant 24 pixels of spacing; the engineer read 22 from the inspector. The hover state existed in the designer's head. The disabled state existed nowhere. Multiply by forty screens and you get the familiar result: a product that resembles its design the way a photocopy of a photocopy resembles the original.

The fix isn't better inspection tools or longer handoff meetings. It's making the design itself machine-readable.

Three layers, one source of truth

A design token is a named decision. Not "this button is #E3A857" but: there is a color called accent, the button's background refers to it, and the hex lives in exactly one place. We structure tokens in three layers — primitives (raw values), semantics (what a value is for), and component tokens (how a specific part uses it).

The layering matters because change arrives at different altitudes. A rebrand swaps primitives; nothing else moves. A dark mode remaps semantics; components never know. A new button variant touches component tokens only. Each kind of change has a blast radius of one layer.

The contract in practice

On our projects, the token file is generated from the design source and consumed directly by the codebase — Tailwind theme, CSS variables, component library, all reading the same names. When a designer renames surface-raised or tightens the type scale, the pull request that updates the product is mechanical, reviewable, and boring. Boring is the goal. Drift hides in excitement.

Tokens also change design reviews. Instead of "that gray looks off," the conversation becomes "that's muted on surface — do we change the pair everywhere or is this a new semantic?" The vocabulary forces systemic thinking, which is exactly the thinking that keeps a two-year-old product coherent.

Where teams go wrong

The failure mode is tokenizing values without tokenizing intent — a palette of blue-100 through blue-900 with no layer that says what any of them are for. That's a paint catalog, not a system. The semantic layer is the contract. Skip it and every component negotiates its own treaty, and you're back to photocopies.

Name the decision, not the value. Everything else follows.