Design Tokens Are a Contract, Not a Theme

Most teams treat design tokens as a theming mechanism — a way to swap brand colors or support dark mode. That undersells them badly. Tokens are most valuable as a contract: the single, enforceable agreement between what design intends and what engineering ships.

## The drift problem

Every gap between the Figma file and the production DOM is a conversation that didn’t happen. A designer picks a 14px radius; an engineer hard-codes 12px; six months later nobody knows which is canonical. Multiply that by every spacing step, every shadow, every duration, and you have two sources of truth diverging in real time.

## Tokens as the source of truth

When tokens are the contract, the conversation changes. Design proposes a token change; engineering reviews it like an API change — because it is one. Renaming a primary color token breaks the contract the same way renaming a function parameter does. Suddenly design decisions get code review, and engineering changes to visual language get design review.

## What belongs in the contract

The strongest token systems encode decisions, not values. Not a raw pixel value but the semantic gap between form fields. Semantic naming means the contract stays stable even when the underlying values change — which is exactly when you need it most.

Teams that adopt tokens this way report the same thing: handoff friction collapses, because there’s nothing left to hand off. The file and the DOM are reading from the same document.