@radicool/throughline 0.19.0 → 0.20.0

package/scripts/README.md

@@ -10,9 +10,11 @@ tested here; copied verbatim by `token-crosswalk-builder` into the user's
 | `validate-crosswalk.mjs` | Resolve every `newToken` against the DTCG token source; assert resolved value == `newValue`, N/N. The CI gate. | `tokens:validate` |
 | `build-reverse-index.mjs` | Emit a `codeToken -> newToken` map from the crosswalk to semi-automate SCSS/Tailwind swaps. | `tokens:reverse-index` |
 | `guard-token-removal.mjs` | Grep `.ts/.tsx` (minus generated + tests) for about-to-be-deleted symbols; blocks cleanup until zero references remain. | run during the cleanup phase |
-| `validate-token-output.mjs` | Assert generated native token output matches its DTCG source: authored-unit fidelity, no leaked CSS syntax, no bare unit literals, no mode collisions. Fails when no emitted symbol matches a source token, and reports match rate, unparsed lines, and unemitted tokens on every run. | `tokens:validate-output` |
+| `validate-token-output.mjs` | Assert generated token output — Swift, Kotlin, or web CSS custom properties — matches its DTCG source: authored-unit fidelity and no mode collisions everywhere, plus no leaked CSS syntax and no bare unit literals in Swift and Kotlin. Fails when no emitted symbol matches a source token, and reports match rate, unparsed lines, and unemitted tokens on every run. | `tokens:validate-output` |
+| `validate-adherence.mjs` | Assert the code *consuming* a design system still adheres to it: every referenced component exists, every literal variant value is one the system declares, and no colour, spacing, radius or type literal duplicates a token that already holds that value. Fails when an enabled rule had nothing to check, so a green run always means something was verified. | `adherence:check` |
+| `lib/source-scan.mjs` | Shared source-tree walker (`walk`, `DEFAULT_EXCLUDES`, `SOURCE_EXT`) plus `normalizeName`, the display-name-to-code-identifier fold. Every gate that scans a consumer's repo reads it from here rather than carrying its own copy. | copied alongside `guard-token-removal.mjs`, and in the documentation set for `validate-adherence.mjs` and `verify-check.mjs` |
 | `lib/crosswalk.mjs` | Shared loader + structural validation for `crosswalk.json` (used by the validator and reverse-index). | copied alongside |
-| `lib/dtcg.mjs` | Shared DTCG flatten + `{alias}` resolution. Dual-node aware: a node carrying both a `$value` and children yields its own value **and** is descended into. Used by `validate-crosswalk.mjs` and `validate-token-output.mjs`. | copied alongside both |
+| `lib/dtcg.mjs` | Shared DTCG flatten + `{alias}` resolution. Dual-node aware: a node carrying both a `$value` and children yields its own value **and** is descended into. Used by `validate-crosswalk.mjs`, `validate-token-output.mjs`, `validate-adherence.mjs`, `verify-check.mjs`, and `lib/sd-native.mjs`. | copied alongside each of those |
 | `lib/sd-native.mjs` | The Style Dictionary native configuration as code: unit-aware dimension transforms, `color-mix` computation, dual-node preprocessing, platform assembly, and a per-mode source guard. Style Dictionary is a parameter, never an import. | copied alongside `validate-token-output.mjs` |
 | `lib/native-literal.mjs` | Shared grammar for "is this a well-formed Swift or Kotlin literal": parses rather than pattern-matches, so an unquoted string, a raw CSS function, or any other unanticipated case fails the same way. Used by `sd-native.mjs`'s output filter and by `validate-token-output.mjs`'s invalid-literal rule. | copied alongside `validate-token-output.mjs` and `lib/sd-native.mjs` |
 | `crosswalk.schema.json` | The finalized JSON Schema for `crosswalk.json` (contract + editor support). | copied beside `crosswalk.json` |
