How the system works

The written model behind the swatches above. Read this to know which token to reach for and why.

Two-tier architecture

Primitive is what the value is (gray/950). Semantic is what it means / where it's used (text.primary). Components consume the semantic token, never the raw primitive — so a primitive can change (text.primary → gray/900) without touching a single component.

Naming dimensions

A semantic name can describe up to four things. Read a name as context.role — sometimes with emphasis or state.

Choosing a token

Don't start with “which shade?” Start with “what is this color doing?”

When to add a new token

• It represents a real UI role.
• It communicates meaning, emphasis, purpose, or state.
• Its purpose can be explained without a hex value.
• The name stays meaningful if the primitive changes.
• The interface actually needs it.
• You're defining a role — not reproducing the palette.

Avoid minting information/50…950 just because those shades exist. Prefer information.text, information.icon, information.border — purpose-driven, not scale-driven.

Primitive vs semantic

Registry principle

In the token registry the semantic layer stays independent of the primitive layer. Dots flatten to CSS variables — text.primary becomes --text-primary, warning.border-strong becomes --warning-border-strong. A component uses var(--text-primary), so the primitive underneath can evolve without a component-by-component rewrite.