How Do You Build Design Tokens That Survive a Rebrand?

How Do You Build Design Tokens That Survive a Rebrand?

Put a naming layer between your raw values and your components, so a rebrand changes what a name points at rather than where the name is used. A token set that survives a rebrand is one where nothing in the product refers to a colour by its colour.

We inherit a lot of design systems, and the token layer is where we can tell in about ten minutes how the next two years will go. The systems that age well all share one structural decision.

The standard behind this also finally settled recently, which changes what is worth building.

What Is a Design Token, Precisely?

A named design decision, stored in a format tools can read. The Design Tokens Community Group's format module is unusually concrete about this. Tokens are JSON, with a recommended media type of application/design-tokens+json and suggested file extensions of .tokens or .tokens.json.

The rule that defines a token is simple. An object with a $value property is a token, and an object without one is a group. A token also needs a $type, and the spec is strict here: if no explicit type has been set for a token, tools must consider the token invalid.

There is also $description for the explanation tools can surface as a tooltip or a code comment, and $deprecated, which accepts true, false, or a string explaining the situation. That last one matters more than it looks, and we come back to it below.

Why Do Most Token Sets Break at the First Rebrand?

Because the names describe the value instead of the job. A token called blue-600 is a label for a colour, so when the brand stops being blue, every component referring to blue-600 is now wrong, and the only fixes are to rename hundreds of references or to keep a token called blue-600 that renders green.

We have seen both. The second is worse, because it silently poisons every future conversation between design and engineering. Nobody trusts the names any more, so people start hard-coding values again, and the system quietly dies.

The same failure happens with sizes. A token called font-18 is a fact about today's type scale. When the scale changes, you are renaming or lying.

What Are the Three Layers, and Why Does the Middle One Matter?

Primitives, semantics, and components. Primitives are the raw palette, the full set of values with descriptive names. Semantics name the job, such as surface-default or text-critical, and point at primitives. Component tokens name a specific use, such as button-primary-background, and point at semantics.

The format supports this directly through aliases. A token's value can be a reference in curly braces, written as a path to another token, which resolves to that token's value. There is also a JSON Pointer form using $ref for reaching a specific property inside a token.

The middle layer is the one that makes a rebrand survivable, and it is the one teams skip because it feels like indirection for its own sake. It is not. It is the only layer where the meaning of your design lives. Primitives are just numbers, and component tokens are just plumbing. Change the semantics and the whole product changes coherently.

The test is blunt. If you deleted the primitive layer and replaced it wholesale, would anything in your components need editing? If yes, your semantic layer has holes.

How Should You Name Semantic Tokens?

After the role, the state and the context, never after the appearance. Something like text-on-accent tells you where it goes. Something like text-white tells you what it looks like today.

Keep the vocabulary small and boring, and write it down. The most common failure we see is not a bad naming scheme but three competing ones, added by different people in different quarters, none of them wrong and none of them compatible.

One useful constraint from the spec is worth adopting as a team habit. It says groups should not be used to infer a token's type or purpose. Your folder structure is organisation, not meaning. If the only way to know what a token does is where it sits in the tree, the name is not doing its job.

Groups do have one genuinely helpful feature here: a reserved $root name lets a group hold a base token alongside its variants, so you can have a default and its modifiers in one place without inventing a naming convention for it.

What Does the Standard Format Actually Give You?

Portability, and as of recently a stable target to build against. The Design Tokens Community Group announced its first stable version, 2025.10, on 28 October 2025, developed by over 20 editors and authors from organisations including Adobe, Amazon, Google, Microsoft, Meta, Sketch, Figma, Salesforce and Shopify, with more than 10 design tools supporting or implementing it.

The announcement describes it as a production-ready, vendor-neutral format, and names the capabilities that matter for this problem specifically: theming, modern colour spaces including Display P3 and Oklch, token relationships through inheritance and aliases, and cross-platform code generation.

What that buys you practically is that your token file stops being an export artefact of one tool. It becomes the source, and design tools and build pipelines both read it. That is the difference between a rebrand being a coordinated change to one file and being a migration.

It is a community group specification with open governance rather than a finished web standard, so expect it to keep evolving. Building on 2025.10 is still a much better bet than building on a tool's proprietary export.

How Do You Handle Themes and Modes?

Swap the primitive layer, keep the semantic names. Dark mode is not a separate design system, it is a different set of values behind the same set of meanings. If surface-default resolves to a light value in one theme and a dark value in another, every component works in both without knowing either exists.

This is also where teams discover whether their semantics are honest. Tokens named after appearance break immediately in a second theme, which is why dark mode projects so often turn into token refactors. The mode is not the problem. It is the audit.

Colour space support matters here too. Being able to express values in Oklch rather than hex makes it far easier to generate a consistent set of steps and to keep contrast relationships stable across themes, which is the part that usually breaks by hand. Our thinking on the palette itself is in choosing a website colour palette.

What Do You Do With Tokens You No Longer Want?

Deprecate them rather than delete them, and say why. The format has $deprecated for exactly this, and it takes a string, so the value can carry the replacement and the reason rather than just a flag.

Deleting a token breaks builds and makes people defensive about ever adopting the system. Deprecating one with a clear note lets teams migrate on their own schedule while everyone can see what the intended state is.

Then actually remove them, on a stated cadence, once usage hits zero. A deprecation list that never empties is just documentation of your regrets, and it is a reliable symptom of the wider problem we described in design debt.

How Do You Migrate an Existing Token Set?

Add the semantic layer without touching components first. Define the semantic names, point them at the primitives you already have, and ship that with nothing else changed. It is a no-op release, which makes it safe and easy to review.

Then migrate components to semantics one area at a time, starting wherever the next real project is happening so the work rides along with something funded. Do not attempt a big-bang rewrite of every reference, because it will stall halfway and you will be left with two conventions.

Track one number through the whole thing: how many component references still point directly at primitives. That is the only metric that tells you whether the migration is real, and it should only go down.

What Does Good Look Like Two Years Later?

A rebrand that is a pull request. New primitive values, unchanged semantic names, no component edits, a visual regression run, and a conversation about whether the contrast still holds rather than a three-month project.

That outcome is not achieved by clever tooling. It is achieved by one boring discipline held consistently, which is that nothing in the product ever refers to a value directly. Everything goes through a name that describes its job. The rest is plumbing, and the plumbing now has a standard.

If you are staring at a token set that will not survive the rebrand you know is coming, or building one from scratch and want it to age well, we are happy to work through it with you. Come and find us at phoenix.studio. Our broader view on the system around it is in building a web design system.