@@ -22,6 +24,10 @@ tested here; copied verbatim by `token-crosswalk-builder` into the user's
 | `lib/doc-record.mjs` | Canonical record load + `canonicalFingerprint` (sha256 over the record minus `provenance`). The fingerprint every surface is stamped with. | copied alongside docs-check.mjs |
 | `lib/doc-card-render.figma.js` | Figma renderer template for the doc card's `Usage` band and header. Inlined into `references/doc-card-builder.md`; never executed as a module. | plugin-internal (not installed) |
 | `lib/doc-card-plan.mjs` | Pure layout planner for the doc card's `Usage` band + `DOC_CARD_RENDERER_VERSION` (single source of the layout version). Inlined into `references/doc-card-builder.md`; imported by `docs-check.mjs`. | copied alongside docs-check.mjs; also inlined into the generated builder |
+| `verify-check.mjs` | The verification proof bundle: records each stage's entry, and re-derives what it can rather than trusting the record. Fails on an orphaned token, a component documented without its archetype's baseline interaction states, a name that drifts between the manifest, its record and its code surface, or a recorded result the rerun contradicts. | `verify:check` |
+| `lib/proof.mjs` | The proof store's vocabulary and mechanics: the stage list, entry validation, latest-wins merge, and the fingerprint the manifest pointer carries. | copied alongside `verify-check.mjs` |
+| `lib/component-states.mjs` | The archetype table and resolver behind `state-incomplete` — which baseline interaction states each kind of component owes, and when to abstain. | copied alongside `verify-check.mjs` |
+| `lib/contrast.mjs` | The WCAG contrast maths and the semantic colour pairs behind `color-contrast` — which text role must clear which surface, in every mode, and where the rule deliberately abstains. | copied alongside `verify-check.mjs` |
 | `build-doc-card-builder.mjs` | Generate `references/doc-card-builder.md` from the planner + the Figma renderer template (`lib/doc-card-render.figma.js`). `--check` gates CI. | plugin-internal (not installed) |
 | `build-native-adapter-config.mjs` | Generate `references/native-adapter-config.md` by slicing `lib/sd-native.mjs` on its `@doc-section` markers and interleaving each fragment under its prose. Fails when module code falls outside every section, so the doc cannot silently ship incomplete. `--check` gates CI. | plugin-internal (not installed) |
 
@@ -29,7 +35,7 @@ tested here; copied verbatim by `token-crosswalk-builder` into the user's
 registering them leaves a repo with a script on disk and no entry point, which
 is how a stale `docs:check` went unnoticed for a full release. Both
 `storybook-chromatic-builder` (first-time setup) and `/document-component`
-(freshness refresh) install the same five files and register the same three
+(freshness refresh) install the same twelve files and register the same five
 scripts:
 
 | File | npm script |
@@ -39,9 +45,29 @@ scripts:
 | `docs-lint.mjs` | `"docs:lint": "node scripts/docs-lint.mjs"` |
 | `lib/doc-record.mjs` | — (imported by the above) |
 | `lib/doc-card-plan.mjs` | — (imported by the above) |
+| `validate-adherence.mjs` | `"adherence:check": "node scripts/validate-adherence.mjs --root ../../apps --system ../.. --package <specifier> --tokens dtcg/tokens.json"` |
+| `lib/source-scan.mjs` | — (imported by the above) |
+| `lib/dtcg.mjs` | — (imported by the above) |
+| `verify-check.mjs` | `"verify:check": "node scripts/verify-check.mjs --root ../.. --tokens dtcg/tokens.json"` |
+| `lib/proof.mjs` | — (imported by the above) |
+| `lib/component-states.mjs` | — (imported by the above) |
+| `lib/contrast.mjs` | — (imported by the above) |
 
 A refresh that adds a file must also add its npm script; check `package.json`
