# Token model

## Layers

1. **Primitive** — raw values such as color ramps, type scales, and spacing intervals.
2. **Semantic** — intent-based aliases such as `color.text.primary` and `space.layout.gutter`.
3. **Component** — narrow decisions owned by a component, used only when a semantic token is insufficient.

## DTCG rules

- Store values and types in DTCG-compatible JSON.
- Prefer aliases over duplicated values.
- Define modes at the semantic layer.
- Give every non-obvious token a description.
- Deprecate with an explicit replacement; do not silently rename.

## Validation

- Reject unresolved aliases and circular references.
- Check contrast for semantic foreground/background pairs.
- Compare generated CSS, design-tool variables, and documented examples.