@bounded-systems/conformance-kit 0.4.0 → 0.6.0

package/gates/token-a11y.mjs

@@ -0,0 +1,128 @@
+#!/usr/bin/env node
+// Token Accessibility suite — the UNIFIED runner. One `token-a11y.json` config drives
+// every member of the suite over a single token map, and the runner FAILS CLOSED if
+// ANY member fails. This is the named "thing": token-level accessibility as one gate.
+//
+// Members (each a standalone gate, documented in TOKEN-A11Y.md):
+//   · palette          — palette-gate.mjs       CVD-safe / APCA / non-text contrast
+//   · pairing          — pairing-extractor.mjs  derive fg×bg pairings from CSS usage,
+//                        then feed the palette check (coverage without hand-listing)
+//   · typography       — typography-gate.mjs    line-height / spacing / size / weight
+//   · targetSize       — target-size-gate.mjs   interactive target ≥ 24×24 (2.5.8)
+//   · opacity          — opacity-contrast-gate  effective contrast of translucent fg
+//   · likeness         — likeness-gate.mjs      near-duplicate + confusable categoricals
+//
+//   node gates/token-a11y.mjs <token-a11y.json>      # (or $TOKEN_A11Y_CONFIG)
+//
+// CONFIG (every member is OPTIONAL — only declared members run):
+//   { "tokens": "brand/tokens/tokens.css",          // default token map (path or map)
+//     "palette":   { "pairings":[…], "categorical":[…], "thresholds":{…} } | "pairings.json",
+//     "pairing":   { "css":["a.css","b.css"], "declared":"pairings.json", "gate":true },
+//     "typography":{ "tokens":"…", "body":["body"], "thresholds":{…} } | "typo.json",
+//     "targetSize":{ "targets":[…], "thresholds":{…} } | "targets.json",
+//     "opacity":   { "usages":[…], "opacityTokens":{…} } | "usages.json",
+//     "likeness":  { "categorical":[…], "thresholds":{…} } | "likeness.json" }
+//   A member may set its own `tokens` to override the top-level map.
+//   $TOKEN_A11Y_REPORT writes the aggregate JSON report.
+import { readFile, writeFile } from "node:fs/promises";
+import { resolve, dirname, isAbsolute, join } from "node:path";
+import { runPaletteGate } from "./palette-gate.mjs";
+import { runTypographyGate } from "./typography-gate.mjs";
+import { runTargetSizeGate } from "./target-size-gate.mjs";
+import { runOpacityContrastGate } from "./opacity-contrast-gate.mjs";
+import { runLikenessGate } from "./likeness-gate.mjs";
+import { runPairingExtractor } from "./pairing-extractor.mjs";
+
+const MEMBERS = ["palette", "pairing", "typography", "targetSize", "opacity", "likeness"];
+
+/** Resolve a path/config value relative to the config file's directory. */
+function rel(base, p) {
+  if (typeof p !== "string") return p;
+  return isAbsolute(p) ? p : join(base, p);
+}
+
+/**
+ * Run the suite from a parsed config. `base` is the dir paths resolve against.
+ * Returns the aggregate report. Pure-ish (I/O only via the member runners).
+ */
+export async function runTokenA11y(config, base = ".") {
+  const tokens = (m) => rel(base, m?.tokens ?? config.tokens);
+  const members = {};
+  const run = async (name, fn) => { try { members[name] = { ...(await fn()), error: null }; } catch (e) { members[name] = { passed: false, error: String(e.message || e) }; } };
+
+  if (config.palette) {
+    const m = typeof config.palette === "string" ? rel(base, config.palette) : config.palette;
+    await run("palette", () => runPaletteGate({ tokens: tokens(typeof m === "object" ? m : {}), pairings: m }));
+  }
+  if (config.pairing) {
+    const m = config.pairing;
+    await run("pairing", async () => {
+      const r = await runPairingExtractor({
+        tokens: tokens(m), css: (m.css || []).map((c) => rel(base, c)),
+        declared: m.declared ? rel(base, m.declared) : null,
+      });
+      // Report-only unless `gate:true`.
+      return m.gate ? r : { ...r, passed: true, gated: false };
+    });
+  }
+  if (config.typography) {
+    const m = typeof config.typography === "string" ? rel(base, config.typography) : config.typography;
+    await run("typography", () => runTypographyGate({ tokens: tokens(typeof m === "object" ? m : {}), config: m }));
+  }
+  if (config.targetSize) {
+    const m = typeof config.targetSize === "string" ? rel(base, config.targetSize) : config.targetSize;
+    await run("targetSize", () => runTargetSizeGate({ config: m }));
+  }
+  if (config.opacity) {
+    const m = typeof config.opacity === "string" ? rel(base, config.opacity) : config.opacity;
+    await run("opacity", () => runOpacityContrastGate({ tokens: tokens(typeof m === "object" ? m : {}), usages: m }));
+  }
+  if (config.likeness) {
+    const m = typeof config.likeness === "string" ? rel(base, config.likeness) : config.likeness;
+    await run("likeness", () => runLikenessGate({ tokens: tokens(typeof m === "object" ? m : {}), config: m }));
+  }
+
+  const ran = Object.keys(members);
+  const failing = ran.filter((k) => members[k].passed === false);
+  return {
+    passed: failing.length === 0,
+    members: Object.fromEntries(MEMBERS.filter((k) => k in members).map((k) => [k, members[k]])),
+    summary: { ran, passed: ran.filter((k) => members[k].passed !== false), failing },
+  };
+}
+
+/** One-line status per member, for the CLI. */
+function memberLine(name, m) {
+  if (m.error) return `  ✗ ${name}: error — ${m.error}`;
+  const s = m.summary || {};
+  const tail =
+    name === "palette" ? `${s.pairs} pair(s), ${s.failingPairs} failing, ${s.categoricalCollapses} collapse(s)`
+    : name === "pairing" ? `${s.total} pair(s), ${s.failing} failing${m.gated === false ? " (report-only)" : ""}`
+    : name === "typography" ? `${s.styles} style(s), ${s.errors} error(s), ${s.warnings} warn(s)`
+    : name === "targetSize" ? `${s.targets} target(s), ${s.belowAA} below AA${m.coverage === "none" ? " (none declared)" : ""}`
+    : name === "opacity" ? `${s.usages} usage(s), ${s.failing} failing`
+    : name === "likeness" ? `${s.nearDuplicates} near-dup(s), ${s.categoricalCollapses} collapse(s)`
+    : "";
+  return `  ${m.passed ? "✓" : "✗"} ${name}: ${tail}`;
+}
+
+async function main() {
+  const argv = process.argv.slice(2).filter((a) => !a.startsWith("--"));
+  const configPath = argv[0] || process.env.TOKEN_A11Y_CONFIG;
+  if (!configPath) {
+    console.error("✗ token-a11y: usage: token-a11y.mjs <token-a11y.json>  (or set $TOKEN_A11Y_CONFIG)");
+    process.exit(2);
+  }
+  const config = JSON.parse(await readFile(configPath, "utf8"));
+  const report = await runTokenA11y(config, dirname(resolve(configPath)));
+  if (process.env.TOKEN_A11Y_REPORT) await writeFile(resolve(process.env.TOKEN_A11Y_REPORT), JSON.stringify(report, null, 2) + "\n");
+
+  const lines = Object.entries(report.members).map(([k, m]) => memberLine(k, m));
+  const head = `token-a11y: ${report.summary.ran.length} member(s) — ${report.summary.failing.length} failing`;
+  if (!report.passed) { console.error(`✗ ${head}`); for (const l of lines) console.error(l); process.exit(1); }
+  console.log(`✓ ${head}`); for (const l of lines) console.log(l);
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main().catch((e) => { console.error("✗ token-a11y: error —", e.stack || e.message); process.exit(1); });
+}

