Name the role before the value
A raw color or spacing value describes implementation. A semantic token explains why that value exists: surface, border, primary action, muted text, focus ring, or destructive feedback.
Role-based names survive a theme change because they preserve intent while the concrete value moves.
Keep the system intentionally small
A token for every isolated pixel creates a second stylesheet that is harder to understand. Begin with the repeated decisions that shape the product, then add a token only when a stable role emerges.
- Define accessible foreground and background pairs.
- Use a deliberate spacing and type scale.
- Separate semantic roles from brand primitives.
- Document which component contracts consume each role.
Make tokens readable by tools
Machine-readable token metadata can expose type, allowed values, fallbacks, contrast relationships, and usage examples. An agent can then select a supported role instead of inventing a near-duplicate variable.
The visual system becomes easier to theme because its decisions are explicit, finite, and testable.