new-validator

1. 1
   Study the references

   Read the Registries section of CLAUDE.md, then one script of each shape: validate-doc-refs.mjs on its own, the generate-component-md.mjs pair, and validate-rendered-spacing.mjs for built HTML.
2. 2
   Decide the shape

   A validator checks a rule and fails the build. A generator writes a derived file and gets a validator that holds the file to its source. A countable fact usually wants a registry as well.
3. 3
   Decide where it runs

   What the script reads decides the slot. Source files go in the chain that runs before every build. Built HTML goes after the website build. A check against an earlier release needs the git tags. Anything that reads the network runs by hand, in no chain.
4. 4
   Makes the scriptWrite the doc block

   The script opens with its filename, what it guards and why a failure matters, and why it runs where it runs. Any exception lives there or in a named constant beside it, with a reason a stranger could check.
5. 5
   Follow the house conventions

   Collect every error before exiting, and make each one name its fix. Normalise Windows line endings once, on the read. Build paths from the script’s own location and compare them with forward slashes.
6. 6
   For a generator, compare bytes

   The generator exports its assemble function and writes only when run directly. Its validator regenerates in memory and compares with the file on disk, so a hand edit or a stale file fails.
7. 7
   Makes the chain entryWire it in

   Add it to validate-registry in the root package.json, generators ahead of validators. A website check also joins website/package.json. A post-build check joins verify and CI in the same change.
8. 8
   Makes the CLAUDE.md lineClose the loop and prove it fails

   Give the rule its line in CLAUDE.md. Run the script, break the rule on purpose to see the message, restore it, then run the whole chain. A check that cannot be made to fail is not guarding anything.

A hex code like #1A2B3C may live in one file, tokens-primitives.css. Every other tier reaches it through a token, so a theme can swap the value in one place. Two validators hold that line. validate-token-references.mjs fails a semantic token written as a hex instead of a var(). validate-raw-values.mjs reads every stylesheet the package ships and fails a hex in component CSS. Say one is typed into a component’s stylesheet. The next build fails with the file, the line and the value, and says what to do: use the token that owns it, or mark it ds-allow(color) with a reason when it is deliberately off the scale.

1 · In the repowhere a hex may and may not go

2 · The chainroot package.json

3 · What runs the chainevery build starts here

4 · The resultprinted by the script

palettePrimitivestokens-primitives.css · the hex lives here

sellSemantic tokenstokens-light.css · tokens-dark.css · var() only

cssComponent CSSsrc/components/ · src/chat/ · tokens only

flagds-allow(color)a deliberate exception, with its reason

ruleToken referencesscripts/validate-token-references.mjs

ruleRaw valuesscripts/validate-raw-values.mjs

account_treevalidate-registryprebuild · prestorybook · prebuild-storybook

webWebsite prebuildwebsite/package.json · leaves both out

fact_checknpm run verifythe local mirror of CI

CI library jobnpm run build

CI Storybook jobnpm run build-storybook

check_circlePassone ✓ line with the count checked

errorFailfile:line · the value · the fix

blockBuild stopsnothing ships

var()a hex herea hex fails it

removeZoom out50%addZoom infit_screenFit the whole mapopen_in_fullExpand the map

Each tier has one answer, and a script holds it. A var() fallback is a consumer’s override hook, so the raw values check reads past it.