@bounded-systems/conformance-kit 0.5.0 → 0.6.0

package/gates/opacity-contrast-gate.mjs

@@ -0,0 +1,191 @@
+#!/usr/bin/env node
+// Opacity-contrast gate — the CROSS-CUTTING guard of the Token Accessibility suite,
+// and the one that catches a whole class of real bugs (the bounded.tools opacity
+// regression): a colour token that clears AA at full strength but is APPLIED at a
+// reduced opacity — `opacity: .6`, `color-mix(… N%, transparent)`, an `--alpha`
+// token, an 8-digit `#rrggbbaa` — so the EFFECTIVE, composited colour silently
+// drops below contrast. Per-pair palette checks miss it because they test the
+// opaque token; per-page axe can miss it when the element isn't sampled.
+//
+// For every consumer-declared "opacity applied to a foreground" usage we composite
+// the foreground OVER its background at the stated alpha (Porter-Duff source-over,
+// opaque backdrop) and require the EFFECTIVE WCAG contrast to clear the floor:
+//   · text        ≥ 4.5:1   (WCAG 2.2 SC 1.4.3 AA)
+//   · large-text  ≥ 3:1     (SC 1.4.3 AA, large)
+//   · ui          ≥ 3:1     (SC 1.4.11 non-text)
+// We report BOTH the nominal (alpha = 1) ratio and the effective ratio, so the DROP
+// the opacity introduces is visible. A combo that drops below its floor → FAIL.
+//
+// HONEST SCOPE: this assumes the backdrop the consumer declares is the actual one
+// (the real backdrop is a DOM/stacking-context fact). If a translucent layer sits
+// over an unknown/photo background, contrast can't be guaranteed statically — the
+// gate flags such usages as `unknownBackdrop` for manual review rather than passing
+// them. Stacked translucent layers can be expressed by pre-compositing.
+//
+// Zero-dependency: colour-science primitives are imported from the palette gate.
+//
+//   node gates/opacity-contrast-gate.mjs <tokens.(json|css)> <usages.json>
+//
+// INPUTS:
+//   argv[2] / $OPACITY_TOKENS  the token map (DTCG json | tokens.css), same loader
+//                              as the palette gate.
+//   argv[3] / $OPACITY_USAGES  a `usages.json` the consumer authors:
+//     { "thresholds": { … }, "opacityTokens": { "muted": 0.6, … },
+//       "usages": [ { "fg":"token|#hex", "bg":"token|#hex",
+//                     "opacity": 0.6 | "{muted}",   // 0..1, or a ref into opacityTokens
+//                     "kind": "text"|"large-text"|"ui", "name?":"…",
+//                     "unknownBackdrop?": true } ] }
+//
+// Thresholds (config ⊕ env), fail closed:
+//   $OPACITY_MIN_RATIO_TEXT  (default 4.5)  SC 1.4.3 (AA, text)
+//   $OPACITY_MIN_RATIO_LARGE (default 3.0)  SC 1.4.3 (AA, large)
+//   $OPACITY_MIN_RATIO_UI    (default 3.0)  SC 1.4.11 (non-text)
+import { readFile, writeFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { parseHex, toHex, wcagContrast, loadTokens, resolveColor } from "./palette-gate.mjs";
+
+export const DEFAULT_THRESHOLDS = {
+  minRatioText: 4.5, // SC 1.4.3
+  minRatioLarge: 3.0, // SC 1.4.3 large
+  minRatioUi: 3.0, // SC 1.4.11
+};
+
+const round2 = (n) => Math.round(n * 100) / 100;
+
+/**
+ * Composite a foreground sRGB over a background sRGB at alpha (0..1).
+ * Porter-Duff "source-over" with an OPAQUE backdrop: out = fg·α + bg·(1−α),
+ * computed per channel in sRGB space. (sRGB compositing is what a browser's
+ * `opacity` / `rgba()` / `color-mix(… transparent)` effectively does for a single
+ * translucent layer over an opaque backdrop.)
+ * Ref: Porter & Duff (1984), "Compositing Digital Images"; CSS Color 4 alpha.
+ */
+export function compositeOver(fgRgb, bgRgb, alpha) {
+  const a = Math.max(0, Math.min(1, alpha));
+  return [0, 1, 2].map((i) => fgRgb[i] * a + bgRgb[i] * (1 - a));
+}
+
+export function ratioFloor(kind, t) {
+  if (kind === "ui") return t.minRatioUi;
+  if (kind === "large-text") return t.minRatioLarge;
+  return t.minRatioText;
+}
+
+/** Evaluate ONE opacity-on-foreground usage. `fgHex`/`bgHex` resolved. Pure. */
+export function evaluateUsage(usage, thresholds = DEFAULT_THRESHOLDS) {
+  const t = { ...DEFAULT_THRESHOLDS, ...thresholds };
+  const kind = usage.kind || "text";
+  const fg = parseHex(usage.fgHex);
+  const bg = parseHex(usage.bgHex);
+  const alpha = usage.opacity == null ? 1 : Number(usage.opacity);
+  const floor = ratioFloor(kind, t);
+
+  const nominal = wcagContrast(fg, bg);
+  const composited = compositeOver(fg, bg, alpha);
+  const effective = wcagContrast(composited, bg);
+  const pass = effective + 1e-9 >= floor;
+
+  const findings = [];
+  if (usage.unknownBackdrop) {
+    findings.push({ severity: "error", sc: kind === "ui" ? "1.4.11" : "1.4.3", msg: `translucent fg over an UNKNOWN backdrop — effective contrast cannot be guaranteed statically (declared backdrop ${toHex(bg)} assumed)` });
+  } else if (!pass) {
+    findings.push({ severity: "error", sc: kind === "ui" ? "1.4.11" : "1.4.3", msg: `effective contrast ${round2(effective)}:1 < ${floor}:1 at opacity ${alpha} (nominal ${round2(nominal)}:1)` });
+  }
+
+  return {
+    name: usage.name || `${usage.fg}@${alpha} on ${usage.bg}`,
+    fg: { ref: usage.fg, hex: toHex(fg) },
+    bg: { ref: usage.bg, hex: toHex(bg) },
+    kind,
+    opacity: alpha,
+    effectiveHex: toHex(composited),
+    nominalRatio: round2(nominal),
+    effectiveRatio: round2(effective),
+    floor,
+    drop: round2(nominal - effective),
+    unknownBackdrop: !!usage.unknownBackdrop,
+    findings,
+    passed: findings.length === 0,
+  };
+}
+
+/** Whole-suite evaluation → fail-closed report. Pure. */
+export function evaluateOpacityContrast({ usages = [], thresholds = DEFAULT_THRESHOLDS } = {}) {
+  const t = { ...DEFAULT_THRESHOLDS, ...thresholds };
+  const results = usages.map((u) => evaluateUsage(u, t));
+  const failing = results.filter((r) => !r.passed);
+  return {
+    passed: failing.length === 0,
+    thresholds: t,
+    summary: {
+      usages: results.length,
+      failing: failing.length,
+      unknownBackdrops: results.filter((r) => r.unknownBackdrop).length,
+      worstDrop: results.reduce((m, r) => Math.max(m, r.drop), 0),
+    },
+    usages: results,
+    // Envelope a future lone `opacity.effective-contrast` criterion can consume.
+    opacity: { effectiveContrast: failing.length === 0 },
+  };
+}
+
+/** Resolve an opacity value: a number 0..1, or `{name}` into opacityTokens. */
+export function resolveOpacity(ref, opacityTokens = {}) {
+  if (ref == null) return 1;
+  if (typeof ref === "number") return ref;
+  const m = /^\{(.+)\}$/.exec(String(ref).trim());
+  if (m) return Number(opacityTokens[m[1]] ?? 1);
+  return Number(ref);
+}
+
+/** Full run: load tokens + usages → resolve → evaluate. Exposed for tests. */
+export async function runOpacityContrastGate({ tokens, usages, thresholds = {} }) {
+  const map = typeof tokens === "string" ? await loadTokens(tokens) : tokens;
+  const spec = typeof usages === "string" ? JSON.parse(await readFile(usages, "utf8")) : usages;
+  const resolved = (spec.usages || []).map((u) => ({
+    ...u,
+    fgHex: resolveColor(map, u.fg),
+    bgHex: resolveColor(map, u.bg),
+    opacity: resolveOpacity(u.opacity, spec.opacityTokens || {}),
+  }));
+  return evaluateOpacityContrast({
+    usages: resolved,
+    thresholds: { ...DEFAULT_THRESHOLDS, ...(spec.thresholds || {}), ...thresholds },
+  });
+}
+
+function envThresholds() {
+  const t = {};
+  const num = (e) => (process.env[e] != null ? Number(process.env[e]) : undefined);
+  const set = (k, e) => { const v = num(e); if (v != null && !Number.isNaN(v)) t[k] = v; };
+  set("minRatioText", "OPACITY_MIN_RATIO_TEXT");
+  set("minRatioLarge", "OPACITY_MIN_RATIO_LARGE");
+  set("minRatioUi", "OPACITY_MIN_RATIO_UI");
+  return t;
+}
+
+async function main() {
+  const argv = process.argv.slice(2).filter((a) => !a.startsWith("--"));
+  const tokens = argv[0] || process.env.OPACITY_TOKENS;
+  const usages = argv[1] || process.env.OPACITY_USAGES;
+  if (!tokens || !usages) {
+    console.error("✗ opacity-contrast-gate: usage: opacity-contrast-gate.mjs <tokens.(json|css)> <usages.json>");
+    console.error("  (or set $OPACITY_TOKENS and $OPACITY_USAGES)");
+    process.exit(2);
+  }
+  const report = await runOpacityContrastGate({ tokens, usages, thresholds: envThresholds() });
+  if (process.env.OPACITY_REPORT) await writeFile(resolve(process.env.OPACITY_REPORT), JSON.stringify(report, null, 2) + "\n");
+
+  const s = report.summary;
+  const line = `opacity-contrast-gate: ${s.usages} usage(s) — ${s.failing} failing (worst drop ${s.worstDrop}:1)`;
+  if (!report.passed) {
+    console.error(`✗ ${line}`);
+    for (const u of report.usages) for (const f of u.findings) console.error(`  · ${u.name} [${u.kind}] ${u.fg.hex}@${u.opacity}→${u.effectiveHex}/${u.bg.hex}: ${f.msg}`);
+    process.exit(1);
+  }
+  console.log(`✓ ${line}`);
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main().catch((e) => { console.error("✗ opacity-contrast-gate: error —", e.stack || e.message); process.exit(1); });
+}

package/gates/pairing-extractor.mjs

@@ -0,0 +1,267 @@
+#!/usr/bin/env node
+// Pairing extractor — the COVERAGE engine of the Token Accessibility suite. The
+// contrast / CVD / APCA checks in the palette gate are only as complete as their
+// pairings list, and a HAND-MAINTAINED pairings.json misses combos — that's exactly
+// how the bounded.tools opacity-contrast regression slipped through. This tool
+// DERIVES the real foreground×background pairings from ACTUAL stylesheet usage, so
+// coverage is complete without hand-declaring every pair, then feeds them to the
+// palette gate and emits a human-readable PAIRING MATRIX (every fg×bg combo actually
+// used → WCAG ratio · APCA Lc · per-CVD ratios) so a reviewer can SEE what co-occurs
+// and that it's all clean.
+//
+// HOW (zero-dep, bounded, documented heuristic — no DOM, so no full cascade):
+//   1. Parse the stylesheet(s) into rules: selector-list → { color, background,
+//      border-color, outline-color, fill, stroke }, resolving `var(--token)` and
+//      literal colours against the token map.
+//   2. A rule that sets BOTH a foreground (color/fill/stroke/border) and a
+//      background → a DEFINITE co-occurrence (confidence "rule").
+//   3. A rule that sets only a foreground is paired with a background by STRUCTURAL
+//      containment: the nearest ancestor selector (by selector-string prefix, e.g.
+//      `.card` is an ancestor of `.card .title`) that declares a background; else
+//      the ROOT surface (`:root`/`html`/`body` background) (confidence "surface").
+//   4. `border-color`/`outline-color` foregrounds are `kind:"ui"`; everything else
+//      defaults to `kind:"text"` (a consumer override map can re-tag).
+//   5. Dedup by (fgHex,bgHex,kind). DECLARED pairings (an optional supplement) are
+//      UNIONED in, so you get extracted ∪ declared.
+//
+// HONEST SCOPE: containment-by-selector-prefix is a heuristic, not a real cascade —
+// it can pair a fg with a backdrop it never actually renders on (false positive,
+// SAFE: an extra clean pair) or, for deeply dynamic DOMs, miss a backdrop (covered
+// by also pairing against the root surface). Treat the matrix as "every combo the
+// stylesheet PLAUSIBLY puts together", reviewed by a human — superset coverage beats
+// a hand-list that silently omits the dangerous pair.
+//
+// Zero-dependency; colour-science + evaluation imported from the palette gate.
+//
+//   node gates/pairing-extractor.mjs <tokens.(json|css)> <style1.css> [style2.css …]
+//
+// INPUTS / ENV:
+//   $PAIRING_DECLARED   optional pairings.json to UNION in (declared ∪ extracted).
+//   $PAIRING_MATRIX     write the Markdown matrix here (else stdout).
+//   $PAIRING_REPORT     write the full JSON report here.
+//   $PAIRING_GATE       "1" → also run the palette gate over the union and exit 1 on
+//                       any failing pair (default: report-only, exit 0).
+import { readFile, writeFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { tokensFromCSS, loadTokens, resolveColor, evaluatePair, evaluatePalette, CVD_TYPES, parseHex, toHex } from "./palette-gate.mjs";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// 1. Minimal CSS rule parser (zero-dep) — selectors → colour-bearing declarations
+// ─────────────────────────────────────────────────────────────────────────────
+
+const COLOR_PROPS = {
+  color: "fg", fill: "fg", stroke: "fg",
+  "border-color": "ui", "border-top-color": "ui", "border-bottom-color": "ui",
+  "border-left-color": "ui", "border-right-color": "ui", "outline-color": "ui",
+  "background-color": "bg", background: "bg",
+};
+
+/** Strip comments + at-rule prelude noise, then yield { selectors:[], decls:{} } rules. */
+export function parseRules(css) {
+  const clean = css.replace(/\/\*[\s\S]*?\*\//g, "");
+  const rules = [];
+  // Flatten one level of @media/@supports by stripping the at-rule wrapper braces.
+  const body = clean.replace(/@(media|supports|layer)[^{]*\{/g, "");
+  const re = /([^{}]+)\{([^{}]*)\}/g;
+  let m;
+  while ((m = re.exec(body))) {
+    const selectors = m[1].split(",").map((s) => s.trim()).filter(Boolean);
+    if (!selectors.length || selectors[0].startsWith("@")) continue;
+    const decls = {};
+    for (const d of m[2].split(";")) {
+      const i = d.indexOf(":");
+      if (i < 0) continue;
+      decls[d.slice(0, i).trim().toLowerCase()] = d.slice(i + 1).trim();
+    }
+    rules.push({ selectors, decls });
+  }
+  return rules;
+}
+
+/** Resolve a CSS colour VALUE (`var(--t)`, `#hex`, or a token name) to #hex, or null. */
+export function resolveCssColor(value, map) {
+  if (value == null) return null;
+  let v = String(value).trim();
+  const varm = /var\(\s*--([a-zA-Z0-9-]+)\s*(?:,[^)]*)?\)/.exec(v);
+  if (varm) { try { return resolveColor(map, varm[1]); } catch { return null; } }
+  const hex = /#[0-9a-fA-F]{3,8}/.exec(v);
+  if (hex) { try { return resolveColor(map, hex[0].slice(0, 7)); } catch { return hex[0].slice(0, 7); } }
+  // bare token name
+  try { return resolveColor(map, v.split(/\s+/)[0]); } catch { return null; }
+}
+
+/** Find the token NAME whose value equals a hex (for readable matrix labels). */
+function nameForHex(map, hex) {
+  const h = hex.toLowerCase();
+  for (const [k, v] of Object.entries(map)) { try { if (toHex(parseHex(v)).toLowerCase() === h) return k; } catch {} }
+  return hex;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// 2. Extraction — rules → fg/bg pairings (pure)
+// ─────────────────────────────────────────────────────────────────────────────
+
+const ROOT_SELECTORS = new Set([":root", "html", "body", "*", ":where(html)"]);
+
+/** Is `anc` a structural ancestor of `sel` (prefix-of-compound heuristic)? */
+function isAncestorSelector(anc, sel) {
+  if (anc === sel) return false;
+  // descendant combinator: ".card" ancestor of ".card .title", ".card>.title", ".card.x"
+  return sel.startsWith(anc + " ") || sel.startsWith(anc + ">") || sel.startsWith(anc + " >") || sel.startsWith(anc + ":");
+}
+
+/**
+ * Derive pairings from parsed rules + token map. Returns
+ * { pairings:[{fg,bg,fgHex,bgHex,kind,source,confidence}], surfaces, foregrounds }.
+ * Pure.
+ */
+export function extractPairings(rules, map, opts = {}) {
+  // Per simple-selector record fg(s) and bg.
+  const flat = [];
+  for (const r of rules) {
+    let bg = null;
+    const fgs = [];
+    for (const [prop, role] of Object.entries(COLOR_PROPS)) {
+      if (!(prop in r.decls)) continue;
+      const hex = resolveCssColor(r.decls[prop], map);
+      if (!hex) continue;
+      if (role === "bg") bg = hex;
+      else fgs.push({ hex, kind: role === "ui" ? "ui" : "text", prop });
+    }
+    if (bg == null && fgs.length === 0) continue;
+    for (const sel of r.selectors) flat.push({ sel, bg, fgs });
+  }
+
+  // Root surface background(s).
+  const rootBgs = flat.filter((f) => f.bg && ROOT_SELECTORS.has(f.sel.split(/[ >:]/)[0]) ).map((f) => f.bg);
+  const defaultSurface = rootBgs[0] || opts.defaultBackground || null;
+
+  // Background-declaring selectors (surfaces) for containment lookup.
+  const surfaces = flat.filter((f) => f.bg).map((f) => ({ sel: f.sel, bg: f.bg }));
+
+  const pairings = [];
+  const seen = new Set();
+  const emit = (fgHex, bgHex, kind, source, confidence) => {
+    if (!fgHex || !bgHex || fgHex.toLowerCase() === bgHex.toLowerCase()) return;
+    const key = `${fgHex.toLowerCase()}|${bgHex.toLowerCase()}|${kind}`;
+    if (seen.has(key)) return;
+    seen.add(key);
+    pairings.push({
+      fg: nameForHex(map, fgHex), bg: nameForHex(map, bgHex),
+      fgHex, bgHex, kind, source, confidence,
+    });
+  };
+
+  for (const f of flat) {
+    for (const fg of f.fgs) {
+      if (f.bg) { emit(fg.hex, f.bg, fg.kind, f.sel, "rule"); continue; }
+      // containment: nearest ancestor surface
+      const anc = surfaces.filter((s) => isAncestorSelector(s.sel, f.sel));
+      if (anc.length) for (const a of anc) emit(fg.hex, a.bg, fg.kind, `${f.sel} ⊂ ${a.sel}`, "surface");
+      else if (defaultSurface) emit(fg.hex, defaultSurface, fg.kind, `${f.sel} ⊂ :root`, "root");
+    }
+  }
+  return { pairings, surfaces, defaultSurface };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// 3. Matrix — evaluate every extracted pair, render Markdown (pure)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Evaluate each pairing through the palette gate's per-pair check → matrix rows. */
+export function buildMatrix(pairings) {
+  return pairings.map((p) => {
+    const ev = evaluatePair({ ...p, fgHex: p.fgHex, bgHex: p.bgHex });
+    return {
+      fg: p.fg, bg: p.bg, fgHex: p.fgHex, bgHex: p.bgHex, kind: p.kind,
+      confidence: p.confidence, source: p.source,
+      wcag: ev.wcag.ratio, wcagPass: ev.checks.wcagAA,
+      apca: ev.apca ? ev.apca.absLc : null,
+      cvd: Object.fromEntries(CVD_TYPES.map((c) => [c, ev.cvd[c].ratio])),
+      cvdPass: ev.cvd.pass,
+      passed: ev.passed,
+    };
+  });
+}
+
+/** Render the matrix as a Markdown table. Pure. */
+export function renderMatrixMarkdown(matrix) {
+  const head = `| fg | bg | kind | WCAG | APCA Lc | ${CVD_TYPES.map((c) => c.slice(0, 4)).join(" | ")} | pass | conf |`;
+  const sep = `|${"---|".repeat(6 + CVD_TYPES.length)}`;
+  const rows = matrix.map((m) =>
+    `| ${m.fg} | ${m.bg} | ${m.kind} | ${m.wcag}:1 | ${m.apca ?? "—"} | ${CVD_TYPES.map((c) => m.cvd[c]).join(" | ")} | ${m.passed ? "✓" : "✗"} | ${m.confidence} |`);
+  return [`# Pairing matrix (${matrix.length} extracted fg×bg combos)`, "", head, sep, ...rows, ""].join("\n");
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// 4. Full run
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Load tokens + stylesheets → extract ∪ declared → matrix + palette evaluation. */
+export async function runPairingExtractor({ tokens, css = [], declared = null, defaultBackground = null }) {
+  const map = typeof tokens === "string" ? await loadTokens(tokens) : tokens;
+  const cssTexts = await Promise.all((Array.isArray(css) ? css : [css]).map((c) => (c.includes("{") ? c : readFile(c, "utf8"))));
+  const rules = cssTexts.flatMap((t) => parseRules(t));
+  const ext = extractPairings(rules, map, { defaultBackground });
+
+  // Union declared pairings (resolved) in.
+  const extractedCount = ext.pairings.length;
+  let union = ext.pairings;
+  if (declared) {
+    const spec = typeof declared === "string" ? JSON.parse(await readFile(declared, "utf8")) : declared;
+    const seen = new Set(union.map((p) => `${p.fgHex.toLowerCase()}|${p.bgHex.toLowerCase()}|${p.kind}`));
+    for (const d of spec.pairings || []) {
+      try {
+        const fgHex = resolveColor(map, d.fg), bgHex = resolveColor(map, d.bg), kind = d.kind || "text";
+        const key = `${toHex(parseHex(fgHex)).toLowerCase()}|${toHex(parseHex(bgHex)).toLowerCase()}|${kind}`;
+        if (!seen.has(key)) { seen.add(key); union.push({ fg: d.fg, bg: d.bg, fgHex, bgHex, kind, source: "declared", confidence: "declared" }); }
+      } catch {}
+    }
+  }
+
+  const matrix = buildMatrix(union);
+  const palette = evaluatePalette({ pairings: union.map((p) => ({ ...p })) });
+  return {
+    passed: palette.passed,
+    summary: {
+      extracted: extractedCount,
+      declaredAdded: union.length - extractedCount,
+      total: union.length,
+      failing: matrix.filter((m) => !m.passed).length,
+      surfaces: ext.surfaces.length,
+    },
+    defaultSurface: ext.defaultSurface,
+    pairings: union,
+    matrix,
+    palette,
+  };
+}
+
+async function main() {
+  const argv = process.argv.slice(2).filter((a) => !a.startsWith("--"));
+  const tokens = argv[0] || process.env.PAIRING_TOKENS;
+  const css = argv.slice(1);
+  if (!tokens || css.length === 0) {
+    console.error("✗ pairing-extractor: usage: pairing-extractor.mjs <tokens.(json|css)> <style1.css> [style2.css …]");
+    process.exit(2);
+  }
+  const report = await runPairingExtractor({ tokens, css, declared: process.env.PAIRING_DECLARED || null });
+  if (process.env.PAIRING_REPORT) await writeFile(resolve(process.env.PAIRING_REPORT), JSON.stringify(report, null, 2) + "\n");
+
+  const md = renderMatrixMarkdown(report.matrix);
+  if (process.env.PAIRING_MATRIX) await writeFile(resolve(process.env.PAIRING_MATRIX), md + "\n");
+  else console.log(md);
+
+  const s = report.summary;
+  const line = `pairing-extractor: ${s.total} pair(s) (${s.extracted} extracted + ${s.declaredAdded} declared) — ${s.failing} failing`;
+  if (process.env.PAIRING_GATE === "1" && !report.passed) {
+    console.error(`✗ ${line}`);
+    for (const m of report.matrix) if (!m.passed) console.error(`  · ${m.fg}/${m.bg} [${m.kind}] WCAG ${m.wcag}:1`);
+    process.exit(1);
+  }
+  console.error(`✓ ${line}`);
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main().catch((e) => { console.error("✗ pairing-extractor: error —", e.stack || e.message); process.exit(1); });
+}

package/gates/target-size-gate.mjs

@@ -0,0 +1,166 @@
+#!/usr/bin/env node
+// Target-size gate — STATIC analysis over a site/brand's INTERACTIVE-TARGET size
+// tokens (the dimensions a design system ships for buttons, controls, icon hit-
+// areas, list rows, …), member of the Token Accessibility suite. Reasons about the
+// size TOKENS, not a rendered layout, so it answers: "do these control tokens
+// PERMIT a large-enough pointer target, or do they bake in a too-small one?"
+//
+// Checks, mapped to WCAG 2.2:
+//   1. TARGET SIZE (Minimum) — SC 2.5.8 (AA): the bounding box of a pointer target
+//      must be ≥ 24×24 CSS px (unless an exception applies). A declared target token
+//      whose min(width,height) < 24px → ERROR (fails closed).
+//   2. TARGET SIZE (Enhanced) — SC 2.5.5 (AAA): ≥ 44×44 px. Reported as STATUS only
+//      (pass/fail per target) — not a hard failure, since 2.5.5 is AAA.
+//
+// SC 2.5.8 EXCEPTIONS (spacing, inline, user-agent, essential): a consumer may mark
+// a target `exception: "inline" | "essential" | "user-agent" | "spacing"` with a
+// `reason`; an exempt target is recorded (not failed) but the reason is surfaced so
+// the claim stays auditable. The HONEST SCOPE: tokens declare *intended* dimensions;
+// only the rendered DOM proves the actual box and the spacing-offset exception — so
+// this gate verifies the tokens don't UNDERCUT the floor, not that every instance
+// meets it. (The axe-gate / a manual check cover the rendered side.)
+//
+// Zero-dependency, pure exported primitives + a fail-closed CLI.
+//
+//   node gates/target-size-gate.mjs [config.json]
+//
+// INPUTS the consumer supplies (the consumer DECLARES which tokens are targets —
+// nothing is auto-assumed, because "is this token a tap target?" is design intent):
+//   argv[2] / $TARGET_CONFIG  a `config.json`:
+//     { "thresholds": { "minPx": 24, "aaaPx": 44 },
+//       "tokens": { "control-min": "44px", … },           // optional token map
+//       "targets": [ { "name":"icon-button", "width":"{control-min}"|"24px",
+//                      "height":"24px", "exception?":"inline", "reason?":"…" } ] }
+//     `width`/`height` (or a single `size` for a square) are a literal px, a `{name}`
+//     ref into `tokens`, or a number. A target with only one dimension is treated as
+//     a square of that side.
+//   $TARGET_REPORT            path to write the machine-readable JSON report.
+//
+// Thresholds (config ⊕ env), fail closed:
+//   $TARGET_MIN_PX  (default 24)  SC 2.5.8 AA floor
+//   $TARGET_AAA_PX  (default 44)  SC 2.5.5 AAA target (status only)
+import { readFile, writeFile } from "node:fs/promises";
+import { resolve } from "node:path";
+
+export const DEFAULT_THRESHOLDS = {
+  minPx: 24, // WCAG 2.2 SC 2.5.8 (AA)
+  aaaPx: 44, // WCAG 2.2 SC 2.5.5 (AAA)
+};
+
+export const EXCEPTIONS = new Set(["inline", "essential", "user-agent", "spacing"]);
+
+/** Resolve a dimension ref (`"24px"` | `24` | `"{token}"`) against a token map → px or null. */
+export function resolveDimension(ref, tokens = {}) {
+  if (ref == null) return null;
+  if (typeof ref === "number") return ref;
+  let s = String(ref).trim();
+  const m = /^\{(.+)\}$/.exec(s);
+  if (m) { if (!(m[1] in tokens)) return null; s = String(tokens[m[1]]).trim(); }
+  const px = /^(-?[0-9]*\.?[0-9]+)\s*px$/.exec(s) || /^(-?[0-9]*\.?[0-9]+)$/.exec(s);
+  if (px) return parseFloat(px[1]);
+  const rem = /^(-?[0-9]*\.?[0-9]+)\s*rem$/.exec(s);
+  if (rem) return parseFloat(rem[1]) * 16;
+  return null;
+}
+
+/** Evaluate ONE declared target. Pure. */
+export function evaluateTarget(target, tokens = {}, thresholds = DEFAULT_THRESHOLDS) {
+  const t = { ...DEFAULT_THRESHOLDS, ...thresholds };
+  const w = resolveDimension(target.width ?? target.size, tokens);
+  const h = resolveDimension(target.height ?? target.size, tokens);
+  const minSide = [w, h].filter((n) => n != null).length ? Math.min(...[w, h].filter((n) => n != null)) : null;
+
+  const exception = target.exception && EXCEPTIONS.has(target.exception) ? target.exception : null;
+  const aaPass = minSide == null ? null : minSide + 1e-9 >= t.minPx;
+  const aaaPass = minSide == null ? null : minSide + 1e-9 >= t.aaaPx;
+
+  const findings = [];
+  if (minSide == null) {
+    findings.push({ severity: "warn", sc: "2.5.8", msg: `target "${target.name}" has no resolvable dimension` });
+  } else if (!aaPass && !exception) {
+    findings.push({ severity: "error", sc: "2.5.8", msg: `${minSide}px < ${t.minPx}px (AA minimum)` });
+  } else if (!aaPass && exception) {
+    findings.push({ severity: "info", sc: "2.5.8", msg: `${minSide}px < ${t.minPx}px but exempt via "${exception}"${target.reason ? `: ${target.reason}` : ""}` });
+  }
+
+  return {
+    name: target.name,
+    width: w, height: h, minSide,
+    exception,
+    reason: target.reason ?? null,
+    aa: { min: t.minPx, pass: aaPass },
+    aaa: { min: t.aaaPx, pass: aaaPass },
+    findings,
+    passed: findings.every((f) => f.severity !== "error"),
+  };
+}
+
+/** Whole-suite evaluation → fail-closed report. Pure. */
+export function evaluateTargets({ targets = [], tokens = {}, thresholds = DEFAULT_THRESHOLDS } = {}) {
+  const t = { ...DEFAULT_THRESHOLDS, ...thresholds };
+  const results = targets.map((tg) => evaluateTarget(tg, tokens, t));
+  const errors = results.flatMap((r) => r.findings.filter((f) => f.severity === "error"));
+  const notes = [];
+  if (targets.length === 0) {
+    notes.push("no interactive-target tokens declared — target-size cannot be asserted from tokens alone (declare the controls' size tokens to enable this gate)");
+  }
+  return {
+    passed: errors.length === 0,
+    thresholds: t,
+    summary: {
+      targets: results.length,
+      belowAA: results.filter((r) => r.aa.pass === false && !r.exception).length,
+      exempt: results.filter((r) => r.exception).length,
+      meetsAAA: results.filter((r) => r.aaa.pass === true).length,
+      unresolved: results.filter((r) => r.minSide == null).length,
+    },
+    targets: results,
+    notes,
+    coverage: targets.length === 0 ? "none" : "declared",
+    // Envelope a future lone `target.min-size` criterion can consume.
+    target: { minSizeAA: errors.length === 0, declared: targets.length },
+  };
+}
+
+export async function runTargetSizeGate({ config = {}, thresholds = {} }) {
+  const cfg = typeof config === "string" ? JSON.parse(await readFile(config, "utf8")) : config;
+  return evaluateTargets({
+    targets: cfg.targets || [],
+    tokens: cfg.tokens || {},
+    thresholds: { ...DEFAULT_THRESHOLDS, ...(cfg.thresholds || {}), ...thresholds },
+  });
+}
+
+function envThresholds() {
+  const t = {};
+  const num = (e) => (process.env[e] != null ? Number(process.env[e]) : undefined);
+  const set = (k, e) => { const v = num(e); if (v != null && !Number.isNaN(v)) t[k] = v; };
+  set("minPx", "TARGET_MIN_PX");
+  set("aaaPx", "TARGET_AAA_PX");
+  return t;
+}
+
+async function main() {
+  const argv = process.argv.slice(2).filter((a) => !a.startsWith("--"));
+  const config = argv[0] || process.env.TARGET_CONFIG;
+  if (!config) {
+    console.error("✗ target-size-gate: usage: target-size-gate.mjs <config.json>  (or set $TARGET_CONFIG)");
+    process.exit(2);
+  }
+  const report = await runTargetSizeGate({ config, thresholds: envThresholds() });
+  if (process.env.TARGET_REPORT) await writeFile(resolve(process.env.TARGET_REPORT), JSON.stringify(report, null, 2) + "\n");
+
+  const s = report.summary;
+  const line = `target-size-gate: ${s.targets} target(s) — ${s.belowAA} below AA, ${s.exempt} exempt, ${s.meetsAAA} meet AAA`;
+  if (!report.passed) {
+    console.error(`✗ ${line}`);
+    for (const r of report.targets) for (const f of r.findings) if (f.severity === "error") console.error(`  · ${r.name}: ${f.msg}`);
+    process.exit(1);
+  }
+  console.log(`✓ ${line}`);
+  for (const n of report.notes) console.log(`  · note: ${n}`);
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main().catch((e) => { console.error("✗ target-size-gate: error —", e.stack || e.message); process.exit(1); });
+}