Design tokens that survive a rebrand
13 October 2026 3 min read
A token system is only as good as its middle layer. Skip it and the first rebrand works, the first dark mode breaks, and nobody can say why.
- Design systems
- Tokens
- Theming
Most token systems are built to survive a rebrand. Few are built to survive a dark mode, a high-contrast theme and a second product line in the same week. The difference is one layer that people like to skip.
What the user sees
Order confirmed
Arrives Thursday. We will text you.
Brand and mode change values. Components never notice.
What the button resolves to
button.background
→ color.action
#3d6b4f
color.action
→ color.moss.500
#3d6b4f
Pick a brand, then tick Dark mode. Everything follows. Now tick Skip the semantic layer and switch brands again. It still works. Switch to dark mode and the button stays exactly as bright as it was on the light surface.
Three layers, three questions
Primitives answer "what values exist?". color.moss.500 is #3d6b4f. It has no opinion about where it is used.
Semantic tokens answer "what does it mean?". color.action is the colour of the thing you press. In light mode it points at moss.500, in dark mode at moss.100. This is where themes live.
Component tokens answer "where is it used?". button.background points at color.action. Only add this layer when a component needs to deviate. For most buttons, using the semantic token directly is enough.
The rule is that every reference goes down one layer and never skips one. A component never names a primitive.
What breaks when you skip the middle
If button.background points straight at moss.500, a rebrand is a one-line change in the primitives. That is the demo everyone shows in a pitch.
Dark mode is different. Nothing in the chain knows that the surface changed, because the only token that could know is the one that was skipped. You end up with a second set of overrides inside every component, written under deadline, and they drift.
/* skipped the middle: the component has to know about every theme */
.button { background: var(--moss-500); }
:root[data-theme='dark'] .button { background: var(--moss-100); }
/* with the middle: the theme changes the meaning, the component stays dumb */
.button { background: var(--color-action); }
:root[data-theme='dark'] { --color-action: var(--moss-100); }
Name by role, not by look
color-blue is a primitive. color-link is semantic. color-primary sits in between and causes arguments, because it describes importance rather than purpose. Prefer names that explain what a person is doing: action, danger, surface, surface-raised, text-subtle, border-focus.
A useful test: if the name would become a lie after a rebrand, it is a primitive wearing a semantic name. color-brand-green has to be renamed the day the brand turns orange.
Pairs, not singles
Colour tokens work in pairs. action goes with on-action: the text or icon that sits on top. If you only define the background, every component picks its own foreground and contrast becomes a matter of luck. Define the pair together and check the contrast ratio once, in the token file, instead of in every component.
Check the chain in CI
You can test this. Parse the token file and fail the build if a component token references a primitive, or if a semantic token has no value in one of the themes. It takes about forty lines and removes a whole class of review comments.
Take the working version
The demo above is a toy. This is the same system as files. tokens.json is the one place where values live. node build-tokens.mjs turns it into CSS variables for every brand in light and dark. The page switches with two attributes on <html>:
<html data-brand="ember" data-theme="dark">
Two scripts run the checks from the section before. lint-tokens.mjs fails if a component names a primitive colour or a semantic token has no dark value. check-contrast.mjs tests the text, button and surface pairs for every brand and mode. Run both before a rebrand ships.
The values are examples. Replace the colours, run the two checks and see which pairs your own brand fails. That list is usually the real work of a rebrand.
No wish to edit JSON by hand? The token generator takes a primary and a secondary colour and builds a one-brand version of the same kit around them. It darkens a colour only as far as white text needs, tells you what it changed, and hands you the zip.
The goal is not a clever naming scheme. It is that the person who rebrands in two years, or ships a theme next sprint, changes values in one place and nothing else.