Design tokens that scale past one product

The first product is easy. Tokens are a list of colours and sizes, and everyone knows what they mean. The trouble starts with the second product, the first rebrand or the day someone asks for dark mode. This is how we structure DrumKit’s tokens so those days are a change of values, not a rewrite.

Introduction

A design token is a named decision: the colour of body text, the space between a label and its field, the radius of a card. The name goes into designs and code; the value lives in one place. Change the value and every screen follows.

That works beautifully until the names start describing values instead of decisions. A token called blue-600 can’t become green in a rebrand without lying. A token called text-link can, and nothing that uses it has to know.

We learned this the slow way. DrumKit’s first tokens were a palette with sensible names, and for two years that was fine. Then we launched a second product with its own brand colour, and a search for blue-600 across our code returned four hundred results. About half meant “the brand”. The other half just meant “blue”.

Fixing it by search and replace would only have moved the problem. The real question was what each of those four hundred places meant, and only a person reading the screen could answer it. So before we renamed anything, we changed how our tokens were organised.

Our fix was three layers, and every token in DrumKit now sits in exactly one of them.

The first layer is primitives: the raw palette, the spacing scale, the type sizes. They are named for what they are, like gray-900 or space-4, and nothing in a product uses them directly.

The second layer is semantic tokens, named for a decision: text-primary, bg-secondary, border-error. Each points at a primitive. This is the layer designers and developers use every day, and it is the layer a theme changes. Dark mode, for example, is the same semantic names pointing at different primitives.

The third layer is component tokens, used sparingly, for the rare decision that belongs to one component, like the height of a button. They point at semantic tokens, never at primitives, so a theme still reaches them.

Software and tools

Tokens are only useful if they arrive in code unchanged. DrumKit exports them as a standard JSON file every time a library is published, and our build turns that file into CSS variables and a typed list for code completion. Nobody copies a hex value by hand.

We also lint for the two mistakes that undo the layers: a product using a primitive directly, and a semantic token pointing at another semantic token. Both fail the build with a message that names the token to use instead.

Where to begin

If you are starting out or cleaning up, this is the order we would work in, based on the migration we ran across both products last year.

1. List every value your products use today, and group the duplicates.
2. Name the decision behind each group, and make those names your semantic tokens.
3. Point every semantic token at a primitive, then replace raw values in code, one screen at a time.

The migration took us eleven weeks, most of it the third step. It paid for itself the first time marketing asked for a seasonal colour on the website: one value changed in one file, reviewed in the morning and live after lunch.

The bigger payoff came later. When a customer asked for a high-contrast theme, we built it in a week, because it was only a new set of answers to questions the system already asked.