Make your tokens human readable. Here's why

Why the name matters as much as the value

A token's value tells the code what to draw. Its name tells a person, or an agent, when to use it. If the name only describes the colour, the person picking it has to work out the purpose themselves, and different people work it out differently. That's how three slightly different error reds end up in one product.

It's even more important now that coding agents read your design system. When you ask your coding agent to build a screen for you, it's supposed to read your components and your tokens to decide how and what to build. A name like color.text.error leaves nothing to guess. A name like red-600 leaves it to the agent.

A naming pattern that holds up

The pattern I use goes from general to specific: category, property, role, and then state if there is one. So a primary button's background on hover becomes color.background.button.primary.hover. It's long, but nobody has to ask what it's for.

Keep the order the same everywhere: If one token is color.text.error and another is error.text.color, people stop trusting the pattern and start searching instead.
Spell words out: bg, txt, and pri save a few characters and cost a lot of questions. Write background, text, and primary.
Keep appearance words in the primitive layer only: orange.500 is fine as a primitive. In the semantic layer, name the purpose and point it at the primitive.
Name states the same way every time: hover, pressed, disabled, focus. Pick one word for each state and use it across every component.

The read-it-out-loud test

Here's the simplest check I know. Read the token name out loud to someone who joined the team last week. If they can tell you where it goes without opening the documentation, the name is doing its job. If they ask a question, the name needs work.

How to rename without breaking everything

You don't have to rename everything in one go. Create the new names, point the old names at them as aliases, and move components over one by one. Once nothing uses an old name, delete it. This way, the product never breaks, and the team can see progress every week.

Where to start

Export your tokens, go down the list, and mark every name you can't place without context. That list is your starting point, and it usually tells you quickly if this is an afternoon of cleanup or a proper project.