Name tokens by what they do

When we started Meter, the design system at Daluur, our first color tokens were named after colors: blue-500, gray-100, red-600. It felt neutral. It lasted until the first theme.

The app needed a dark mode. Screens used gray-100 for backgrounds, and in the dark theme those backgrounds had to be nearly black. We could redefine gray-100 as a dark color and let the name lie, or change every screen that used it. We did neither. We added a layer of role tokens: surface, surface-raised, text-muted, border-strong, action, critical. Screens use the roles, and each theme points them at different raw values.

Here’s what we kept from that change.

Name the role, not the swatch. Critical is red today. If the brand changes, it might not be, and the name still holds.

Use two layers. A small palette of raw values that only the system touches, and role tokens that everyone else uses. Product work uses role tokens only, and raw values stay inside the system.

Allow no synonyms. Danger, error, and critical meant the same thing in three products. We kept one.

Write down when to use it. Every token got one sentence of guidance, and those sentences settled more arguments than the names did.

Pick names people can say. If a name is awkward out loud, the team invents a nickname, and the nickname ends up in the code.

The switch took a sprint and touched most of the codebase. The dark theme would have cost more without it.

A shorter version of this note first ran on the Daluur design blog.