Tokens, not values

Primitive tokens are raw values: color-blue-500, space-400, radius-md. They have no semantic meaning. They're the alphabet.

Semantic tokens reference primitives and carry intent: color-bg-page, color-border-default, color-brand-primary, space-card-padding. They're the words.

Component tokens reference semantic tokens and describe specific instances: button-primary-bg, input-border-color, modal-shadow. They're the sentences.

Most systems botch the middle layer. They jump from primitive to component, and end up with a component layer that's actually a thin renaming of primitives. That defeats the point.

color-bg-default, not color-gray-50. The first survives a dark-mode swap; the second turns into a lie. Same for space-card-padding instead of space-16, and radius-control instead of radius-md.

Appearance-based names are fine at the primitive layer (color-blue-500 is a fact, not an opinion). They're poison at the semantic and component layers.

The W3C Design Tokens spec ($value, $type, $description, $extensions) is the lingua franca that lets tokens flow between Figma (via Tokens Studio) and code (via Style Dictionary, the token generator's exporters, or hand-written CSS variables).

If your tokens don't round-trip, designers and engineers maintain parallel sources of truth. That's a guaranteed drift.

Bump the major version when you remove or rename a token. Bump the minor when you add. Bump the patch when you adjust a value within the same name. Document deprecations in the changelog and keep aliases in place for at least one release.