package/gates/typography-gate.mjs

@@ -0,0 +1,396 @@
+#!/usr/bin/env node
+// Typography gate — STATIC analysis over a site/brand's TYPE tokens (the
+// font-size / line-height / weight / letter-&-word-&-paragraph-spacing recipes),
+// member of the Token Accessibility suite. Like the palette gate it reasons about
+// the TOKENS themselves — the values a design system ships — not a rendered page,
+// so it answers a question axe cannot: "do these type tokens PERMIT accessible
+// text, or do they bake in a barrier?"
+//
+// Four checks, each mapped to a WCAG success criterion:
+//
+//   1. BODY LINE-HEIGHT ≥ 1.5  (WCAG 2.2 SC 1.4.12 Text Spacing)
+//      Body/paragraph styles must author a line-height of at least 1.5× the font
+//      size. 1.4.12 is written as a USER-OVERRIDE criterion (no loss of content
+//      when the reader sets line-height to 1.5) — a static token check approximates
+//      the spirit by requiring the shipped body token not undercut that floor, and
+//      by requiring it be expressed in an OVERRIDABLE unit (see check 2).
+//
+//   2. TEXT-SPACING ACHIEVABILITY  (WCAG 2.2 SC 1.4.12)
+//      The criterion guarantees the reader can set letter-spacing ≥ 0.12em, word-
+//      spacing ≥ 0.16em, paragraph-spacing ≥ 2em and line-height ≥ 1.5 with no loss
+//      of content. From tokens alone we cannot prove "no loss of content", but we
+//      CAN prove the tokens don't PRECLUDE those overrides: spacing/line-height must
+//      be expressed in RELATIVE, overridable units (unitless / em / rem / %), never
+//      pinned in px (which a user stylesheet without !important cannot scale past a
+//      fixed line-box). A px-pinned line-height or letter-spacing on body is flagged.
+//
+//   3. MINIMUM FONT SIZE  (WCAG 1.4.4 Resize Text — supporting; readability)
+//      Body text should be ≥ ~16px (recommended) and MUST clear a hard floor of
+//      ~12px. Below the floor → error; between floor and recommended → warning. Plus
+//      a modular-scale sanity check: the size ramp should be monotonic and each step
+//      within a sane ratio band (no inversions, no absurd jumps, no exact dups).
+//
+//   4. WEIGHT × SIZE LEGIBILITY  (APCA cross-check; WCAG 1.4.3/1.4.6 spirit)
+//      Hairline/thin weights (≤ 200) at small sizes render as low-contrast strokes.
+//      Flag thin weight below a size threshold. AND cross-link the palette gate:
+//      report the APCA Lc a style of this size/weight will REQUIRE wherever it is
+//      coloured (thin + small ⇒ higher Lc), via palette-gate's `apcaMinLc`.
+//
+// Zero-dependency. Colour-science / APCA primitives are imported from the sibling
+// palette gate (no duplication). The pure functions are exported for unit testing;
+// the CLI is a thin wrapper that FAILS CLOSED (exit 1) on any error-severity finding.
+//
+//   node gates/typography-gate.mjs <type-tokens.(json|css)> [config.json]
+//
+// INPUTS the consumer supplies (nothing about any one brand is hard-coded):
+//   argv[2] / $TYPO_TOKENS   a DTCG `tokens.json` (its `$type:"typography"` recipes,
+//                            with `{size.*}` aliases resolved) OR a `tokens.css`
+//                            (`.bs-text-*{ font-size; line-height; … }` recipe classes).
+//   argv[3] / $TYPO_CONFIG   a `config.json` declaring which styles are BODY text
+//                            (`{ "body":["body"], "thresholds":{…}, "styles":[…] }`).
+//                            Only the consumer knows which token is the body recipe;
+//                            line-height & min-size rules apply to those. `styles[]`
+//                            can inline extra styles (for a CSS-less consumer) or
+//                            override parsed ones.
+//   $TYPO_REPORT             path to write the machine-readable JSON report.
+//
+// Thresholds are config-driven (`config.json` `thresholds` ⊕ env) and fail closed:
+//   $TYPO_MIN_BODY_LINE_HEIGHT (default 1.5)  SC 1.4.12 body line-height floor
+//   $TYPO_REC_BODY_PX          (default 16)   recommended body min (warn below)
+//   $TYPO_MIN_BODY_PX          (default 12)   hard body min (error below)
+//   $TYPO_MIN_LETTER_EM        (default 0.12) 1.4.12 letter-spacing override target
+//   $TYPO_MIN_WORD_EM          (default 0.16) 1.4.12 word-spacing override target
+//   $TYPO_MIN_PARA_EM          (default 2)    1.4.12 paragraph-spacing override target
+//   $TYPO_THIN_WEIGHT          (default 200)  weight ≤ this is "thin/hairline"
+//   $TYPO_THIN_MIN_PX          (default 24)   thin weight below this px → error
+//   $TYPO_SCALE_MIN_RATIO      (default 1.05) min step ratio in the size ramp
+//   $TYPO_SCALE_MAX_RATIO      (default 2.4)  max step ratio in the size ramp
+import { readFile, writeFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { apcaMinLc } from "./palette-gate.mjs";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// 1. Value parsing — dimensions, line-heights, spacings (pure)
+//    Refs: CSS Values & Units (px/em/rem/%); a `rem`/`em` is resolved against the
+//    document/element font size (we assume a 16px root, the browser default).
+// ─────────────────────────────────────────────────────────────────────────────
+
+const ROOT_PX = 16; // CSS initial root font-size (browser default).
+
+/** A length string → { px, unit, value } or null. Supports px / rem / em / pt / %. */
+export function parseLength(value, contextPx = ROOT_PX) {
+  if (value == null) return null;
+  if (typeof value === "number") return { px: value, unit: "px", value };
+  const m = /^(-?[0-9]*\.?[0-9]+)\s*(px|rem|em|pt|%)?$/.exec(String(value).trim());
+  if (!m) return null;
+  const n = parseFloat(m[1]);
+  const unit = m[2] || "px";
+  let px;
+  if (unit === "px") px = n;
+  else if (unit === "rem") px = n * ROOT_PX;
+  else if (unit === "em") px = n * contextPx;
+  else if (unit === "pt") px = (n * 96) / 72;
+  else if (unit === "%") px = (n / 100) * contextPx;
+  else px = n;
+  return { px, unit, value: n };
+}
+
+/** A line-height (unitless | px | em | rem | %) → its RATIO to the font size. */
+export function parseLineHeight(value, fontSizePx) {
+  if (value == null) return null;
+  const s = String(value).trim();
+  if (/^-?[0-9]*\.?[0-9]+$/.test(s)) return { ratio: parseFloat(s), unit: "unitless", overridable: true };
+  const len = parseLength(s, fontSizePx);
+  if (!len) return null;
+  const overridable = len.unit !== "px" && len.unit !== "pt"; // px/pt pin a fixed box
+  return { ratio: fontSizePx ? len.px / fontSizePx : null, unit: len.unit, overridable };
+}
+
+/** A letter/word/paragraph spacing → em relative to font size. */
+export function parseSpacingEm(value, fontSizePx) {
+  if (value == null) return null;
+  const s = String(value).trim();
+  if (s === "normal" || s === "0") return { em: 0, unit: s === "0" ? "unitless" : "normal", overridable: true };
+  const len = parseLength(s, fontSizePx);
+  if (!len) return null;
+  if (len.unit === "em") return { em: len.value, unit: "em", overridable: true };
+  if (len.unit === "rem" || len.unit === "%") return { em: fontSizePx ? len.px / fontSizePx : null, unit: len.unit, overridable: true };
+  // px/pt: a fixed spacing the reader's relative override can't supersede cleanly.
+  return { em: fontSizePx ? len.px / fontSizePx : null, unit: len.unit, overridable: false };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// 2. Token loading — DTCG `$type:"typography"` recipes, or `tokens.css` classes
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Flatten DTCG `size`/`dimension` tokens → { "size.text-body": "15px", … } (aliases kept). */
+function flattenDimensions(json) {
+  const out = {};
+  const walk = (node, path) => {
+    if (node && typeof node === "object") {
+      if (typeof node.$value === "string" && (node.$type === "dimension" || /px|rem|em|pt|%$/.test(node.$value))) {
+        out[path.join(".")] = node.$value;
+      }
+      for (const [k, v] of Object.entries(node)) if (!k.startsWith("$")) walk(v, [...path, k]);
+    }
+  };
+  walk(json, []);
+  return out;
+}
+
+/** Resolve a `{dotted.alias}` (or literal) against a flat map. */
+function resolveAlias(v, flat, seen = new Set()) {
+  const m = /^\{(.+)\}$/.exec(String(v).trim());
+  if (!m) return v;
+  if (seen.has(m[1]) || !(m[1] in flat)) return v;
+  return resolveAlias(flat[m[1]], flat, new Set([...seen, m[1]]));
+}
+
+/**
+ * Parse a DTCG tokens.json into normalized type styles:
+ *   { name → { fontSizePx, lineHeight{ratio,unit,overridable}, fontWeight,
+ *              letterSpacing{em,unit,overridable}, wordSpacing?, paragraphSpacing?,
+ *              fontFamily, raw } }
+ * `$type:"typography"` recipes are read from any tier (brand uses a `text` tier).
+ */
+export function typesFromDTCG(json) {
+  const dims = flattenDimensions(json);
+  const styles = {};
+  const walk = (node, path) => {
+    if (node && typeof node === "object") {
+      if (node.$type === "typography" && node.$value && typeof node.$value === "object") {
+        styles[path.join(".")] = normalizeStyle(node.$value, dims);
+      }
+      for (const [k, v] of Object.entries(node)) if (!k.startsWith("$")) walk(v, [...path, k]);
+    }
+  };
+  walk(json, []);
+  return styles;
+}
+
+function normalizeStyle(v, dims = {}) {
+  const fsRaw = resolveAlias(v.fontSize, dims);
+  const fontSizePx = parseLength(fsRaw)?.px ?? null;
+  return {
+    fontSizePx,
+    fontSizeRaw: fsRaw,
+    lineHeight: v.lineHeight != null ? parseLineHeight(v.lineHeight, fontSizePx) : null,
+    fontWeight: v.fontWeight != null ? Number(v.fontWeight) : null,
+    letterSpacing: v.letterSpacing != null ? parseSpacingEm(v.letterSpacing, fontSizePx) : null,
+    wordSpacing: v.wordSpacing != null ? parseSpacingEm(v.wordSpacing, fontSizePx) : null,
+    paragraphSpacing: v.paragraphSpacing != null ? parseSpacingEm(v.paragraphSpacing, fontSizePx) : null,
+    fontFamily: v.fontFamily ?? null,
+    raw: v,
+  };
+}
+
+/** Parse a tokens.css of `.name { font-size; line-height; font-weight; letter-spacing }` recipes. */
+export function typesFromCSS(css) {
+  const styles = {};
+  const re = /\.([a-zA-Z0-9_-]+)\s*\{([^}]*)\}/g;
+  let m;
+  while ((m = re.exec(css))) {
+    const name = m[1], body = m[2];
+    const decl = {};
+    for (const d of body.split(";")) {
+      const i = d.indexOf(":");
+      if (i < 0) continue;
+      decl[d.slice(0, i).trim().toLowerCase()] = d.slice(i + 1).trim();
+    }
+    if (!("font-size" in decl) && !("line-height" in decl)) continue;
+    styles[name] = normalizeStyle({
+      fontSize: decl["font-size"],
+      lineHeight: decl["line-height"],
+      fontWeight: decl["font-weight"],
+      letterSpacing: decl["letter-spacing"],
+      wordSpacing: decl["word-spacing"],
+      fontFamily: decl["font-family"],
+    });
+  }
+  return styles;
+}
+
+export async function loadTypeTokens(path) {
+  const raw = await readFile(path, "utf8");
+  if (path.endsWith(".json")) return typesFromDTCG(JSON.parse(raw));
+  if (path.endsWith(".css")) return typesFromCSS(raw);
+  try { return typesFromDTCG(JSON.parse(raw)); } catch { return typesFromCSS(raw); }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// 3. Thresholds + per-style evaluation (pure)
+// ─────────────────────────────────────────────────────────────────────────────
+
+export const DEFAULT_THRESHOLDS = {
+  minBodyLineHeight: 1.5, // SC 1.4.12
+  recBodyPx: 16,          // recommended body min (warn below)
+  minBodyPx: 12,          // hard body min (error below)
+  minLetterEm: 0.12,      // SC 1.4.12 target
+  minWordEm: 0.16,        // SC 1.4.12 target
+  minParaEm: 2,           // SC 1.4.12 target
+  thinWeight: 200,        // ≤ this is hairline/thin
+  thinMinPx: 24,          // thin weight below this px → error
+  scaleMinRatio: 1.05,    // size-ramp step floor
+  scaleMaxRatio: 2.4,     // size-ramp step ceiling
+};
+
+const round2 = (n) => (n == null ? null : Math.round(n * 100) / 100);
+
+/** Evaluate ONE type style. `isBody` drives which checks are hard. Pure. */
+export function evaluateStyle(name, style, isBody, thresholds = DEFAULT_THRESHOLDS) {
+  const t = { ...DEFAULT_THRESHOLDS, ...thresholds };
+  const findings = [];
+  const add = (severity, sc, msg, data) => findings.push({ severity, sc, msg, ...data });
+  const px = style.fontSizePx;
+
+  // 1. Body line-height ≥ 1.5 (SC 1.4.12).
+  if (isBody && style.lineHeight) {
+    if (style.lineHeight.ratio != null && style.lineHeight.ratio + 1e-9 < t.minBodyLineHeight) {
+      add("error", "1.4.12", `body line-height ${round2(style.lineHeight.ratio)} < ${t.minBodyLineHeight}`, { lineHeight: round2(style.lineHeight.ratio) });
+    }
+  }
+
+  // 2. Text-spacing achievability — relative, overridable units (SC 1.4.12).
+  if (style.lineHeight && style.lineHeight.overridable === false) {
+    add(isBody ? "error" : "warn", "1.4.12", `line-height pinned in ${style.lineHeight.unit} (not user-overridable)`, { unit: style.lineHeight.unit });
+  }
+  for (const [prop, sp] of [["letterSpacing", style.letterSpacing], ["wordSpacing", style.wordSpacing], ["paragraphSpacing", style.paragraphSpacing]]) {
+    if (sp && sp.overridable === false) {
+      add(isBody ? "error" : "warn", "1.4.12", `${prop} pinned in ${sp.unit} (not user-overridable, can clip 1.4.12 spacing)`, { prop, unit: sp.unit });
+    }
+  }
+
+  // 3. Minimum font size (body) — hard floor + recommended (SC 1.4.4 / readability).
+  if (isBody && px != null) {
+    if (px + 1e-9 < t.minBodyPx) add("error", "1.4.4", `body font-size ${px}px < hard floor ${t.minBodyPx}px`, { px });
+    else if (px + 1e-9 < t.recBodyPx) add("warn", "1.4.4", `body font-size ${px}px < recommended ${t.recBodyPx}px`, { px });
+  }
+
+  // 4. Weight × size legibility + APCA cross-check (SC 1.4.3/1.4.6 spirit; APCA).
+  if (px != null && style.fontWeight != null && style.fontWeight <= t.thinWeight && px < t.thinMinPx) {
+    add("error", "1.4.8", `thin weight ${style.fontWeight} at ${px}px (< ${t.thinMinPx}px) — hairline strokes lose legibility`, { weight: style.fontWeight, px });
+  }
+  const requiredLc = px != null ? apcaMinLc({ sizePx: px, weight: style.fontWeight ?? 400 }) : null;
+
+  const errors = findings.filter((f) => f.severity === "error").length;
+  return {
+    name,
+    isBody,
+    fontSizePx: px,
+    fontWeight: style.fontWeight ?? null,
+    lineHeight: style.lineHeight ? round2(style.lineHeight.ratio) : null,
+    letterSpacingEm: style.letterSpacing ? round2(style.letterSpacing.em) : null,
+    requiredApcaLc: requiredLc, // cross-link: wherever this style is coloured, palette gate must clear this Lc
+    findings,
+    passed: errors === 0,
+  };
+}
+
+/** Modular-scale sanity over the distinct font sizes used. Pure. */
+export function evaluateScale(sizesPx, thresholds = DEFAULT_THRESHOLDS) {
+  const t = { ...DEFAULT_THRESHOLDS, ...thresholds };
+  const sizes = [...new Set(sizesPx.filter((n) => typeof n === "number"))].sort((a, b) => a - b);
+  const findings = [];
+  for (let i = 1; i < sizes.length; i++) {
+    const ratio = sizes[i] / sizes[i - 1];
+    if (ratio + 1e-9 < t.scaleMinRatio) findings.push({ severity: "warn", msg: `near-duplicate scale step ${sizes[i - 1]}px→${sizes[i]}px (ratio ${round2(ratio)} < ${t.scaleMinRatio})`, from: sizes[i - 1], to: sizes[i], ratio: round2(ratio) });
+    else if (ratio - 1e-9 > t.scaleMaxRatio) findings.push({ severity: "warn", msg: `large scale jump ${sizes[i - 1]}px→${sizes[i]}px (ratio ${round2(ratio)} > ${t.scaleMaxRatio})`, from: sizes[i - 1], to: sizes[i], ratio: round2(ratio) });
+  }
+  return { sizes, steps: Math.max(0, sizes.length - 1), findings };
+}
+
+/** Whole-typography evaluation → fail-closed report. Pure. */
+export function evaluateTypography({ styles = {}, body = [], thresholds = DEFAULT_THRESHOLDS } = {}) {
+  const t = { ...DEFAULT_THRESHOLDS, ...thresholds };
+  const bodySet = new Set(body);
+  const results = Object.entries(styles).map(([name, s]) => evaluateStyle(name, s, bodySet.has(name) || bodySet.has(name.split(".").pop()), t));
+  const scale = evaluateScale(Object.values(styles).map((s) => s.fontSizePx), t);
+
+  const allFindings = [...results.flatMap((r) => r.findings.map((f) => ({ style: r.name, ...f }))), ...scale.findings.map((f) => ({ style: "<scale>", ...f }))];
+  const errors = allFindings.filter((f) => f.severity === "error");
+  const warns = allFindings.filter((f) => f.severity === "warn");
+
+  return {
+    passed: errors.length === 0,
+    thresholds: t,
+    summary: {
+      styles: results.length,
+      bodyStyles: results.filter((r) => r.isBody).length,
+      errors: errors.length,
+      warnings: warns.length,
+    },
+    styles: results,
+    scale,
+    findings: allFindings,
+    // Envelope a future lone `typography.*` criterion can consume.
+    typography: {
+      bodyLineHeight: !errors.some((f) => f.sc === "1.4.12" && /line-height/.test(f.msg)),
+      textSpacingAchievable: !errors.some((f) => f.sc === "1.4.12" && /pinned/.test(f.msg)),
+      minFontSize: !errors.some((f) => f.sc === "1.4.4"),
+      weightLegibility: !errors.some((f) => f.sc === "1.4.8"),
+    },
+  };
+}
+
+/** Full run: load tokens + config → evaluate. Exposed for tests. */
+export async function runTypographyGate({ tokens, config = {}, thresholds = {} }) {
+  const parsed = typeof tokens === "string" ? await loadTypeTokens(tokens) : tokens;
+  const cfg = typeof config === "string" ? JSON.parse(await readFile(config, "utf8")) : config;
+  const styles = { ...parsed };
+  for (const s of cfg.styles || []) styles[s.name] = normalizeStyle(s);
+  return evaluateTypography({
+    styles,
+    body: cfg.body || [],
+    thresholds: { ...DEFAULT_THRESHOLDS, ...(cfg.thresholds || {}), ...thresholds },
+  });
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// 4. CLI
+// ─────────────────────────────────────────────────────────────────────────────
+
+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("minBodyLineHeight", "TYPO_MIN_BODY_LINE_HEIGHT");
+  set("recBodyPx", "TYPO_REC_BODY_PX");
+  set("minBodyPx", "TYPO_MIN_BODY_PX");
+  set("minLetterEm", "TYPO_MIN_LETTER_EM");
+  set("minWordEm", "TYPO_MIN_WORD_EM");
+  set("minParaEm", "TYPO_MIN_PARA_EM");
+  set("thinWeight", "TYPO_THIN_WEIGHT");
+  set("thinMinPx", "TYPO_THIN_MIN_PX");
+  set("scaleMinRatio", "TYPO_SCALE_MIN_RATIO");
+  set("scaleMaxRatio", "TYPO_SCALE_MAX_RATIO");
+  return t;
+}
+
+async function main() {
+  const argv = process.argv.slice(2).filter((a) => !a.startsWith("--"));
+  const tokens = argv[0] || process.env.TYPO_TOKENS;
+  const config = argv[1] || process.env.TYPO_CONFIG;
+  if (!tokens) {
+    console.error("✗ typography-gate: usage: typography-gate.mjs <type-tokens.(json|css)> [config.json]");
+    console.error("  (or set $TYPO_TOKENS and $TYPO_CONFIG)");
+    process.exit(2);
+  }
+  const cfg = config ? JSON.parse(await readFile(config, "utf8")) : {};
+  const report = await runTypographyGate({ tokens, config: cfg, thresholds: envThresholds() });
+  if (process.env.TYPO_REPORT) await writeFile(resolve(process.env.TYPO_REPORT), JSON.stringify(report, null, 2) + "\n");
+
+  const s = report.summary;
+  const line = `typography-gate: ${s.styles} style(s) (${s.bodyStyles} body) — ${s.errors} error(s), ${s.warnings} warning(s)`;
+  const fmt = (f) => `  · [${f.severity}] ${f.style}${f.sc ? ` (SC ${f.sc})` : ""}: ${f.msg}`;
+  if (!report.passed) {
+    console.error(`✗ ${line}`);
+    for (const f of report.findings) console.error(fmt(f));
+    process.exit(1);
+  }
+  console.log(`✓ ${line}`);
+  for (const f of report.findings) console.log(fmt(f)); // warnings only when passing
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main().catch((e) => { console.error("✗ typography-gate: error —", e.stack || e.message); process.exit(1); });
+}

package/generators/gen-print-snapshots.mjs

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+// Printed-view snapshot generator — the print/PDF twin of gen-snapshots (which does
+// the headless reader/Markdown view). For every built page it renders the page's
+// `@media print` view to a durable `<page>.print.pdf`, so the printed artifact is
+// archived + content-addressable alongside the served bytes.
+//
+// Unlike the reader view, a PDF needs a real print-CSS renderer. The default is
+// `tezcatl` (macOS-native WebKit, no Chromium download) — the same engine the kit's
+// axe gate uses locally. So this generator is a LOCAL / macOS-deploy artifact: on a
+// host without the renderer (e.g. a Linux CI runner) it SKIPS with a clear note.
+//
+//   node generators/gen-print-snapshots.mjs [distDir]
+//
+// Config-driven; NOTHING about any one site is hard-coded:
+//   argv / $PRINT_DIST        built output dir                  (default: "dist")
+//   $PRINT_PAGES             comma list of page paths under dist (default: every *.html)
+//   $PRINT_RENDERER          renderer command                  (default: "tezcatl")
+//   $PRINT_WAIT              ms to let JS/layout settle         (default: 600)
+//   $PRINT_SUFFIX            output basename suffix             (default: ".print")
+//
+// The pure path/arg functions are exported for unit testing without a renderer.
+import { readdir, access, stat } from "node:fs/promises";
+import { readFileSync } from "node:fs";
+import { createServer } from "node:http";
+import { spawn, spawnSync } from "node:child_process";
+import { resolve, join, relative, dirname, basename, extname } from "node:path";
+
+// ── Pure core (renderer-free; unit-testable) ─────────────────────────────────
+
+const MIME = {
+  ".html": "text/html", ".css": "text/css", ".js": "text/javascript",
+  ".json": "application/json", ".svg": "image/svg+xml", ".png": "image/png",
+  ".jpg": "image/jpeg", ".webp": "image/webp", ".woff2": "font/woff2",
+  ".woff": "font/woff", ".ico": "image/x-icon", ".txt": "text/plain",
+};
+export const mimeFor = (p) => MIME[extname(p).toLowerCase()] || "application/octet-stream";
+
+/** Output PDF path for a built page: dist/blog/x.html → dist/blog/x.print.pdf. */
+export function pdfOutPath(file, suffix = ".print") {
+  return join(dirname(file), basename(file, extname(file)) + suffix + ".pdf");
+}
+
+/** The renderer command + args. Pure: (renderer, url, out, wait) → [cmd, args]. */
+export function rendererCommand(renderer, url, out, wait = 600) {
+  if (renderer === "tezcatl") return ["tezcatl", [url, `--pdf=${out}`, `--wait=${wait}`]];
+  // A custom $PRINT_RENDERER is a command template: "cmd {url} {out}".
+  const parts = renderer.split(/\s+/).map((t) => t.replace("{url}", url).replace("{out}", out).replace("{wait}", String(wait)));
+  return [parts[0], parts.slice(1)];
+}
+
+// ── Impure: static origin + renderer ─────────────────────────────────────────
+
+/** Serve `root` over an ephemeral localhost origin so absolute asset paths resolve. */
+function startServer(root) {
+  return new Promise((res) => {
+    const server = createServer(async (req, res2) => {
+      try {
+        let p = join(root, decodeURIComponent((req.url || "/").split("?")[0]));
+        try { if ((await stat(p)).isDirectory()) p = join(p, "index.html"); } catch { p = join(root, "404.html"); }
+        res2.writeHead(200, { "content-type": mimeFor(p) });
+        res2.end(readFileSync(p));
+      } catch { res2.writeHead(404); res2.end(); }
+    });
+    server.listen(0, "127.0.0.1", () => res({ origin: `http://127.0.0.1:${server.address().port}`, close: () => server.close() }));
+  });
+}
+
+function render(renderer, url, out, wait) {
+  const [cmd, args] = rendererCommand(renderer, url, out, wait);
+  return new Promise((res, rej) => {
+    const ch = spawn(cmd, args, { stdio: ["ignore", "ignore", "pipe"] });
+    let err = "";
+    ch.stderr.on("data", (d) => (err += d));
+    ch.on("error", (e) => rej(new Error(`renderer "${cmd}" not runnable (on PATH?): ${e.message}`)));
+    ch.on("close", (code) => (code === 0 ? res() : rej(new Error(`renderer "${cmd}" exit ${code}: ${err.trim().slice(0, 200)}`))));
+  });
+}
+
+async function walkHtml(dir) {
+  const out = [];
+  for (const e of await readdir(dir, { withFileTypes: true })) {
+    const p = join(dir, e.name);
+    if (e.isDirectory()) out.push(...await walkHtml(p));
+    else if (e.name.endsWith(".html")) out.push(p);
+  }
+  return out;
+}
+
+/** Render each page → PDF. Exposed for programmatic use. */
+export async function genPrintSnapshots({ dist, pages, renderer = "tezcatl", wait = 600, suffix = ".print" }) {
+  const distAbs = resolve(dist);
+  const files = pages && pages.length ? pages.map((p) => resolve(distAbs, p)) : (await walkHtml(distAbs)).sort();
+  const { origin, close } = await startServer(distAbs);
+  const written = [];
+  try {
+    for (const file of files) {
+      const rel = relative(distAbs, file);
+      const out = pdfOutPath(file, suffix);
+      await render(renderer, `${origin}/${rel}`, out, wait);
+      written.push(relative(distAbs, out));
+    }
+  } finally { close(); }
+  return written;
+}
+
+// ── CLI ──────────────────────────────────────────────────────────────────────
+
+async function main() {
+  const distArg = process.argv.slice(2).find((a) => !a.startsWith("--"));
+  const dist = resolve(distArg || process.env.PRINT_DIST || "dist");
+  const exists = async (p) => { try { await access(p); return true; } catch { return false; } };
+  if (!(await exists(dist))) { console.error(`✗ gen-print-snapshots: ${dist} not found — build first.`); process.exit(2); }
+
+  const renderer = (process.env.PRINT_RENDERER || "tezcatl").trim();
+  const wait = Number.parseInt(process.env.PRINT_WAIT ?? "600", 10);
+  const suffix = process.env.PRINT_SUFFIX || ".print";
+  const pages = (process.env.PRINT_PAGES || "").split(",").map((s) => s.trim().replace(/^\//, "")).filter(Boolean);
+
+  // Renderer present? If not, SKIP (this is a local/macOS-deploy artifact, not CI).
+  const cmd0 = rendererCommand(renderer, "", "", wait)[0];
+  if (spawnSync(cmd0, ["--help"], { stdio: "ignore" }).error) {
+    console.log(`✓ gen-print-snapshots: renderer "${cmd0}" not on PATH — SKIPPED (run on a host with it, e.g. macOS + tezcatl).`);
+    return;
+  }
+
+  const written = await genPrintSnapshots({ dist, pages, renderer, wait, suffix });
+  for (const w of written) console.log(`  ✓ ${w}`);
+  console.log(`✓ gen-print-snapshots: ${written.length} printed PDF snapshot(s) via ${cmd0}.`);
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main().catch((e) => { console.error("✗ gen-print-snapshots: error —", e.stack || e.message); process.exit(1); });
+}