Naming design tokens so people can still use them two years later

A list before everything else

The registry is simply a written list of every token in the system, with its name, its value and a short note on what it is for. Where it lives matters less than the fact that it exists. It can be the first page of the Figma library or the opening section of the library’s own presentation site. What matters is that it comes before the components, because the components are built from it, and anyone who wants to understand the system should meet the vocabulary before the sentences.

It is tempting to skip this step and let the tokens live quietly inside variables and code. They work there, of course. But a token nobody reads is a token nobody really learns.

Reading it is how people learn it

The registry is not there just to exist. It is there to be read, and reading it is what makes it work. When designers, developers and analysts go through the list, the structure of the names settles into memory: the order of the parts, the meaning of each part and the logic that connects them. After a while, people stop looking names up and start predicting them, which is exactly the point.

That is why the order of terms in a name deserves real care. In my systems a name moves from the general to the specific: first the category, such as colour or spacing, then the role, such as surface, text or border, then the variant and finally the state, if there is one. A name like colour, text, muted, disabled reads almost like a sentence, and once you know the grammar you can build the next one yourself.

Semantics outlive values

The other rule is to name by purpose rather than appearance. A token called orange 500 tells you a colour; a token called action, primary tells you a decision. When the brand changes, the orange may become blue, but the decision stays the same, and every screen built on it changes correctly without anyone hunting through files. Raw values still belong in the system, but they sit underneath, and people rarely need to touch them.

What happens without one

Not long ago I was invited to work for a client with an enormous system, the kind every vendor has to plug into. Early on I asked, as politely as I could, whether they happened to have a token registry. The answer came with a sigh: no, they didn’t, but they really should have. I had to tell them, just as gently, that they also had names in the library that were simply wrong, and that those names could no longer be tidied up easily, because half a dozen teams and vendors had already built on them.

Nobody had made a dramatic mistake. Each name had seemed reasonable to whoever created it, on the day they created it. What was missing was a single written list that everyone read, which would have shown the drift long before it turned into structure. A registry costs an afternoon at the start. Untangling the names years later costs months, and it is never quite finished.

Two years later

The real test of a naming scheme comes long after launch, when new people join, new products are added and the original authors have moved on. A system with a clear, readable registry passes that test quietly. Newcomers learn the language in an afternoon, names stay consistent because everyone knows the grammar, and the tokens keep meaning what they were meant to mean. On my most recent large project, the registry was the first thing in the library, and it was also the page people returned to most.