How do you organise primitive, semantic, and component tokens?

Separate raw choices, purposes, and component-specific rules to control the impact of changes.

Token layers separate available values from what those values are used for. This makes it easier to understand which parts will change when appearance is adjusted.

Keep these basics in mind

• Primitive tokens record raw choices, such as a particular blue, usually without a purpose.
• Semantic tokens name a purpose, such as the primary action background, and can refer to primitive tokens.
• Component tokens belong to a specific part, such as button padding. Avoid using them arbitrarily elsewhere.
• An alias refers to another token’s value. It records a relationship rather than copying a value twice.

See Spectrum’s token terminology and Figma’s variable management guide for layers and aliases.

Adjust a relationship

Illustrative references

These are teaching relationships, not the project’s configuration.

Walk through an example

The team wants a more prominent primary button while retaining the link colour. Both initially refer to one primitive blue. They change only the action reference to a suitable alternative. Links retain the original value. They then check both on actual backgrounds rather than changing the shared primitive directly.

Limits and common misunderstandings

Not every system needs three layers, and not every part needs a three-step reference chain. More layers increase complexity. Choose enough structure to explain purpose and control changes, and document the relationships.