-for all three every time, not just the file that changed.
+for all five npm scripts every time, not just the file that changed.
+
+`verify:check`, like `adherence:check`, carries placeholder paths the installing
+skill substitutes for the repo's real layout. Dropping `--tokens` rather than
+substituting it is how a repo ends up with a rule that never runs: with no token
+source there is nothing to read, so the gate reports both `orphan-token` and
+`color-contrast` as skipped on every run — two stop conditions disabled by their
+own registration.
+
+The registered form carries a single `dtcg/tokens.json`, and a system whose
+values span modes registers **one `--tokens` per mode file**, because each source
+file is its own mode. Registering a multi-mode system with a single `--tokens`
+flag leaves a script that checks Light and reports that it checked one mode —
+quieter than the dropped `--tokens` failure above it, and just as wrong.
 
 The crosswalk contract is documented in
 `${CLAUDE_PLUGIN_ROOT}/references/crosswalk-schema.md`.
@@ -52,15 +78,123 @@ The crosswalk contract is documented in
 node validate-crosswalk.mjs --crosswalk crosswalk.json --tokens dtcg/tokens.json
 node build-reverse-index.mjs --crosswalk crosswalk.json --out crosswalk.reverse.json
 node guard-token-removal.mjs --root . --symbols symbols-to-remove.txt
