Design tokens and component versions: interfaces you can rebuild

You may have been here. One day you need to make the site's primary colour a little darker, and you find the same blue in two hundred places. Some are buttons, some are links, some are just spots where a designer once thought blue looked nice. After the change there's always a corner you missed, or one you shouldn't have touched.

The problem isn't the colour. It's that none of those two hundred places ever said why they were that colour. Design tokens are a tool for answering that question.

A token is a named decision

The simplest description is that a token is a variable, such as "primary equals this blue". But if you think of it only as storing a hex code in a variable, you miss the most useful part.

A good token name describes a purpose, not an appearance. Canvas, body text, muted text, accent, focus ring, error surface, error text, saving, conflict: you can read these and know what each one is responsible for. Names like "blue 1" or "light grey 3" tell you the colour, not the decision.

When names describe purpose, the same value can legitimately appear in several tokens. White might be both the canvas colour and the text colour on an accent button. They match today. If tomorrow you want button text to be slightly warmer, you change one, and the other isn't dragged along.

In other words, tokens move design decisions out of a designer's head and into files. Files can be read, compared, traced and followed by AI. Decisions in someone's head can only be passed on by word of mouth, and they drift a little every time.

Three layers: raw values, meaning, components

We think about tokens in three layers.

• Raw values: plain colours, spacing and radius numbers, such as a particular white, a particular blue, 4px, 8px.
• Semantic tokens: names for purposes, such as canvas, body text, accent, error surface. Each picks a raw value.
• Components: buttons, fields, status notices, navigation and overlays. Components only reference semantic tokens, never hex codes.

The most direct benefit is that reskinning becomes a clearly bounded job. A dark mode means giving each semantic token a dark value. Making the same interface look like another brand means swapping the semantic layer and the outer frame. Sections and components don't change, so after a reskin you check the screens, not the logic.

A less obvious benefit is state. An interface isn't only "normal". It also has error, success, saving, conflict and disabled. Each state has its own text, surface and border colour, each a set of tokens. When states are treated as real design decisions rather than red text added at the last minute, "something went wrong" looks the same on every screen, and people understand it just as fast.

Same value, different decision

Next comes a deliberate choice that can look counter-intuitive.

We have an interface built mostly for reading and managing data. Its needs differ from ordinary web pages: denser information, finer hierarchy, more states. It uses its own independent set of tokens with its own naming. It doesn't mix in the site's base styles, and it doesn't create aliases saying "this equals that".

When you audit them, some values in that set turn out to be identical to the site's tokens. Both canvases are white; both accents are the same blue. The instinct is to merge them, let the data interface reference the site tokens, and maintain one less file.

We don't, because matching values only means they match today. The site's white was chosen for reading and breathing room. The data interface's white was chosen to keep hierarchy clear inside dense tables. If the site moves to a warmer off-white one day, the data interface shouldn't change along with it by accident.

So a mapping table records the relationship: which values are the same, and which belong only to the data interface. The table records; it doesn't link. If we ever want to merge, that's a separate, explicit decision, followed by a visual comparison to confirm the screens didn't change.

Components and tokens have versions

Tokens answer "why does it look like this?". Versions answer "when did it start looking like this?".

Our components and tokens are released in versions. When an interface needs a big change, such as a whole new visual vocabulary, we don't edit the existing version. We release a new candidate. The old version stays, and pages that depend on it keep working. The new one takes over gradually, after comparison and acceptance.

The key is rollback. If a problem appears after the new version goes live, we need to go back, and going back mustn't lose what people stored in the interface. To make that possible, old and new versions share the same storage contract: the same data location, the same way of identifying things. Switching versions changes the screens, not where the data lives.

It sounds cautious, but it's what lets us try things. Knowing we can always go back means new designs can be tested in real situations instead of staying in mockups.

If you can rebuild it, it's a system

Put these together and you get a practical ability: the interface can be rebuilt from files.

Tokens live in versioned files. Components reference tokens and are versioned too. Pages are assembled from registered sections, and page content is data, not code. Any clean machine with these files can put the whole interface back together, and it will look exactly the same.

That also makes checking possible. After every change, take screenshots at several widths in light and dark mode and compare them with the previous version. Each difference is either intended or something to fix. There's no grey zone of "probably fine".

For a small team, this pays off in unexpected moments. A new colleague taking over the interface doesn't need an oral history first; reading the token file tells them what each colour is for. An AI assistant asked to add a section can only use semantic tokens that already exist, rather than picking a hex code that looks close enough. The rules live in files, so people and AI follow the same ones.

When someone genuinely needs a new colour, the right move is just as clear: give it a name that describes its purpose, explain why existing tokens aren't enough, and add it to the semantic layer. Those extra minutes come back every time the interface changes.

In short

• A token is a named decision: names describe purpose, not colour. Components only reference semantic tokens, so a theme changes only the middle layer.
• Same value isn't the same decision. An independent interface keeps its own tokens, recorded in a mapping table rather than linked; merging needs its own decision and a visual re-check.
• Components and tokens are versioned. New versions sit beside old ones and share the same storage contract, so rollback never loses data.