# validate-design-md.mjs — the design.md system's validator + token emitter

**CLI:** `node validate-design-md.mjs <file|folder> [--mode admission|build|ship] [--json] [--emit]`
File mode validates one design.md. Folder mode validates every `.md` in the tree (skipping `SCHEMA.md`) plus `index.csv` integrity.
`admission` and `build` run the same checks; `ship` adds the dmv-11 drift check against a `design.tokens.css` beside the input file.
`--json` prints `{file, fails:[{id,detail}], warns:[{id,detail}]}` (array in folder mode). Exit 0 on pass (warns allowed), 1 on any FAIL.

**Emit:** `--emit` (single file) compiles the token artifact from the `yaml design-values` block to stdout — deterministic, byte-stable;
redirect to `design.tokens.css`. Shape: `:root, :root[data-theme="light"]` + `:root[data-theme="dark"]` blocks (specificity armor, both
0,2,0) carrying the 36 color roles as `--<role>`; the light block also carries `--font-display/sans/mono` (registered names quoted, with
fallback stacks), `--text-<step>-size/-line/-weight` (+ `-family/-tracking/-features`), `--radius-*`, `--shadow-*`, `--duration-*`,
`--ease-*`, and layout vars (`--space-base`, `--sidebar-width[-collapsed]`, `--topbar-height`, `--side-panel-width[-wide]`, `--content-max-width`).

**Fails (close the gate):** dmv-01 frontmatter strict, per-tier keys, id = filename · dmv-02 the 12 sections in order, non-empty,
plus trailing design-values block · dmv-03 value block parses as YAML · dmv-04 coverage: 36 roles × both themes, ramp, register-scope,
elevation, motion base, iconography, charts, layout · dmv-05 contrast on every declared pairing (body ≥ 4.5:1; primary/accent/
destructive/sidebar-primary fills ≥ 3:1, warn under 4.5) · dmv-06 no image reference anywhere · dmv-07 index.csv ↔ files, both
directions, no duplicates · dmv-08 registered font names + fallback stacks · dmv-09 no claude.md (any case) · dmv-10 project tier:
`primitives: nurix|native` + `source-package` · dmv-11 (ship) emitted artifact byte-matches recompilation.

**Warns (recorded, never close):** dmw-01 background in the anti-cream band (L 0.84–0.97, C < 0.06, hue 40–100) · dmw-02 neutral
surfaces pure gray (C < 0.005) or over-tinted (C > 0.015) · dmw-03 untinted black shadow above 0.15 alpha · dmw-04 ease-in entrance
or duration over its element-class budget · dmw-05 display face granted a data register · dmw-06 dark ladder steps < ~0.04 L or hue
drift · dmw-07 accent chroma delta between themes > 0.06.

Stdlib-only: vendors its own YAML-subset parser and oklch → sRGB → WCAG-contrast math. The exact contrast pair table, thresholds,
and emission order live in the script's header comment.