Global Token

There was a time when color values got typed wherever they were needed. The design file says #2F6BFF and the code says the same thing. Taken one at a time, nothing is wrong with that.

The trouble arrives when the value has to change. Theo got a request to darken the accent color, went looking through the code, and found the same value scattered across more than forty places. Three of them read #2F6CFF — one character off. Somebody had mistyped a paste or sampled the color with an eyedropper, and since no eye can tell those two apart, nobody had ever noticed.

Writing names instead of values is where design tokens start. A global token is the lowest of those names, the one attached to the value itself. Because naming begins here, there is exactly one place a value can live.

One name binds to one value. The name describes what the value is, not where it gets used: color-blue-500, space-8, radius-4. Whether that blue is the accent color or the warning color is not decided at this tier.

Collected together, they form a palette. One blue carries steps from 100 through 900, light to dark, and the grays follow the same pattern. Spacing gets about ten steps on a multiple of four, corner radii about four. The whole set can run into the hundreds, but once it is settled it rarely needs touching.

The rule is that screens never call these names directly. An alias token, which carries a usage name, points at the global token, and the screen calls the alias. That extra hop exists because the same usage needs different values in different conditions. In dark mode, background has to resolve to gray-900 instead of gray-50, and if screens call value names directly, every screen ends up carrying its own condition.

"That color isn't in the global tokens. We need to decide whether it goes into the palette at all."

An arbitrary value came in from a design file, so either extend the palette or use an existing step.

"Don't call color-blue-500 from the screen. It won't switch in dark mode."

A tier got skipped; route it through an alias instead.

"The global tokens are unchanged — I only edited the aliases. The palette wasn't touched."

What changed was the usage mapping, not the values themselves.

Pagedeck has barely opened this tier since the palette was settled once. When Noa shifted the brand color one step darker, the only edit was to color-blue-500, and the twelve aliases pointing at that name came along with it. Values that only ever appear inside one part are kept separately as component tokens, so the palette doesn't grow because of one component's needs.