Why most token systems break

A token named blue-500 is a fact about the current brand. A token named color-action-primary is a fact about the product. When the brand changes, the first name becomes a lie you cannot fix without touching every consumer.

The three-tier model

The structure that holds up separates tokens into three layers, each of which may only reference the layer above it: primitives, semantics, and component tokens.

Naming rules that actually hold

A semantic name should answer three questions in a fixed order: what category, what role, what state. Consistency matters more than elegance, because a scheme you cannot guess is a scheme nobody uses.

Implementing in CSS custom properties

Custom properties map onto this model almost exactly, because they cascade and can reference each other. The primitive layer goes on the root, and the semantic layer references the primitives.

Theming without duplication

The mistake here is redefining primitives per theme. Redefine the semantic layer instead, and the primitives never move.

Handling the migration

Add the semantic layer alongside the existing tokens, pointing at the same primitives, then migrate consumers one component at a time.

What to measure

The health metric is not adoption percentage. It is the number of hard-coded values still present in component source, and that number should trend to zero.

Where teams get stuck

Almost always at the point where a semantic token is missing and somebody works around it rather than requesting one. Watch for hard-coded values clustering in a single component.