| name | spectra-tokens |
| description | Consume Spectra design tokens correctly. Use when styling any UI — picking a color, spacing, radius, shadow, z-index, or duration — to reference tokens instead of hardcoding values, in React/Chakra or Svelte or plain CSS. |
spectra-tokens
Spectra tokens have one origin (foundations/tokens/tokens.json) and three generated outputs. Always consume a generated output; never copy values out of the origin.
Choose the right output
- Any framework (Svelte, plain CSS, web components) →
foundations/tokens/dist/css-vars.css. Use var(--spectra-*). Core tier only.
- React / Chakra → the generated Chakra fragment; use semantic tokens as style props (
bg="bodyBg").
- Tooling / other agents →
foundations/tokens/dist/DESIGN.md.
The rule
- Semantic over primitive. Prefer
bodyBg, bodyText, bodyTextMuted, linesDefault, focusOutlineColor over gray.*/moon.*. Primitive scales are raw material.
- Never hardcode a value that has a token — colors, spacing, radius, z-index, shadow, duration.
- Dual-mode is free if you use tokens: CSS vars carry light/dark; Chakra semantic tokens carry
default/_dark. Don't hand-write a dark variant.
orange/lilac are deprecated.- If you keep needing a raw primitive for the same purpose, a semantic token is missing — flag it rather than hardcoding.
Naming map (CSS vars)
--spectra-color-<scale>-<step> (e.g. --spectra-color-moon-950), --spectra-color-<semantic> (e.g. --spectra-color-body-text-muted), --spectra-space-<n>, --spectra-radius-<name>, --spectra-z-<name>, --spectra-shadow-<name>, --spectra-duration-<name>, --spectra-easing-<name>.
Changing a token
Edit tokens.json, then pnpm generate:tokens and pnpm drift-check. Commit the regenerated dist/ with the change. Details: foundations/tokens/AGENTS.md.
