Component Token

A two-layer token setup runs into a wall eventually. The lower layer holds value names like blue-600 and the upper layer holds usage names like color-action. In that arrangement, a request to make the button background one shade darker leaves color-action as the only place to edit.

Change it and badges, tabs, and links all move with it, because they were reading the same line. The conversation that follows is familiar: a designer says they darkened the button by one step, and whoever is reviewing asks why the tab underline and the notification badge changed too. Backing out of it usually means hardcoding a value on the button, and at that moment the reason for having tokens disappears — the button stops answering to the system that is supposed to describe it.

A component token solves this by inserting one more layer between them. Every component gets tokens named after itself, and the component looks at its own tokens instead of the shared ones.

The name starts with the component, and the value is a pointer to the layer above rather than a literal. button-primary-background carries both which component and which slot inside the name.

Three layers chain together.

1. A global token holds the value. blue-600 is #1D4ED8.
2. An alias token points at it under a usage name. color-action reads blue-600.
3. The component token points at the alias under a component name. button-primary-background reads color-action.

When only the button needs to be darker, line 3 gets repointed to blue-700. Badges and tabs still read color-action and stay exactly as they were.

Two lines are worth holding. Never write a literal value into a component token — always point at the layer above. And never use another component's token. If the tab borrows button-primary-background, fixing the button drags the tab along, and the problem you just removed is back with an extra layer in the way of finding it.

"Push this down to a component token and change the button only."

A proposal to solve it in the component-specific layer instead of touching the shared one.

"The token is named card-title-color and the modal is using it right now."

Pointing out that a component-specific token leaked into another component.

"We don't need two hundred component tokens. Keep the ones that actually differ."

Raising the cost side: another layer is another thing to maintain.

At Pagedeck, Noa created this layer while trying to darken the button background. Editing the shared token moved the tab underline and badge color too, so Noa opened component tokens for two components, the button and the text input, and nothing else. Theo wired up only those two and left every other component reading the shared tokens.