references/tokens.md
GitHubTokens
The defaults fit a hand-rolled app. When the repo already has a token source other tools read, keep its format, apply these rules inside it and record the departure. A foundation's own names are never renamed.
Layers
| Layer | Holds | Read by |
|---|---|---|
| Primitive | Raw values with palette names: gray.900, space.4 |
Semantic tokens only |
| Semantic | Roles: color.text.subtle, color.surface.raised, space.inset.md |
Components and product code |
| Component | A value one component themes apart from its role | That component only |
- Product code reads semantic tokens. A semantic token is an alias to a primitive, never a raw value.
- Start with zero component tokens. Delete one that only aliases a semantic token.
- Themes swap which primitive a semantic token points to. Every semantic token resolves in every theme. A theme the app ships on any route counts as shipped, even half built, and each value it lacks is a gate whose default is the nearest existing role.
Names
- Name by purpose:
color.text.danger, notcolor.red. The order is category, role, variant, state. - Pair every surface with its foreground (
surface.inverse,text.inverse) and check contrast on the pair. - One word per idea. If
subtlemeans lower emphasis in text, it means the same in borders. Do not also usemutedandsecondary. - Keep a working name even when you would have chosen another. Split a token only when the inventory shows it doing two jobs.
- A role that starts with its property word doubles the class (
text-text-muted).rule/doubled-utilityflags it. - No brand or product words in semantic names. Those are gates.
What never becomes a token
0, 100%, auto, currentColor. A value used once for one layout. Values set by content (an aspect ratio, chart colours from a scale). Third-party widget internals. Logo and illustration art. Math between tokens (calc(var(--space-inset-md) * 2)). A value within tolerance of an existing token maps to that token and makes no new one.
Tolerances
Tolerance applies only after purpose fits. These are defaults, so token-mapping and the merge decisions agree.
| Category | Limit |
|---|---|
| Colour | delta E OK 2 (under 0.5 is exact) |
| Spacing, size, radius | 2 px |
| Font size | 1 px |
| Line height | 0.05 as a ratio |
| Border width, weight, family, easing | none, each value is a choice |
| Opacity | 0.02 |
| Duration | 30 ms |
A merge inside tolerance is a decision. A merge past it is a gate whose default is the merge, naming the largest shift and the surfaces it touches.
Generating
Use the generator the repo has, or a short script. Output is sorted, the first line says it is generated and by which command, and a second run leaves no diff. Errors name the token path and the valid options. A brand value given as hex keeps its exact colour, so convert to another format with code, never by eye, and keep the hex in the description.
Do not reset a styling framework's whole palette to block palette classes, because stock components read black, white and transparent from it. rule/palette-use catches palette classes instead.
Motion
Name the presets before the first component, by job: instant (press), micro (hover), enter, exit, overlay, sheet, collapse, loader, follow (drag). Each has a duration, an easing, the properties it animates and its reduced-motion form.
- The surface's tier caps announce motion. High-frequency surfaces (nav, list rows, primary actions, menus) get
instantor first-open motion only. - Enters ease out, exits are shorter than enters, nothing enters from
scale(0), and only progress and loops are linear. - Animate
transformandopacityonly. Fix a motion finding with the first of these that clears it. Delete the animation, shorten or shrink it, fix its curve or origin, make it interruptible, move it totransformandopacity. - When the app has no motion for a job, the gate default is
instant.