The test of a design token system is not how it looks in the documentation. It is what happens the day someone decides the brand should be green.
If the answer is "we change a few values and everything moves", the system was built properly. If the answer is "we open four hundred components and search for hex codes", then what you had was a spreadsheet with good intentions. I have been on both sides of that day, and the difference was decided long before the rebrand was announced.
The mistake is naming things after what they look like
Almost every token system starts the same way. Someone exports the palette, gives each colour a name, and ships it. blue-500. grey-200. red-600. It feels like progress because the hex codes are gone from the components.
They are not gone. They have been renamed. blue-500 is still a description of a colour, so a component that uses it is still saying "be this colour" rather than "be this kind of thing". When the brand changes, every one of those statements has to be re-evaluated by a human, because nothing in the name records why that blue was chosen.
The fix is old and well known and still skipped constantly: put a layer in between that names the job rather than the appearance.
Three layers, and what each is for
The structure that has held up for me looks like this.
The first layer is the raw palette. blue-500 lives here and is allowed to be a description, because that is all it is. Nothing in a component ever references this layer directly.
The second layer is semantic. color-action-primary, color-text-secondary, color-border-subtle. These describe roles in the interface. They point at the first layer, and they are the only thing a component is allowed to use.
The third layer, which many teams skip and later wish they had not, is the component layer: button-primary-background, card-border. These exist so a single component can deviate without either hardcoding a value or dragging the whole semantic layer with it.
The discipline that makes this work is boring and absolute: a component may only reference the second and third layers. The moment a component references blue-500, the abstraction is gone, and it is gone silently, which is why this needs to be a lint rule and not a code review convention.
Dark mode is the rehearsal for the rebrand
The most useful thing about supporting a second theme is not the theme. It is that it forces you to find every place where the appearance and the intention were conflated, months before a rebrand would have found them for you.
A token called grey-100 used as a card background reveals itself immediately, because in dark mode the card background is not grey-100 and it never will be. A token called surface-raised keeps working, because the name described the job.
If you want to know whether your token system will survive a rebrand and you do not have a rebrand handy, build the second theme. Every awkward case you hit is a case the rebrand would have hit too.
Tokens that describe relationships, not just values
The systems that age best encode more than colour. They encode the relationships that a designer would otherwise have to remember.
Spacing is the obvious one. A scale of space-1 through space-12 is fine, but the real value comes from a small number of named intentions on top of it: the gap inside a card, the gap between cards, the page gutter. Those three change together during a redesign in ways that a raw scale cannot express.
Type is the same. A system that exposes font-size-16 invites everyone to make their own judgement about what deserves sixteen pixels. A system that exposes text-body, text-caption, text-card-title makes the judgement once. It also means a type scale change is a change to three definitions rather than a hunt through every screen.
Contrast belongs in the tokens
The pair that gets separated most often is foreground and background. A token file that lets someone put text-tertiary on surface-accent without noticing that the result fails contrast has left the most important constraint in the system out of the system.
The practical answer is to define the pairs, not just the values. A surface token that carries its own legal text colours makes the accessible combination the easy one, and the illegal one hard to express. It is a small amount of extra structure that removes a whole class of review comment.
Where token systems actually break
In my experience the failure is rarely the token file. It is everything around it.
The handoff drifts. The design tool and the codebase each have a set of tokens, and they agree on the day they are set up. Six weeks later someone adds a colour in one place. Without a single source that generates both, this is not a risk, it is a certainty.
The names encode a hierarchy that changes. color-primary and color-secondary sound durable until the brand decides the secondary colour is now the one people should notice. Names that describe a role in the interface survive this. Names that describe a rank do not.
There is no way to deprecate. A token that turned out to be wrong cannot be deleted, because forty components use it, so it stays, and the system accumulates. Without a deprecation path with a real deadline, a token file only ever grows, and after two years nobody can tell which half is current.
Nobody owns it. The most common ending. The system was built during a project, the project shipped, and the person who understood it moved on. Tokens are infrastructure, and infrastructure without an owner degrades quietly until the day someone needs it to work.
What the rebrand day actually looks like when it goes well
The last one I went through took about a day and a half of real work. The palette changed, three semantic tokens were repointed, two components had genuinely brand-specific decisions in them that needed a human, and the rest moved on their own.
The reason it took a day and a half was not that the token system was clever. It was that for two years, every time someone had wanted to write a hex code in a component, the lint rule had stopped them. That is the whole trick. The structure matters less than the fact that nothing was allowed around it.
If you are starting one now, the highest leverage thing you can do on day one is not the naming scheme. It is the rule that makes the naming scheme mandatory, and the agreement that the rule is not negotiable when a deadline gets close. Every token system I have seen fail failed at exactly that moment.