Naming Conventions

Two Patterns

The token system uses two distinct naming patterns, one per layer:

Key Rules

1. Never invent token names — use existing tokens from the design system source
2. Never hardcode color/spacing values — breaks theming and consistency
3. Use semantic tokens in components, not primitives
4. Primitives only when defining new semantics — reference via var()

Flat Token Alternative

In LLM-mediated workflows, a single-layer naming convention is also used:

--{component}-{part}-{state}

--button-bg-rest
--button-bg-hover
--input-border-focus
--input-height-sm

See Flat Approach for when to use this pattern.