+node validate-adherence.mjs --root ../../apps --system ../.. --package @acme/ui --tokens dtcg/tokens.json
+node validate-token-output.mjs --source dtcg/primitives.json --source dtcg/semantic.dark.json --output css/tokens.css --platform shadcn --block .dark --min-match 1
+node verify-check.mjs --root ../.. --tokens dtcg/tokens.json
+node verify-check.mjs --record --stage component-builder --subject Button --entry entry.json
 ```
 
+`validate-adherence.mjs` takes every path explicitly because cwd is the package
+holding the script, not the repo root. `--system` has no default: defaulting it
+to `--root` resolves to a path that does not exist. `--tokens` is repeatable, so
+a system whose values span mode files passes each one. An alias resolves against
+every `--tokens` file, so a semantic file can point at primitives in another, and
+the report's `colour:` line counts the colour tokens it skipped as unresolvable or
+non-hex. Files inside the package
+that owns a `--tokens` file are not scanned when that package sits beneath
+`--root`, and the report prints an `excluded:` line naming it. A tag whose name
+starts with a built component's name and continues with a capital letter
+(`CardTitle` for `Card`) is read as part of that component, and the report lists
+each one on a `parts:` line. `--skip <rule>`
+switches a rule off entirely (a name that isn't a rule exits `2`, rather than
+skipping nothing), and a skipped rule is absent rather than inert, which
+is the supported answer for a repo the rule cannot apply to (a Vue, Svelte or
+Angular app has no JSX for the component rules to read). An Angular `.html`
+template is read through its styling attributes only: `style`, `class`,
+`ngStyle`, `ngClass`, the SVG colour attributes (`fill`, `stroke`, `stop-color`,
+`flood-color`, `lighting-color`, `color`), and their bindings (`[attr.fill]`,
+`[style.color]`). Text content, `data-*`, `href`, comments and unquoted values
+are not read. Colour is read from all of these. Dimensions are read only where a
+property name sits beside the value: `prop: value` in `style` or `ngStyle`, and
+an arbitrary-value class like `p-[12px]`. `[style.padding.px]="12"` is not.
+`--skip token-exists-for-dimension`
+is the answer for a system with no spacing, radius or type tokens, which
+otherwise fails as `dimension-rule-inert`.
+
+`validate-token-output.mjs` reads web output as CSS custom properties for
+`--platform shadcn`, `tailwind` and `vanilla-css`. `mui` exits `2`: a MUI theme,
+like a Tailwind v3 JavaScript config, has no custom properties to read, and
+isn't checked yet (#127). Web puts every mode in one file, so run the gate once
+per mode block, passing the sources that block was built from. `--block` names
+the block by its enclosing at-rules and selector, joined by single spaces:
+`:root`, `.dark`, `[data-theme="light"]`, `@media (min-width: 768px) :root`,
+`@theme inline`. A file with one block needs no `--block`. A file with several,
+or a `--block` that isn't there, exits `2` and lists every block with its
+declaration count, so the exact key is in the error. A build split across files
+passes each one as another `--output`: everything declared in any of them counts
+as declared, and a token declared in any block counts as emitted. Six rules fail
+a web run:
+
+- `unit-fidelity` — the value changed magnitude, or a ratio gained a unit, or a
+  length lost one (`16` → `16rem`, `1.1` → `1.1rem`, `16px` → `16`). `16` →
+  `1rem` passes.
+- `reference-fidelity` — a declaration's `var()`s don't name the tokens its
+  source references.
+- `dangling-reference` — a `var()` to a variable no `--output` declares, unless
+  the source wrote that `var()` itself.
+- `no-unresolved-reference` — a `{reference}` reached the CSS unresolved.
+- `invalid-value` — `[object Object]`, `NaN` or `undefined` was written into the
+  CSS.
+- `unverifiable-dimension` — a dimension came out in a form the gate can't
+  compare, so it was never checked.
+
+Nothing fails for being CSS: `var()`, `calc()`, `color-mix()` and units are all
+legal output. On `shadcn` and `tailwind`, a declaration with no source token
+whose whole value is a `var()` to a declared variable is an alias layer
+(`--background: var(--color-bg-canvas)`). The report counts aliases on their own
+line and leaves them out of the match rate, so `--min-match 1` still holds.
+
+`verify-check.mjs` has two modes. The **gate** — `--root <dir>`, repeatable
+`--tokens` and `--source`, repeatable `--skip` — reads the proof store at
+`design-system/proof/`, re-derives every check a stage recorded as `derived`, and
+fails on `orphan-token`, `state-incomplete`, `name-drift`, `color-contrast`,
+`proof-missing`, `proof-stale`, `proof-contradicted`, `nothing-verified`,
+`orphan-rule-inert` and `contrast-rule-inert`.
+`archetype-unknown` and `proof-unadopted` are informational. With no `--source`
+the walk covers `--root`; the package that owns a `--tokens` file is set aside
+either way, and the report prints an `excluded:` line naming it — without that,
+generated token output binds every semantic token to itself and `orphan-token`
+can never fire. The **recorder** — `--record --stage <name> [--subject <Name>]
+--entry <file.json>` — merges one entry into that stage's file, recomputes its
+fingerprint and stamps the manifest's `verification` pointer. Skills call it;
+nothing hand-writes the store or hand-computes a hash.
+
+`--skip <rule>` switches a rule off entirely, and a skipped rule is absent rather
+than inert. A name that isn't one of the four rules exits `2`: `colour-contrast`
+is a typo here, not a skip. With no `--tokens` there is no token source to read, so
+`orphan-token` and `color-contrast` are reported as skipped rather than passed.
+
+`color-contrast` compares the semantic colour pairs the system's own role
+definitions already promise — `text/onEmphasis` over `bg/emphasis`, each status
+text over its own status background, and so on. Each `--tokens` file is one
+**mode**, and a pair has to clear WCAG AA's 4.5:1 for normal text in every one of
+them: a system that passes in Light and fails in Dark fails. A pair whose roles
+are absent from a mode abstains rather than passing, which is why a run that
+recognised no role anywhere fails as `contrast-rule-inert` instead of reporting a
+clean sweep. `text/disabled` is excluded, because WCAG 1.4.3 exempts inactive
+components and a disabled role is deliberately low-contrast. A translucent
+foreground is composited over its background and compared; a translucent
+background is skipped and counted, because what sits behind it is a layout fact
+the token tier does not hold. Every number on the report's `contrast:` line is a
+pair, in the mode it occurred in. `--skip color-contrast` is the escape hatch for
+a system whose roles are named differently. The orphan rule counts
+a token as bound when its normalized key appears anywhere in a scanned file, so
+`color.bg.primary` is bound by a mention of `color.bg.primary.hover`: every miss
+is an orphan reported as bound, never a correct system failed. A `derived` check
+is one the gate recomputes off disk, and its recorded result is a cache that must
+agree — a disagreement is `proof-contradicted`. An `attested` check is an agent's
+live observation of something the CLI cannot read, printed informationally and
+never the reason a run passes. See
+`${CLAUDE_PLUGIN_ROOT}/references/proof-bundle.md`.
+
 Exit codes: `0` success, `1` validation/guard failure (mismatch, missing token,
 conflict, or remaining reference), `2` bad CLI arguments.
 
 ## How the skill installs these
 
 `token-crosswalk-builder` copies `lib/crosswalk.mjs`, `lib/dtcg.mjs`,
-`validate-crosswalk.mjs`, `build-reverse-index.mjs`, `guard-token-removal.mjs`, and
+`lib/source-scan.mjs`, `validate-crosswalk.mjs`, `build-reverse-index.mjs`,
+`guard-token-removal.mjs`, and
 `crosswalk.schema.json` into the user's `packages/tokens/scripts/` (schema beside `crosswalk.json`), then
 wires `packages/tokens/package.json`:
 
@@ -88,7 +222,7 @@ Run the suite from the repo root (no install step — uses only Node built-ins):
 node --test
 ```
 
