| Layer | Example | Use when… | Avoid when… |
|---|---|---|---|
| Primitive | blue.600space.16 | You are defining raw palette, scale, or base material. | You are styling product UI directly. |
| Semantic | color.text.dangerspace.stack.md | You are naming product meaning independent of one component. | The meaning only exists inside one component. |
| Component | button.primary.bgalert.error.border | You are defining a component-specific decision or state. | The same meaning should apply across many components. |
Naming test
A good token name should survive a redesign. If the color changes from red to orange,
color.text.danger still makes sense; red.600 may not.Backend analogy
- Primitive: database storage type.
- Semantic: domain field meaning.
- Component: endpoint-specific response contract.