Types of tokens
Token layers describe how close a value is to a raw design primitive or to a specific interface decision.
Each source entry uses the DTCG $value and $type fields. The site’s kind and
visibility fields add governance metadata: kind describes the layer and
visibility determines whether a token belongs in the public authoring API.
Current layers#
| Layer | Role | Current status |
|---|---|---|
| Primitive | Raw reusable values with little context | Exists for colour palette values, fonts, type scale, space, and layout |
| Scale | Ordered values that establish rhythm or hierarchy | Exists for type steps and spacing |
| Semantic | Values named by purpose rather than appearance | Active; interface colours resolve to named color.palette.* primitives |
| Component | Values scoped to one component or element | Not created yet |
Primitive and scale tokens keep foundations consistent. Semantic tokens make the interface easier to theme because the name describes the role, not the literal value. Component tokens should appear only when a component has a reusable styling contract that cannot be expressed by an existing foundation or semantic token.
Current alias resolution#
The named color.palette.* tokens own colour literals. Semantic tokens such as color.ink, color.accent, and color.neutral.500 reference them with Style Dictionary syntax: "{color.palette.near-black}" or "{color.palette.neutral.500}".
outputReferences: true preserves that relationship in generated CSS: --color-ink resolves through --color-palette-near-black instead of repeating its literal. The generated colour cards resolve references before calculating contrast, so their WCAG values remain trustworthy.
Palette literals use visibility: internal: generated aliases may depend on them, but authors use the semantic token in CSS and Tailwind. The category reference table shows only public tokens and includes each alias’s resolved value for inspection.
Future layers#
A theme should become a collection of token values only when the site actually needs more than one visual mode or brand expression. Do not add another token layer because another design system has it; add it when the current site has a repeatable decision that needs that layer.