Tokens: the Compiled Contract browser
Route: /tokens
What this page is
Tokens is the compiled contract of your design system: the single catalog of every token your code, Figma plugins, and AI tools read. Domain studios (Color, Typography, Motion, …) author values; the compiler resolves them into contract rows; this page is where you inspect and govern the result.
Three verbs describe everything you can do here:
| Verb | What it means | Where |
|---|---|---|
| Inspect | Search, filter, and trace any compiled token | The whole page |
| Govern | Review meaning, aliases, lifecycle, quality | Detail panel (read-only today; the meaning editor follows) |
| Delegate | Change a value, always in its source domain | "Change value in [domain] studio →" in the detail panel |
There is deliberately no value editing on this surface. A token's value belongs to the domain that authored it; the contract never forks from it.
Finding tokens
- Search matches name, description, and scale group. (
/focuses search.) - Domain facet ("compiled from") shows which foundation each token compiled out of: Color, Typography, Spacing, Radius, Shadow, Motion, or Custom.
- Source facet shows who authored the row: a studio (e.g. Color studio),
an import (CSS, Figma), or
Seedfor Day-0 defaults. - Status facet tracks AI-clarity (passing / warnings / errors) and lifecycle (deprecated).
- Views: List (default), Cards, Detail, and Table (side-by-side light + dark values).
Reading a token
Click any row to open the detail panel:
- Specimen: the value rendered (light + dark swatches for color).
- Value: read-only light/dark values, plus the alias chain when the
token points at a primitive (e.g.
theme-primary → {primary-9}). - Trace line: where the row came from (
color · primary scale · step 9), with the Change value in [domain] studio → link. - Quality: AI-clarity notes (duplicate values, missing descriptions).
- Governance: source, age, deprecation (successor + removal date), and Referenced by (every token that aliases this one; click to jump).
Editing meaning (the Govern verb)
Edit meaning → in the detail panel opens the meaning editor, a workspace room for what a token promises, never what it equals:
- Identity: rename (the breaking consequence is shown before you commit),
description, and name aliases (other names that resolve here, like
cta → primary). - Guidance: when-to-use / when-not-to-use lines and the AI guidance sentence agents read. Quality nudges suggest "use when…" phrasing.
- What agents read: a live preview of the compiled contract entry.
- Deprecate: names a successor and an optional removal date; the token keeps resolving until removal.
Every change is classified at the point of change in the bottom toolbar:
| Change | Classification | Why |
|---|---|---|
| Rename | major | A published name is the contract; consumers and dependent tokens must migrate |
| Alias added | minor | Additive; existing reads keep working |
| Alias removed | major | A published name stops resolving |
| Deprecation | minor, removal scheduled | Additive until removal; the successor is named |
| Description / guidance | patch | Documentation only |
| Value change | not possible here | Values change in their domain studio and classify per-diff at release time |
Renaming safely: the change-impact review
Because a published name is the contract, renaming opens a change-impact review before anything is written. It shows the blast radius (a risk tier and the artifacts that reference the token), then asks how to proceed:
- Rename and keep an alias (recommended). The old name stays resolvable as an alias that points at the new name, so consumers and generated code still reading the old name keep working. This is the backwards-compatible path.
- Rename without an alias. The old name stops resolving. You record a short reason (for example, "all consumers already migrated"), saved to the token's history alongside the rename.
- Cancel. Nothing changes.
If the impact data cannot be loaded, the review says so and does not present the change as safe: keep the alias, or record a reason to proceed.
The whole save (meaning fields, the rename, the alias, and the audit reason) commits together or not at all, and a rename is rejected if someone else renamed the token while you were editing.
FAQ
Where did the Token Reference page go?
It retired into this page. /tokens/reference links redirect here, and
?category= deep links still work.
Why can't I edit a value here? Values are authored in domain studios so there is exactly one source of truth. Use the "Change value in [domain] studio →" link; your edit recompiles into the contract on save.
What does "compiled N min ago" mean? The time of the newest change in the contract: the last time any studio save or import updated a row.
Why do some tokens say "seed"? They came with your design system's Day-0 defaults and haven't been re-authored through a studio yet. Save in the matching studio and the source becomes that studio.