new-token

1. 1
   Read the checklist

   The How to Add a New Token section of CLAUDE.md is the list. The skill adds the detail it leaves out.
2. 2
   Decide the tier

   A primitive is a raw value. A semantic token is a role, and it points at a primitive through var(). Add a primitive only when no existing one fits.
3. 3
   Makes the tokenPut it in its category’s file

   Colour goes in both tokens-light.css and tokens-dark.css. Spacing, radius and the other sizes go in the light file alone. A colour that carries a state, such as a checked fill, also gets a system colour in tokens-forced-colors.css.
4. 4
   Check the prefix

   An existing prefix needs nothing. A new one fails generation until it is added to CATEGORY_PREFIXES, so the new category gets a home on the same day.
5. 5
   Makes the swatch, story and specGive it its documentation homes

   A row on the matching foundations page, an entry in the Storybook token docs, and a sentence in design.md on its role. The sentence never states a colour value, since design.md holds for every theme.
6. 6
   Package a TypeScript token

   Only for a shared constant like the timings in motion.ts: a published subpath, or an entry saying why it stays internal.
7. 7
   Verify

   Run npm run validate-registry, then the build. Commit every file the chain rewrites. Counts update themselves.

--color-action-primary-bg is the action colour. Its light value points at a primitive, its dark value at another step of the same ramp, and its forced colors value at the system highlight. Button’s CSS uses the semantic token, never the primitive. The registry, the resolved values and the DTCG files are written from the CSS on every build.

1 · The tiers, by handprimitive, semantic, component

2 · Documentation, by handwhere a reader finds it

3 · Every buildvalidate-registry

4 · Generatednever edited by hand

palettePrimitivetokens-primitives.css

styleLight valuetokens-light.css

styleDark valuetokens-dark.css

toggle_onForced colorstokens-forced-colors.css

widgetsComponent CSSButton.css

descriptionSpec sentencedesign.md

Storybook docTokens.stories.tsx

grid_viewSwatchfoundations/colour-mode

auto_awesomeGeneratorstoken registry · token values

ruleValidatorsreferences · parity · usage · mirrors

storageToken registrysrc/tokens/registry.json

data_objectResolved valuessrc/tokens/values.json

downloadDTCG filesone per theme and mode

var() onlyevery buildboth ways

removeZoom out50%addZoom infit_screenFit the whole mapopen_in_fullExpand the map

A build check fails the build the moment a home drifts. An audit home is checked when a drift audit runs.