A design system is the shared set of parts and styles a product is built from. A good way to judge one is not how its documentation looks, but what happens on the day someone decides the brand colour should change.
A design token is a name the whole product uses instead of a raw value. Not "this exact blue", but "the colour of the thing you press". Every button, card and menu (designers call them components) refers to the name, so changing the value behind it changes everything that uses it at once.
If the answer on rebrand day is "we change a few values and everything moves", the system was built properly. If the answer is "we open four hundred components and find every blue by hand", then the tokens were a list of colours rather than a system. 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 raw colour 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 checked by a person, because nothing in the name records why that blue was chosen.
The fix is well known and still often skipped: 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 refers to this layer directly.
The second layer is semantic, which here means named for a job rather than a look. 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 differ from the rest without either writing in a raw value or changing the whole semantic layer with it.
The rule that makes this work is simple and has no exceptions: a component may only refer to the second and third layers. The moment a component refers to blue-500, the layer in between is bypassed, and nothing shows it, which is why this needs to be an automatic check that refuses it, not a polite request in a review.
What belongs in which layer
The rule that has kept this consistent for me: a token moves one layer up the moment a second thing wants it for a different reason.
blue-500 is a raw value because nothing means anything by it.
color-action-primary is semantic because a dozen components want "the colour of
the thing you press", and they all want it to change together.
button-primary-background is a component token because the button, and only the
button, might need to differ from that.
The mistake in the other direction is real too. A team that opens the component
layer too early ends up with card-title-color, panel-title-color and
modal-title-color, all pointing at the same semantic token, each of them a
future edit that has to be made three times. If nothing has ever needed to
differ, the component token is speculative and should not exist yet.
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 makes you find every place where the appearance and the intention were mixed up, months before a rebrand would have found them for you.
A token called grey-100 used as a card background shows the problem immediately, because in dark mode the card background is not grey-100 and 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 one coming up, build the second theme. Every awkward case you hit is a case the rebrand would have hit too.
The theme is not the only axis
Once a second theme exists, teams usually discover a third axis they had not
planned for: density, or brand, or platform. The instinct is to multiply the
token names, and that is where a system starts to become unmanageable.
color-surface-raised-dark-compact is a sign that the naming has stopped working.
The structure that scales instead is that the names stay fixed and the
values are swapped by context. One set of semantic names, several value sets,
switched for the whole page at once. Every component keeps referring to
surface-raised and never knows which context it is currently in. Adding a
fourth context is then a new value set rather than a rename of everything.
Tokens that describe relationships, not just values
The systems that age best record more than colour. They record 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 margin. Those three change together during a redesign in ways that a plain scale cannot express.
Type is the same. A system that exposes font-size-16 invites everyone to make their own judgment about what deserves sixteen pixels. A system that exposes text-body, text-caption, text-card-title makes the judgment once. It also means a change to the text sizes is a change to three definitions rather than a search through every screen.
Contrast belongs in the tokens
The pair that gets separated most often is text and background. A token file that lets someone put text-tertiary on surface-accent without noticing that the result is too faint for many people to read has left one of the most important constraints out of the system.
The practical answer is to define the pairs, not just the values. A background token that carries its own allowed text colours makes the readable combination the easy one, and the unreadable one hard to express. It is a small amount of extra structure that removes a whole category of review comment.
Motion, corners and shadows
The timing of animations deserves the same named-by-intent treatment as colour, for reasons I have set out in when animation helps, and when it gets in the way. So do rounded corners and shadows: neither is expressive enough to be worth a decision per component, and both are the kind of thing a rebrand changes all at once.
Where token systems actually break
In my experience the failure is rarely the token file. It is everything around it.
Design and code drift apart
The design tool and the code each hold their own copy of the tokens, and they agree on the day someone syncs them. Six weeks later someone adds a colour in one place and not the other. A designer specifies a colour that does not exist in code, an engineer approximates it, and the approximation ships.
Of the five failures here, this is the one I would spend real engineering time on. The others are problems of discipline; this one is structural, and discipline does not fix it. One source generating both is the only version I have seen hold, and which direction it generates in matters much less than that there is exactly one. From the design tool to the code, the other way round, or one neutral file feeding both: all three are better than two hand-maintained lists that look the same.
The names encode a ranking 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
To deprecate a token is to mark it as on its way out, so people stop using it before it is removed. A token that turned out to be wrong cannot simply be deleted, because forty components use it, so it stays. Without a way to retire a name, 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 shared groundwork, and groundwork without an owner falls out of date without anyone noticing, until the day someone needs it to work.
A gap in the scale fails silently
This one cost me an afternoon recently. A spacing scale ran 1, 2, 3, 4, 5, 6, 7, 8, 10, 12, with no 9, for perfectly good reasons nobody had written down. A new component asked for step 9. Nothing warns you when you ask for a step that does not exist: the request is quietly ignored, and the element ends up with no width at all. Nothing showed an error, nothing flagged it, the element was simply not there.
The lesson is not "define every number". It is that a scale with a hole in it catches out whoever comes next, and the cheap fix is a comment in the token file saying which steps do not exist and why. A scale tells people what they can ask for, and the gaps are part of that.
What the rebrand day 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 pointed at new values, two components had genuinely brand-specific decisions in them that needed a person, 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 put a raw colour code in a component, the automatic check had stopped them. That is what made the difference. The structure matters less than the fact that nothing was allowed to bypass it.
If you are starting one now, the most useful 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 holds even when a deadline gets close. Every token system I have seen fail did so at exactly that moment.