A design mockup usually arrives with swatches and spacing values attached. The moment it becomes code, though, those values scatter across the screen: once in the button, once in the link, once behind the badge. Six months later you decide to deepen the brand colour slightly, and nobody knows how many places hold that value.
Design tokens solve this with a name rather than a value. The difference between a list of colours and a set of tokens is not the colours — it is whether they are named.
A token is a name, not a value
A token is “a value, a name, and an agreement to use the name”. The third part is what matters. With a name but no agreement — the name used on some screens and the raw value typed on others — tokens become decoration: the scattering problem is untouched and you have simply gained a file.
So the real work of adopting tokens is not choosing names, it is removing literals. One rule expresses it: colour and spacing literals exist only inside the token file. Anywhere else, a value starting with # is a value that has not yet entered the system.
Name things on two levels
A single level runs out quickly. With only palette names (teal-500) you cannot distinguish “change the link colour” from “change the palette”; with only role names (--color-link) the same colour gets copied into ten roles and has to be edited ten times.
Name things by what they do, not what they look like. --color-green becomes a lie the day that colour turns blue, and because nobody renames tokens, the lie stays. --color-success remains true through any repaint.
Where tokens earn their keep in WordPress
A static site can survive without them. A CMS cannot, because at least three parties draw the screen: theme templates, content that editors assemble in the block editor, and output emitted by plugins. A designer cannot stand behind all three.
Tokens are the agreement that stays after the designer leaves the room. If the colours an editor can pick are exactly your token list, the screens they build stay inside the system even though nobody reviews them. Parts four to six of this series wire up precisely that.
For the wider relationship between theme structure and design, see the Themes & plugins archive; and if you would rather have this structure installed while an existing theme is cleaned up, it is part of our optimization program.
Next part
With naming settled, you need values worth naming. The next part builds a colour scale — deriving every variant a real interface needs from a single brand colour.