new-token

Add a design token so it exists in every home the system requires — a token that exists only in CSS is incomplete.

When invoked

Use this skill when asked to add or change a design token or token family — phrases like "add a token", "add a --color-… token", "new motion duration", "extend the chart ramp".

Instructions

CLAUDE.md's How to Add a New Token section is the authoritative checklist — read it first and follow its numbered steps. This skill adds the operational detail the checklist compresses.

1. Decide the tier. A primitive (--primitive-* in tokens-primitives.css) is a raw value; a semantic token is a role. New roles reference existing primitives via var() — add a primitive first only when no suitable one exists. Semantic colour tokens must chain to a primitive or another --color-* token; scripts/validate-token-references.mjs fails the build on a literal.
2. Put it in the file its category lives in — SEMANTIC_FILES in scripts/generate-token-registry.mjs is the authoritative list of what the registry reads. Colour: both src/tokens/tokens-light.css and src/tokens/tokens-dark.css, always; the registry validator enforces light/dark parity for colour, so identical values in both is fine and a missing side is not. Shadow: both files too — the elevation tokens carry different values per theme — but parity is build-enforced for colour only, so a shadow token added to the light file alone ships silently unchanged in dark mode; check tokens-dark.css yourself. Spacing, radius, border, icon size, control height: tokens-light.css alone. A control-height step is also a row of CONTROL_HEIGHT_STEPS in website/src/lib/theme/theme-overrides.ts, which the density lever scales and scripts/validate-theme-mirrors.mjs holds to the primitives in both directions. Typography: tokens-typography.css. Motion: tokens-motion.css. Stacking (--layer-*): tokens-light.css, in its ladder lowest to highest, with a trailing comment saying what sits on the layer (/foundations/layout prints it; scripts/validate-stacking.mjs requires it and the order). Nothing but colour and shadow is theme-split; a typography or spacing token copied into tokens-dark.css registers from the light file anyway and leaves a dead duplicate no validator reports. A colour token that carries a state a reader must see (a checked or selected fill, a count, anything whose meaning is its fill) also needs a value in src/tokens/tokens-forced-colors.css, a system colour (Highlight, Mark…): high contrast modes flatten every other fill to the page, and design.md's Forced colors section owns which roles are re-pointed. The page-level check in scripts/validate-website-a11y.mjs (FORCED_CHECKS) proves the ones on the table bench; a new state outside it needs a row there.
3. Check the prefix. If the token starts a new prefix, generation fails until the prefix is added to CATEGORY_PREFIXES in scripts/generate-token-registry.mjs — deliberately, so a new category gets a display home at the same time. An existing prefix (--color-, --motion-, --radius-, …) needs nothing here; the registry regenerates on every build.
4. Give it its documentation homes (the build enforces the first, a drift audit catches the rest):
   • Colour tokens need a swatch on /foundations/colour-mode — build-enforced in both directions by scripts/validate-website-surfaces.mjs. The values those pages print beside a swatch are build-checked too (scripts/validate-foundation-mirrors.mjs), so a caption must state what the token actually resolves to. Other categories go on their matching foundations page (CLAUDE.md's checklist maps category → page).
   • The matching Storybook doc: src/stories/Tokens.stories.tsx, whose story exports are the list (spacing's story carries the control heights too); src/stories/Typography.stories.tsx for a type style (add it to the matching tier story, DisplayStyles, HeadingStyles or BodyTextStyles, and to AllStyles). A new type style also needs a TYPE_STYLES row in website/src/lib/theme/theme-overrides.ts (style, tier, weight, tracking): scripts/validate-theme-mirrors.mjs holds the table to the CSS in both directions and requires the display and heading tiers to hold one weight each, so decide the tier before picking the weight; a body-tier row is shifted by the body weight lever along with the paragraph, so its shipped weight is its distance from the paragraph's, not a fixed value.
   • A sentence in design.md recording the role and how it relates to its neighbours (never a colour value: design.md is theme-agnostic), in the section that owns the token's subject. If that section states the family's size in words ("a four-step size scale"), scripts/validate-design-counts.mjs holds the words to the token files, so a new step fails the build until the sentence moves with it.
5. A TypeScript-side token (a shared constant, like the JS timing constants in src/tokens/motion.ts) has packaging steps CSS tokens do not:
   • A subpath entry in SUBPATHS in scripts/package-manifest.mjs, mirrored by hand into the root package.json exports (scripts/validate-package-exports.mjs fails the build if they drift), plus a matching entry in vite.lib.config.ts.
   • Or, if it is internal-only, an entry in INTERNAL_MODULES in scripts/validate-package-exports.mjs with the reason.
   • If component code mirrors the token's value outside CSS (a var() fallback, a serialized config), route the mirror through a validator so it cannot drift — the chart palette guard in scripts/validate-token-references.mjs is the pattern to copy.
6. Verify: npm run validate-registry must pass end to end (it regenerates src/tokens/registry.json, src/tokens/values.json with the DTCG files under website/public/schema/tokens/ (scripts/validate-token-values.mjs holds them; CLAUDE.md's How to Add a New Token step 5 says what fails when a token has no family or its value no mapper) and the other derived surfaces that carry token names or values, the consumer skills' token reference among them, and re-checks every home; the generator scripts at the front of the validate-registry entry in the root package.json are the authoritative list, so commit every file the chain rewrites), then npm run build for the type-check. Displayed counts update themselves — never hardcode one.

Guardrails

• Never hand-edit src/tokens/registry.json, src/tokens/values.json or website/public/schema/tokens/ — they regenerate from the CSS
• Never skip a tier: components reference semantic tokens, semantic tokens reference primitives
• A token with no consumer is not a token — if nothing will reference it, don't add it