-This auto-discovers every `**/*.test.mjs` recursively (31 tests). Don't use
+This auto-discovers every `**/*.test.mjs` recursively. Don't use
 `node --test scripts/` — a directory positional is treated as a test name on
 Node >=21 and errors; a `scripts/*.test.mjs` glob silently skips `scripts/lib/`.
 

package/scripts/build-doc-card-builder.mjs

@@ -130,7 +130,7 @@ if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href)
   });
   if (process.argv.includes('--check')) {
     let onDisk = null;
-    try { onDisk = readFileSync(OUT, 'utf8'); } catch (e) { /* missing counts as drift */ }
+    try { onDisk = readFileSync(OUT, 'utf8'); } catch { /* missing counts as drift */ }
     if (onDisk !== result) {
       console.error('✗ references/doc-card-builder.md out of date; run: node scripts/build-doc-card-builder.mjs');
       process.exit(1);

package/scripts/grep-color-usage.mjs

@@ -6,10 +6,17 @@
 // Usage:
 //   node grep-color-usage.mjs --root <dir> [--config <patterns.json>] [--out <counts.json>]
 //     patterns.json: { "<category>": { "files": "<regex>", "pattern": "<regex with g flag>" }, ... }
-import { readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs';
-import { join, relative } from 'node:path';
+import { readFileSync, writeFileSync } from 'node:fs';
+import { relative } from 'node:path';
 import { parseArgs } from 'node:util';
 import { pathToFileURL } from 'node:url';
+import { walk, DEFAULT_EXCLUDES, SOURCE_EXT } from './lib/source-scan.mjs';
+
+// This script has exported `walk` and DEFAULT_EXCLUDES since it was written;
+// keep that surface intact now that both live one file over. SOURCE_EXT is not
+// re-exported because it was never exported from here — import it from
+// lib/source-scan.mjs. `walk`'s second parameter is now an options object.
+export { walk, DEFAULT_EXCLUDES };
 
 // The five categories from the case study. Each: which files it applies to, and the
 // (global) match pattern. Tuned defaults — design-system-audit may override per repo.
@@ -36,33 +43,6 @@ export const DEFAULT_CATEGORIES = {
   },
 };
 
-export const DEFAULT_EXCLUDES = [
-  /(^|\/)node_modules(\/|$)/,
-  /(^|\/)generated(\/|$)/,
-  /\.generated\./,
-  /\.test\./,
-  /\.spec\./,
-  /(^|\/)__tests__(\/|$)/,
-  /(^|\/)dist(\/|$)/,
-  /(^|\/)\.next(\/|$)/,
-];
-
-// Source extensions worth opening at all (union of every category's `files`).
-const SOURCE_EXT = /\.(scss|sass|css|tsx?|jsx?|mjs|cjs|vue|svelte|html|svg)$/;
-
-export function* walk(root, excludes = DEFAULT_EXCLUDES) {
-  for (const entry of readdirSync(root)) {
-    const full = join(root, entry);
-    if (excludes.some((re) => re.test(full))) continue;
-    const st = statSync(full);
-    if (st.isDirectory()) {
-      yield* walk(full, excludes);
-    } else if (SOURCE_EXT.test(full)) {
-      yield full;
-    }
-  }
-}
-
 // Count matches per category in one file. A category contributes only if its `files`
 // regex matches this path. Returns { <category>: count } for every category key.
 export function scanFile(path, categories) {
@@ -82,7 +62,7 @@ export function grepColorUsage(root, categories = DEFAULT_CATEGORIES, excludes =
   const counts = {};
   for (const key of Object.keys(categories)) counts[key] = 0;
   const byFile = [];
-  for (const file of walk(root, excludes)) {
+  for (const file of walk(root, { excludes, fileFilter: SOURCE_EXT })) {
     const fileCounts = scanFile(file, categories);
     const total = Object.values(fileCounts).reduce((a, b) => a + b, 0);
     if (total > 0) {

package/scripts/guard-token-removal.mjs

@@ -7,34 +7,16 @@
 // Usage:
 //   node guard-token-removal.mjs --root <dir> --symbols <symbols.txt>
 //     symbols file: one symbol per line (blank lines and # comments ignored)
-import { readFileSync, readdirSync, statSync } from 'node:fs';
-import { join, relative } from 'node:path';
+import { readFileSync } from 'node:fs';
+import { relative } from 'node:path';
 import { parseArgs } from 'node:util';
 import { pathToFileURL } from 'node:url';
+import { walk, DEFAULT_EXCLUDES } from './lib/source-scan.mjs';
 
-export const DEFAULT_EXCLUDES = [
-  /(^|\/)node_modules(\/|$)/,
-  /(^|\/)generated(\/|$)/,
-  /\.generated\./,
-  /\.test\./,
-  /\.spec\./,
-  /(^|\/)__tests__(\/|$)/,
-  /(^|\/)dist(\/|$)/,
-  /(^|\/)\.next(\/|$)/,
-];
-
-export function* walk(root, excludes = DEFAULT_EXCLUDES) {
-  for (const entry of readdirSync(root)) {
-    const full = join(root, entry);
-    if (excludes.some((re) => re.test(full))) continue;
-    const st = statSync(full);
-    if (st.isDirectory()) {
-      yield* walk(full, excludes);
-    } else if (/\.tsx?$/.test(full)) {
-      yield full;
-    }
-  }
-}
+// This script has exported `walk` and DEFAULT_EXCLUDES since it was written;
+// keep that surface intact now that both live one file over. `walk`'s second
+// parameter is now an options object.
+export { walk, DEFAULT_EXCLUDES };
 
 export function scanFile(path, symbols) {
   const lines = readFileSync(path, 'utf8').split('\n');
@@ -51,7 +33,9 @@ export function scanFile(path, symbols) {
 
 export function guard(root, symbols, excludes = DEFAULT_EXCLUDES) {
   const findings = [];
-  for (const file of walk(root, excludes)) {
+  // .ts/.tsx is this guard's own contract, so the filter stays here rather
+  // than moving into the shared walker's default.
+  for (const file of walk(root, { excludes, fileFilter: /\.tsx?$/ })) {
     for (const hit of scanFile(file, symbols)) {
       findings.push({ file: relative(root, file), ...hit });
     }

package/scripts/lib/component-states.mjs

@@ -0,0 +1,56 @@
+// The archetype baseline for `state-incomplete` (`docs/specs/2026-09-12-verification-proof-bundle.md`,
+// step 3). Source of truth for the prose is `references/figma-component-standards.md:126-138`.
+//
+// `default` is deliberately excluded from every baseline below: documenting the
+// resting state is not documentation, and the Figma matrix requirement for it is
+// the executor's, not this table's. Conditional states (`loading`, `error`,
+// `success`, `selected`) are deliberately excluded too — whether one applies to a
+// given component is a design judgment, not something a baseline can assert.
+//
+// MAINTENANCE: a change to the prose baseline must change this table.
+
+import { normalizeName } from './source-scan.mjs';
+
+export const ARCHETYPES = ['button', 'input', 'choice', 'card', 'modal', 'badge', 'other'];
+
+export const BASELINE_STATES = {
+  button: ['hover', 'focus', 'active', 'disabled'],
+  input: ['hover', 'focus', 'disabled'],
+  choice: ['hover', 'focus', 'active', 'disabled'],
+  card: [],
+  modal: [],
+  badge: [],
+  other: [],
+};
+
+export const NAME_SYNONYMS = {
+  button: 'button',
+  input: 'input',
+  textfield: 'input',
+  textinput: 'input',
+  checkbox: 'choice',
+  radio: 'choice',
+  toggle: 'choice',
+  switch: 'choice',
+  chip: 'choice',
+  card: 'card',
+  modal: 'modal',
+  dialog: 'modal',
+  badge: 'badge',
+  tag: 'badge',
+};
+
+export function resolveArchetype(record) {
+  if (ARCHETYPES.includes(record.archetype)) return record.archetype;
+  const bySynonym = NAME_SYNONYMS[normalizeName(record.name)];
+  return bySynonym ?? null;
+}
+
+export function missingStates(record) {
+  const archetype = resolveArchetype(record);
+  if (archetype === null) return [];
+  const baseline = BASELINE_STATES[archetype];
+  if (baseline.length === 0) return [];
+  const recordedKeys = new Set(Object.keys(record.states ?? {}).map(normalizeName));
+  return baseline.filter((state) => !recordedKeys.has(normalizeName(state)));
+}

package/scripts/lib/contrast.mjs

@@ -0,0 +1,117 @@
+// The WCAG contrast maths and the semantic colour pair table behind the
+// `color-contrast` rule (`docs/specs/2026-09-12-token-contrast-validation.md`,
+// step 1). Source of truth for the prose contract is
+// `skills/token-builder/SKILL.md:250-265`.
+//
+// MAINTENANCE: a change to the semantic role set must change this table.
+
+export const AA_NORMAL_TEXT = 4.5;
+
+// `text/disabled` is excluded: WCAG 1.4.3 exempts inactive user-interface
+// components from the contrast minimum, and a disabled role is deliberately
+// low-contrast — gating it would fail correct systems.
+//
+// `bg/subtle` and `bg/muted` are deliberately not paired in v1 (Open
+// questions) — a system is free to use those roles for non-text surfaces, so
+// pairing them risks the first false failures in the table.
+//
+// `border/*` needs the 3:1 non-text threshold (WCAG 1.4.11) and is a separate
+// table; this one is text-on-surface only.
+//
+// One threshold is applied to every pair because a colour role does not say
+// what text size it is used at — `text/primary` is body copy as well as
+// headings, so 4.5:1 is the binding requirement for it anyway.
+export const CONTRAST_PAIRS = [
+  {
+    fg: 'color.text.primary',
+    bg: 'color.bg.default',
+    threshold: AA_NORMAL_TEXT,
+    why: 'the default reading pair; if this fails, body copy fails everywhere at once',
+  },
+  {
+    fg: 'color.text.secondary',
+    bg: 'color.bg.default',
+    threshold: AA_NORMAL_TEXT,
+    why: 'secondary text is still text, and still has to clear AA on the same surface primary does',
+  },
+  {
+    fg: 'color.text.link',
+    bg: 'color.bg.default',
+    threshold: AA_NORMAL_TEXT,
+    why: 'a link that fails contrast is a link nobody can find, regardless of colour meaning',
+  },
+  {
+    fg: 'color.text.onEmphasis',
+    bg: 'color.bg.emphasis',
+    threshold: AA_NORMAL_TEXT,
+    why: 'the role exists because it sits on the emphasis fill; that is the whole reason it is not `text/inverse`',
+  },
+  {
+    fg: 'color.text.inverse',
+    bg: 'color.bg.inverse',
+    threshold: AA_NORMAL_TEXT,
+    why: 'the inverse pair flips with the theme, and both sides have to keep clearing together',
+  },
+  {
+    fg: 'color.status.success.text',
+    bg: 'color.status.success.bg',
+    threshold: AA_NORMAL_TEXT,
+    why: 'a status text role exists to sit on that status\'s own background, not any other surface',
+  },
+  {
+    fg: 'color.status.warning.text',
+    bg: 'color.status.warning.bg',
+    threshold: AA_NORMAL_TEXT,
+    why: 'a status text role exists to sit on that status\'s own background, not any other surface',
+  },
+  {
+    fg: 'color.status.danger.text',
+    bg: 'color.status.danger.bg',
+    threshold: AA_NORMAL_TEXT,
+    why: 'a status text role exists to sit on that status\'s own background, not any other surface',
+  },
+];
+
+// WCAG 2.x sRGB relative luminance over 0-255 channels.
+export function relativeLuminance({ r, g, b }) {
+  const linearize = (channel) => {
+    const c = channel / 255;
+    return c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+  };
+  return 0.2126 * linearize(r) + 0.7152 * linearize(g) + 0.0722 * linearize(b);
+}
+
+// Takes two `#rrggbb` strings (no alpha; the caller composites first) and
+// returns the raw ratio, unrounded.
+export function contrastRatio(hexA, hexB) {
+  const lumA = relativeLuminance(parseHex(hexA));
+  const lumB = relativeLuminance(parseHex(hexB));
+  const lighter = Math.max(lumA, lumB);
+  const darker = Math.min(lumA, lumB);
+  return (lighter + 0.05) / (darker + 0.05);
+}
+
+// `#rrggbb` or `#rrggbbaa` → `{ r, g, b, a }` with `a` in 0-1. `null` for
+// anything else.
+export function parseHex(hex) {
+  if (typeof hex !== 'string') return null;
+  const match = /^#([0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/.exec(hex);
+  if (!match) return null;
+  const digits = match[1];
+  const r = parseInt(digits.slice(0, 2), 16);
+  const g = parseInt(digits.slice(2, 4), 16);
+  const b = parseInt(digits.slice(4, 6), 16);
+  const a = digits.length === 8 ? parseInt(digits.slice(6, 8), 16) / 255 : 1;
+  return { r, g, b, a };
+}
+
+// The `#rrggbb` of `fg` drawn over `bg` with src-over (`out = fg*a + bg*(1-a)`).
+export function composite(fgHex, bgHex) {
+  const fg = parseHex(fgHex);
+  if (fg.a === 0) return bgHex;
+  if (fg.a === 1) return fgHex.slice(0, 7);
+  const bg = parseHex(bgHex);
+  const mix = (fgChannel, bgChannel) => Math.round(fgChannel * fg.a + bgChannel * (1 - fg.a));
+  const toHex = (value) => value.toString(16).padStart(2, '0');
+  return `#${toHex(mix(fg.r, bg.r))}${toHex(mix(fg.g, bg.g))}${toHex(mix(fg.b, bg.b))}`;
+}

package/scripts/lib/dtcg.mjs

@@ -1,6 +1,7 @@
 // Shared DTCG reading: flatten a token tree to dot-paths, resolve {alias} chains.
-// Zero dependencies. Consumed by validate-crosswalk.mjs and validate-token-output.mjs,
-// and copied alongside both when a skill installs either gate.
+// Zero dependencies. Consumed by validate-crosswalk.mjs, validate-token-output.mjs,
+// validate-adherence.mjs, verify-check.mjs and lib/sd-native.mjs, and copied
+// alongside them when a skill installs any of those.
 
 const REF = /^\{([^}]+)\}$/;