Naming tokens so developers don’t hate you

The fastest way to lose a developer’s trust is a colour called purple-500 that is used for links, focus rings, a chart line and a warning, depending on the screen. Every change becomes a hunt, and every hunt ends with someone hard-coding a hex value.

Good token names stop that from happening. Here is the naming approach I use on every system now.

Name the role, not the colour

A token should say what it is for: text, text-muted, surface, line, accent, on-accent. When the brand colour changes, you change one value and every role follows. When dark mode arrives, each role gets a second value and nothing in the product code changes at all.

This site works that way. Four tokens hold the whole accent palette, so switching from violet to green is a five-minute job in light and dark.

Keep the list short

Every token is a decision someone has to make correctly. Twelve to sixteen colour roles cover most products I have worked on. When a team asks for a new one, I first ask which existing role is almost right, and why it isn’t. Half of the time the answer reveals a design problem rather than a missing token.

Write the pairs down

Tokens are used in pairs: text on surface, on-accent on accent, muted on surface-muted. I document every allowed pair with its contrast ratio in both themes. Developers love it, because they can check a pairing without opening a design file, and accessibility stops being a review comment at the end.

Name what a colour does, keep the list short and publish the pairs. Your developers won’t thank you in words, but they will stop hard-coding hex values, which is better. The same tokens power every page of this site.