Workshop reference

Design system token naming

Complete reference covering all six workshop layers — mental models, tiers, domains, anatomy, questions, and failure modes.

Core mental models

Names are rules, not labels

A label identifies a thing. A rule encodes where it lives, what it does, and how it relates to everything else.

label

blue

rule

color-action-primary-default

Names are coordinates

Built from consistent axes your whole team understands. Anyone who knows the axes can locate any token.

category role emphasis state scale

The naming formula

primitive  →  [category]-[family]-[scale]
             e.g. color-blue-500 · space-16

semantic   →  [category]-[role]-[emphasis]-[state]
             e.g. color-action-primary-default

component  →  [component]-[part]-[property]-[state]
             e.g. button-container-background-hover

Three-tier structure

Tier 1
Primitive — raw values, no meaning. Describes what a value is.
color-blue-600 · space-8 · font-size-14
Tier 2
Semantic — aliases a primitive and assigns purpose. Describes what a value means.
color-action-primary-default → color-blue-600
Tier 3
Component — scopes a semantic to one component part. Describes where a value is applied.
button-container-background-default → color-action-primary-default

Full chain example

color-blue-600 ← color-action-primary-default ← button-container-background-default

Four semantic naming domains

Scales

Ordered progressions of a value

100–900 xs · sm · md · lg · xl role-based

Emphasis

Hierarchy of visual weight

primary secondary tertiary subtle

Hierarchy

Structural levels (heading-1, body, caption)

display heading-1/2/3 body caption label

States

Conditions that change a value

default hover active focus disabled error selected loading

Component types

Simple

Single-purpose, minimal parts

badge · avatar · divider · tag

Sophisticated

Richer anatomy, one unit

button · input · tooltip · toggle

Compound

Assembled from simpler components

card · modal · nav bar · form

Composed

Full interface patterns

hero · data table · settings page

Anatomy formula — component token naming

[component] · [part] · [property] · [state]

Parts:    container · label · description · icon
          leading · trailing · track · thumb · indicator · overlay
Properties: background · foreground · text · border
            border-width · border-radius · shadow · spacing · size
States:   default · hover · active · focus · focus-visible
          disabled · selected · checked · error · success · loading

Naming template — the six questions

Who
Who is this token for?Designer · engineer · both · neither (internal alias)
What
What design decision does this token represent?The decision — not just the value
Where
Where is this token used?Global · contextual · component-scoped
When
When does this token apply?Which state or condition activates it
Why
Why was this name chosen over alternatives?Document the runner-ups and the reasoning
How
How does this token connect to adjacent tokens?What it references · what references it · its family

Four systems thinking questions — before naming anything

1 · Where in the hierarchy?

Primitive → what it is. Semantic → what it means. Component → how it's applied.

2 · What is this token's job?

One responsibility only. A token that does two things creates ambiguity.

3 · How does it relate to neighbors?

Does the family make sense read together? Is the progression legible?

4 · What changes vs. stays stable?

If the value changed tomorrow, would the name still be accurate?

Common failure modes to avoid

Naming from the value

Breaks when values change. Doesn't explain why.

red · #FF0000 · blue-500

Naming from a specific use case

Can't be reused. Creates token duplication.

checkout-button-color

Skipping tier 2

Component tokens reference primitives directly. Theming becomes impossible.

button-bg → color-blue-600

Naming without hierarchy awareness

Same pattern used for primitives and semantics. Nobody knows which tier they're in.

Documentation stack

Source of truth

Conventions, vocabulary, tier rules. Read this first.

Token catalog

Every token, its tier, reference, and status.

Decision records

Why names were chosen. Written at time of decision.

In-tool notes

Short signposts in Figma linking to deeper docs.