Tokens are the API of design

A contract, not a file

When engineers talk about APIs, they mean a stable contract — a surface that both sides of an integration can depend on without needing to know what's happening underneath. The implementation can change, the internals can be refactored, but the interface stays predictable. Design tokens are exactly this, and the moment you start treating them that way, a lot of things about system architecture become much clearer.

The conventional framing is that tokens are a better way to manage design decisions — a single source of truth for color, spacing, and typography. That's true, but it undersells the structural implication. A well-defined token layer means design and engineering can move independently without drifting apart. A designer can rethink the entire color palette without breaking a single component, as long as the semantic token names stay stable. An engineer can refactor a component from scratch without touching any design decisions. The token layer is the seam — and seams are where good architecture lives.

Structure changes everything

Most token implementations I've encountered collapse two distinct layers into one: raw values and semantic meaning. A team defines `blue-500` and then uses `blue-500` directly in components. This works until you need to theme, rebrand, or support dark mode — at which point you realize you've encoded implementation details everywhere. The fix is a two-tier structure: primitive tokens that capture the raw palette, and semantic tokens that map meaning onto that palette. Components only ever reference semantic tokens. Primitives are the internals; semantics are the API.

Once you have that structure, theming becomes a matter of swapping the semantic layer, not touching components. Dark mode is a different mapping, not a different system. Brand updates propagate from one place. It sounds obvious in retrospect, but the number of systems that skip this step — because it feels like premature abstraction — is striking. It's not premature. It's the foundation that makes everything else composable.

Naming as design work

The hardest part of token architecture isn't the tooling. It's naming. A name like `color.background.surface.raised` is doing real semantic work — it's saying something about hierarchy and intent, not about a specific color. Getting those names right requires deep collaboration between design and engineering, because each side brings different intuitions about what the abstraction should express. That conversation is worth having slowly and carefully. The names you choose become the vocabulary of your system. Change them later and you'll feel it everywhere.