Alias Token

Naming a value doesn't make the name say what the value is for. blue-500 tells you which color it is and nothing about where it belongs. So the same name ends up on the primary button, links inside body text, the selected row in a list, and the notification badge.

The problem appears when something has to change. Asked to darken only the link color, someone has to open each of the 140 places using blue-500 and decide which of them are links. Get one wrong and the button color moves too, and that usually surfaces after release. Adding a layer between the value and its purpose is the answer to exactly this.

Two layers, and screens only ever call the upper one.

1. The lower layer holds values. blue-500 holds #2F6BFF; that layer is the global token.
2. The upper layer points at the lower one under a usage name. color-accent-default points at blue-500, and buttons and links reference that name rather than blue-500.

Names get built from purpose, role, and state: color-background-danger, color-text-secondary, color-border-focus. Reading the name should be enough to know where the value belongs. A name nobody can place is worse than a raw hex value, because it hides the ambiguity instead of showing it.

Two different routes to a change open up. To darken only links, move what the link name points at to blue-600. To change every blue in the product, edit the value of blue-500 and every purpose pointing at it follows.

Dark mode is hard without this layer, because it works by binding one name to a different value per mode. color-background-default points at gray-0 in light mode and gray-900 in dark mode, and nothing above has to know which mode is active.

Keep the count deliberately small; thirty to fifty names is a comfortable ceiling for most products. Let the upper layer reach a few hundred names and choosing one means scanning a list, at which point people go back to typing values directly. A value used only inside one component doesn't get promoted here; it goes one layer further down as a component token.

"blue-500 is hardcoded here. Change it to color-accent-default."

Don't call the lower layer directly; use the usage name.

"Only the links need to darken, so it's one alias to move."

The change is a single line.

"I can't tell where this name gets used. Let's rename it by purpose."

The name isn't doing what the layer exists for.

Pagedeck built this layer late, while adding dark mode. Noa counted the places calling values directly and found 210, and grouping them under 34 usage names took a week. After that, Theo's work binding the dark values took two days.