@bounded-systems/conformance-kit 0.5.0 → 0.6.0

package/README.md

@@ -13,6 +13,7 @@ hardcodes `robertdelanghe.dev`, `bounded.tools`, an account, or an email.
 ```
 integrity/    verify-site · verify (sigstore) · gen-sitemanifest · gen-provenance · structure-audit · http-probe
 gates/        sbom (gen + completeness) · shacl-runner · seo-gate · axe-gate (axe-core a11y) · vuln-gate (npm audit) · html-validator-gate (vnu) · baseline-gate (web-features) · jargon-gate (plain-language) · readability-gate · commonmark-runner · semantic (lone)
+gates/        Token Accessibility suite (static token-level a11y → TOKEN-A11Y.md): palette · pairing-extractor · typography · target-size · opacity-contrast · likeness · token-a11y (unified runner)
 gates/conformance/  conformance-report — lone's conformance() projection (Node port of jsr:@bounded-systems/lone@0.4) + a generic HTML renderer
 generators/   gen-cid (IPFS UnixFS) · gen-identity (did:web + VC) · gen-snapshots (reader/markdown) · gen-print-snapshots (PDF) · openapi (static-API helper core)
 emitters/     reprDigest (RFC 9530) · securityTxt (RFC 9116) · webManifest · markdown-sibling headers
@@ -79,7 +80,14 @@ in-process verifier). The Deno semantic runner pins its imports in
 | `baseline-gate.mjs` | `node …/baseline-gate.mjs [cssGlob]` | `$BASELINE_CSS` (default `dist/**/*.css`). Optional `$BASELINE_TARGET` (`widely`/`newly`, default `widely`), `$BASELINE_REPORT`. Maps the shipped CSS to **web-features Baseline** data (via `stylelint-plugin-use-baseline` — headless, no browser) and **fails closed** when the site-wide status is below target. A feature behind an `@supports` query is a tested fallback and doesn't count against it. The report's `baseline: { status, fallbackTested }` envelope is what `conformance-report`'s `compatibility.baseline` criterion consumes. |
 | `palette-gate.mjs` | `node …/palette-gate.mjs <tokens.(json\|css)> <pairings.json>` | **Two inputs the consumer supplies**: a token map (a DTCG `tokens.json` — primitive→semantic aliases resolved — or a `tokens.css` of `--name: #hex` custom properties) and a `pairings.json` declaring the fg/bg pairs that actually co-occur (`{ "pairings":[{fg,bg,kind,size?,weight?,name?}], "categorical":[…], "thresholds":{…} }`; `kind` ∈ `text`\|`large-text`\|`ui`, `fg`/`bg` are token names or literal `#hex`). Runs **static colour-palette analysis** — zero-dep, every primitive computed by hand: (1) **CVD-safe contrast** — simulates each colour under deuteranopia/protanopia/tritanopia (**Machado-2009** matrices), recomputes the WCAG ratio per pair under each, and flags any pair dropping below AA, plus **categorical collapse** (CIEDE2000 ΔE below `$PALETTE_COLLAPSE_DELTAE`, default 10) post-transform; (2) **APCA** — implements **APCA-W3 ~0.1.9**, reports `Lc` per text pair against a font-size/weight-aware (or baseline `$PALETTE_MIN_LC_TEXT` 60 / `$PALETTE_MIN_LC_LARGE` 45) minimum, **alongside** the WCAG-2 ratio (complement, not replacement); (3) **non-text contrast** — `kind:'ui'` pairs require ≥3:1 (WCAG 2.2 **SC 1.4.11**). Thresholds are config-driven (`pairings.json` `thresholds` ⊕ `$PALETTE_MIN_RATIO_{TEXT,LARGE,UI}`) and it **fails closed** on any failure. `$PALETTE_REPORT` writes the per-pair JSON (WCAG ratio · APCA Lc · per-CVD ratios · pass/fail per check). The report's `palette: { cvdSafe, apcaBaseline, nonTextContrast }` envelope is what a future `palette.*` criterion consumes. |
 | `jargon-gate.mjs` | `node …/jargon-gate.mjs [distDir] [--strict]` | `$JARGON_DIST`. Optional `$JARGON_ALLOWLIST` (comma list of accepted terms), `$JARGON_MIN_LENGTH` (default `3`), `$JARGON_THRESHOLD` (default `0`, for `--strict`), `$JARGON_REPORT`. Flags **undefined jargon** in the prose: words not in a 275k-word English dictionary (compounds/possessives atomized first) that the page does not **define** via `<abbr title>`, `<dfn>`, or a `<dl>` glossary — for W3C COGA / WCAG 3.1.3 Unusual Words and for AI readers. WARN-only by default; `--strict` fails closed. Report carries a `plainLanguage: { undefinedJargon, glossaryPresent }` envelope (for a future `cognitive.plain-language` criterion). |
+| `typography-gate.mjs` | `node …/typography-gate.mjs <type-tokens.(json\|css)> [config.json]` | **Token Accessibility suite.** Type tokens (DTCG `$type:"typography"` recipes or `.bs-text-*` CSS) + a `config.json` declaring which styles are **body** (`{ "body":["body"], "thresholds":{…} }`). Static checks, each mapped to a SC: body **line-height ≥ 1.5** (1.4.12); **text-spacing achievability** — spacing/line-height in overridable relative units, never px-pinned (1.4.12); **min font-size** — body ≥ ~16px (warn) / ≥ ~12px hard floor (error) + modular-scale sanity (1.4.4); **weight×size legibility** — thin weight (≤200) at small size → error, plus a `requiredApcaLc` cross-link to the palette gate (1.4.3/1.4.8). Fails closed on any error; `$TYPO_REPORT` writes the JSON. |
+| `target-size-gate.mjs` | `node …/target-size-gate.mjs <config.json>` | **Token Accessibility suite.** A `config.json` where the consumer **declares** which tokens are interactive targets (`{ "targets":[{name,width,height\|size,exception?,reason?}], "tokens":{…}, "thresholds":{minPx,aaaPx} }`). Enforces target **≥ 24×24px** (2.5.8 AA → error below) and reports **≥ 44×44px** (2.5.5 AAA) status; honours the 2.5.8 `inline`/`essential`/`user-agent`/`spacing` exceptions with an audit `reason`. No target tokens → `coverage:"none"` (vacuous pass + gap note). `$TARGET_REPORT` writes the JSON. |
+| `opacity-contrast-gate.mjs` | `node …/opacity-contrast-gate.mjs <tokens.(json\|css)> <usages.json>` | **Token Accessibility suite — the cross-cutting guard.** Token map + a `usages.json` declaring "opacity applied to a foreground" usages (`{ "usages":[{fg,bg,opacity,kind,name?}], "opacityTokens":{…}, "thresholds":{…} }`; `opacity` is 0..1 or a `{token}` ref). Composites fg over bg (Porter-Duff source-over) at the stated alpha and requires the **effective** WCAG contrast ≥ floor (4.5 text / 3 large/ui — 1.4.3/1.4.11), reporting both nominal and effective ratio so the drop is visible. Translucent-over-unknown-backdrop usages are flagged for review, not passed. Catches the bounded.tools opacity regression class. `$OPACITY_REPORT` writes the JSON. |
+| `likeness-gate.mjs` | `node …/likeness-gate.mjs <tokens.(json\|css)> [config.json]` | **Token Accessibility suite.** Two CIEDE2000 checks over the colour tokens: **near-duplicate** tokens (ΔE < ~2 ⇒ perceptually identical ⇒ consolidate candidate — warning, escalatable) and **confusable categoricals** (consumer-declared distinct sets that collapse under normal vision *or* deuteranopia/protanopia/tritanopia — error; supports 1.4.1). Config: `{ "categorical":[{name,members}], "ignore":[…], "thresholds":{dupDeltaE,collapseDeltaE,dupSeverity} }`. `$LIKENESS_REPORT` writes the JSON. |
+| `pairing-extractor.mjs` | `node …/pairing-extractor.mjs <tokens.(json\|css)> <style1.css> [style2.css …]` | **Token Accessibility suite — coverage engine.** Derives the real fg×bg pairings from **actual stylesheet usage** (resolves `var(--token)`/literal colours; pairs by same-rule co-occurrence → ancestor-selector containment → root surface, tagged `rule`/`surface`/`root` confidence), **unions** any declared `$PAIRING_DECLARED` pairings in, scores every pair through the palette check, and emits a **pairing matrix** (WCAG · APCA Lc · per-CVD ratios) to `$PAIRING_MATRIX` (Markdown) / `$PAIRING_REPORT` (JSON). No DOM ⇒ a reviewed **superset** (over-generates safely); **report-only** unless `$PAIRING_GATE=1`. Removes the hand-maintained pairings list that let the opacity bug slip. |
+| `token-a11y.mjs` | `node …/token-a11y.mjs <token-a11y.json>` | **Token Accessibility suite — unified runner** (`ck-token-a11y`). One `token-a11y.json` drives every member (palette · pairing · typography · targetSize · opacity · likeness) over one token map and **fails closed** if any fails. See [`TOKEN-A11Y.md`](./TOKEN-A11Y.md) for the standard. `$TOKEN_A11Y_REPORT` writes the aggregate JSON. |
 | `readability-gate.mjs` | `node …/readability-gate.mjs <corpus.json> [--strict]` | **The corpus is an input** the site assembles from its copy: a JSON array of `{id,text}` or an `{id:text}` map. Optional `$READABILITY_THRESHOLDS`, `$READABILITY_MIN_WORDS`, `$READABILITY_KNOWN_ACRONYMS`. WARN-only unless `--strict`. |
+| `ai-readability-gate.mjs` | `node …/ai-readability-gate.mjs [distDir]` | Re-proves lone's `semantic.ai-readability` at build time: emits `{llmsTxtPresent, linksResolve, markdownSiblings}` — checks `llms.txt` exists, its internal links resolve (and none hit `$AIR_PRIVATE` paths), and every content page has a Markdown sibling (`$AIR_SIBLING_SUFFIX`, default `.md`; `$AIR_SIBLING_IGNORE` defaults to `404`). Fail-closed (`$AIR_STRICT=0` to report only); `$AIR_REPORT` writes the evidence JSON. Static only — the `Accept: text/markdown` content-negotiation half is served-edge behaviour, probe it with `ck-http-probe`. |
 | `commonmark-runner.mjs` | `node …/commonmark-runner.mjs <renderer.mjs> [fixtures.json]` | **The site's markdown renderer module** (export `renderMarkdown`, or set `$COMMONMARK_RENDER_EXPORT`). Default fixtures pin a safe CommonMark subset + 4 hostile-HTML escapes; a site with a different renderer supplies its own `fixtures.json`. |
 | `semantic/gate.ts` | `deno run --allow-read --allow-net …/gate.ts` | Built HTML in `$SEMANTIC_DIR` (default `dist/blog`); `$SEMANTIC_SELECTOR` (subject node, default `article`). Imports `jsr:@bounded-systems/lone`; any error-severity finding fails CI. |
 | `conformance-report.mjs` | `import { buildConformanceReport, renderConformanceReport } from "…/gates/conformance-report.mjs"` | **The site's evidence** — `loneFindings` (the semantic gate's DOM findings, or `null` when no DOM was blessed → those criteria report `not-assessed`) + an external-evidence envelope whose fields it gathers from its own gates (`jsonLdShacl`, `sbom`, `contentDigests`, `slsaProvenance`, …). `renderConformanceReport(report, { evidenceHref })` → a class-based HTML fragment; the consumer wraps it in its template and supplies per-criterion evidence URLs. Zero-dep; the conformance MODEL is a Node port of `jsr:@bounded-systems/lone@0.4`'s `conformance()` in `gates/conformance/`. |

package/gates/ai-readability-gate.mjs

@@ -0,0 +1,169 @@
+#!/usr/bin/env node
+// AI-readability gate — re-proves lone's `semantic.ai-readability` criterion at build
+// time: a site is legible to LLM agents when it ships an `llms.txt` index, that index's
+// links actually resolve, and every page has a Markdown sibling (the clean,
+// chrome-free source an agent reads instead of scraping rendered HTML).
+//
+// It emits exactly the evidence shape the standard consumes —
+//   aiReadability: { llmsTxtPresent, linksResolve, markdownSiblings }
+// — so the consumer asserts the criterion and THIS gate proves it (fail-closed).
+//
+//   node gates/ai-readability-gate.mjs [distDir]
+//
+// Static / build-time only. The HTTP half of AI-readability — `Accept: text/markdown`
+// content negotiation (`Content-Type: text/markdown; Vary: Accept`) — is served-edge
+// behaviour, not a build artifact; probe that at deploy with `ck-http-probe`.
+//
+// Config (nothing site-specific hard-coded):
+//   argv / $AIR_DIST       built output dir                    (default: "dist")
+//   $AIR_LLMS              index filename under dist            (default: "llms.txt")
+//   $AIR_SIBLING_SUFFIX    Markdown sibling suffix             (default: ".md")
+//   $AIR_SIBLING_IGNORE    comma globs of pages needing none   (default: "404")
+//   $AIR_PRIVATE           comma path prefixes that are private (default: none)
+//   $AIR_REPORT            write the evidence JSON to this path (optional)
+//   $AIR_STRICT=0          report only, never exit non-zero    (default: fail-closed)
+import { readFile, readdir, access } from "node:fs/promises";
+import { resolve, join, dirname, relative, extname, posix } from "node:path";
+
+// ── Pure core (filesystem-free; unit-testable) ───────────────────────────────
+
+/** Extract link targets from Markdown: `[text](url)` + `<url>` autolinks. */
+export function extractMarkdownLinks(md) {
+  const out = [];
+  const text = String(md);
+  for (const m of text.matchAll(/\[[^\]]*\]\(\s*<?([^)\s>]+)>?(?:\s+["'][^)]*["'])?\s*\)/g)) out.push(m[1]);
+  for (const m of text.matchAll(/<((?:https?:\/\/|\/)[^>\s]+)>/g)) out.push(m[1]);
+  return out;
+}
+
+/** internal (relative / root-absolute) · external (scheme or //) · anchor (#…). */
+export function classifyLink(url) {
+  const u = String(url).trim();
+  if (u.startsWith("#")) return "anchor";
+  if (/^[a-z][a-z0-9+.-]*:/i.test(u) || u.startsWith("//")) return "external";
+  return "internal";
+}
+
+export function stripFragment(url) {
+  return String(url).split("#")[0].split("?")[0];
+}
+
+/** Candidate dist files an internal link could resolve to (extensionless → .html / dir index). */
+export function resolveCandidates(url, fromDir) {
+  const clean = stripFragment(url);
+  const base = clean.startsWith("/") ? clean.slice(1) : posix.join(fromDir, clean);
+  const cands = [base];
+  if (base.endsWith("/")) cands.push(posix.join(base, "index.html"));
+  else if (!extname(base)) cands.push(base + ".html", posix.join(base, "index.html"));
+  return cands.map((c) => c.replace(/^\/+/, ""));
+}
+
+/** Markdown sibling for an HTML page: dist/blog/x.html → dist/blog/x<suffix>. */
+export function siblingFor(htmlRel, suffix = ".md") {
+  return htmlRel.replace(/\.html$/, suffix);
+}
+
+export function isPrivate(url, prefixes = []) {
+  const p = stripFragment(url);
+  return prefixes.some((pre) => pre && (p === pre || p.startsWith(pre.endsWith("/") ? pre : pre + "/") || p.startsWith(pre)));
+}
+
+export function matchesAny(rel, globs = []) {
+  return globs.some((g) => {
+    const re = new RegExp("^" + g.trim().replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*") + "(\\.html)?$");
+    return re.test(rel) || re.test(rel.replace(/\.html$/, ""));
+  });
+}
+
+// ── Impure: read dist + evaluate ─────────────────────────────────────────────
+
+const exists = async (p) => { try { await access(p); return true; } catch { return false; } };
+
+async function walkHtml(dir, root = 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, root));
+    else if (e.name.endsWith(".html")) out.push(relative(root, p));
+  }
+  return out;
+}
+
+export async function evaluateAiReadability({
+  dist, llmsName = "llms.txt", siblingSuffix = ".md", siblingIgnore = ["404"], privatePrefixes = [],
+}) {
+  const distAbs = resolve(dist);
+  const llmsPath = join(distAbs, llmsName);
+
+  // 1. llms.txt present?
+  const llmsTxtPresent = await exists(llmsPath);
+
+  // 2. its internal links resolve to real files (and none point to private paths).
+  const brokenLinks = [], privateLinks = [];
+  if (llmsTxtPresent) {
+    const md = await readFile(llmsPath, "utf8");
+    const fromDir = dirname(relative(distAbs, llmsPath));
+    for (const url of extractMarkdownLinks(md)) {
+      if (classifyLink(url) !== "internal") continue;
+      if (isPrivate(url, privatePrefixes)) { privateLinks.push(url); continue; }
+      const cands = resolveCandidates(url, fromDir === "." ? "" : fromDir);
+      let ok = false;
+      for (const c of cands) if (await exists(join(distAbs, c))) { ok = true; break; }
+      if (!ok) brokenLinks.push(url);
+    }
+  }
+  const linksResolve = llmsTxtPresent && brokenLinks.length === 0 && privateLinks.length === 0;
+
+  // 3. every content page has a Markdown sibling.
+  const pages = (await walkHtml(distAbs)).sort();
+  const missingSiblings = [];
+  for (const rel of pages) {
+    if (matchesAny(rel, siblingIgnore)) continue;
+    if (!(await exists(join(distAbs, siblingFor(rel, siblingSuffix))))) missingSiblings.push(rel);
+  }
+  const markdownSiblings = pages.length > 0 && missingSiblings.length === 0;
+
+  return {
+    aiReadability: { llmsTxtPresent, linksResolve, markdownSiblings },
+    details: { llmsPath: relative(distAbs, llmsPath), brokenLinks, privateLinks, missingSiblings, pages: pages.length, siblingSuffix },
+  };
+}
+
+// ── CLI ──────────────────────────────────────────────────────────────────────
+
+async function main() {
+  const distArg = process.argv.slice(2).find((a) => !a.startsWith("--"));
+  const dist = resolve(distArg || process.env.AIR_DIST || "dist");
+  if (!(await exists(dist))) { console.error(`✗ ai-readability-gate: ${dist} not found — build first.`); process.exit(2); }
+
+  const res = await evaluateAiReadability({
+    dist,
+    llmsName: process.env.AIR_LLMS || "llms.txt",
+    siblingSuffix: process.env.AIR_SIBLING_SUFFIX || ".md",
+    siblingIgnore: (process.env.AIR_SIBLING_IGNORE ?? "404").split(",").map((s) => s.trim()).filter(Boolean),
+    privatePrefixes: (process.env.AIR_PRIVATE || "").split(",").map((s) => s.trim()).filter(Boolean),
+  });
+  const { llmsTxtPresent, linksResolve, markdownSiblings } = res.aiReadability;
+  const d = res.details;
+
+  if (process.env.AIR_REPORT) {
+    const { writeFile } = await import("node:fs/promises");
+    await writeFile(resolve(process.env.AIR_REPORT), JSON.stringify(res.aiReadability, null, 2) + "\n");
+  }
+  if (process.argv.includes("--json")) { console.log(JSON.stringify(res, null, 2)); return; }
+
+  console.log(`  ${llmsTxtPresent ? "✓" : "✗"} llms.txt present (${d.llmsPath})`);
+  console.log(`  ${linksResolve ? "✓" : "✗"} llms.txt links resolve` +
+    (d.brokenLinks.length ? ` — broken: ${d.brokenLinks.slice(0, 5).join(", ")}` : "") +
+    (d.privateLinks.length ? ` — private: ${d.privateLinks.slice(0, 5).join(", ")}` : ""));
+  console.log(`  ${markdownSiblings ? "✓" : "✗"} Markdown siblings (${d.siblingSuffix}) for ${d.pages} page(s)` +
+    (d.missingSiblings.length ? ` — missing: ${d.missingSiblings.slice(0, 5).join(", ")}` : ""));
+
+  const pass = llmsTxtPresent && linksResolve && markdownSiblings;
+  console.log(`${pass ? "✓" : "✗"} ai-readability-gate: ${pass ? "AI-readable" : "NOT AI-readable"} (semantic.ai-readability)`);
+  if (!pass && process.env.AIR_STRICT !== "0") process.exit(1);
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main().catch((e) => { console.error("✗ ai-readability-gate: error —", e.stack || e.message); process.exit(1); });
+}

package/gates/conformance/conformance.mjs

@@ -79,6 +79,53 @@ const EXTERNAL_EVALUATORS = {
       ? met(`selected AAA met (${v.criteria.length} criteria)`)
       : unmet("selected AAA not met");
   },
+  "design.palette-contrast": (e) => {
+    const v = e.palette;
+    if (!v) return notAssessed("no palette-token report supplied");
+    const gaps = [];
+    if (!v.cvdSafe) gaps.push("CVD-unsafe pairings");
+    if (!v.apcaBaseline) gaps.push("below APCA baseline");
+    if (!v.nonTextContrast) gaps.push("non-text contrast fails");
+    return gaps.length === 0
+      ? met("color tokens CVD-safe, APCA baseline, non-text contrast ok")
+      : unmet(gaps.join(", "));
+  },
+  "design.typography": (e) => {
+    const v = e.typography;
+    if (!v) return notAssessed("no typography-token report supplied");
+    const gaps = [];
+    if (!v.bodyLineHeight) gaps.push("body line-height < 1.5");
+    if (!v.textSpacingAchievable) gaps.push("text spacing not achievable");
+    if (!v.minFontSize) gaps.push("font below minimum");
+    if (!v.weightLegibility) gaps.push("thin weight illegible at size");
+    return gaps.length === 0
+      ? met("type tokens meet line-height, spacing, size, and weight bars")
+      : unmet(gaps.join(", "));
+  },
+  "design.target-size": (e) => {
+    const v = e.targetSize;
+    if (!v) return notAssessed("no target-size report supplied");
+    return v.minSizeAA
+      ? met("interactive tokens meet SC 2.5.8 AA target size")
+      : unmet("interactive tokens below SC 2.5.8 AA target size");
+  },
+  "design.opacity-contrast": (e) => {
+    const v = e.opacityContrast;
+    if (!v) return notAssessed("no opacity-contrast report supplied");
+    return v.effectiveContrast
+      ? met("effective contrast holds with token opacity composited")
+      : unmet("effective contrast fails once token opacity is composited");
+  },
+  "design.token-likeness": (e) => {
+    const v = e.tokenLikeness;
+    if (!v) return notAssessed("no token-likeness report supplied");
+    const gaps = [];
+    if (!v.distinctCategoricals) gaps.push("categorical tokens not distinct");
+    if (!v.noRedundantTokens) gaps.push("redundant near-duplicate tokens");
+    return gaps.length === 0
+      ? met("categorical tokens distinct; no redundant tokens")
+      : unmet(gaps.join(", "));
+  },
   "security.asvs": (e) => {
     const v = e.asvs;
     if (!v || v.achievedLevel == null) return notAssessed("no OWASP ASVS attestation supplied");

package/gates/conformance/web-build.mjs

@@ -132,6 +132,68 @@ export const CRITERIA = [
     required: false,
   },
 
+  // ── Design tokens — WCAG over the design system, at the source ────────────
+  // Proven over the token set BEFORE pages compose it (recommended, tier-2).
+  {
+    id: "design.palette-contrast",
+    area: "design",
+    label: "Palette contrast (design tokens)",
+    standard: "WCAG 2.2 + APCA",
+    target:
+      "Color-token pairings are CVD-safe, meet an APCA Lc baseline, and satisfy non-text contrast.",
+    level: "AA (token-level)",
+    evidence: "external",
+    required: false,
+    tier: 2,
+  },
+  {
+    id: "design.typography",
+    area: "design",
+    label: "Typography tokens",
+    standard: "WCAG 2.2",
+    target:
+      "Type tokens give body line-height ≥ 1.5, achievable text spacing (1.4.12), a minimum font size, and legible weights.",
+    level: "AA (token-level)",
+    evidence: "external",
+    required: false,
+    tier: 2,
+  },
+  {
+    id: "design.target-size",
+    area: "design",
+    label: "Target size (interactive tokens)",
+    standard: "WCAG 2.2",
+    target: "Interactive size tokens meet the SC 2.5.8 minimum target size (AA).",
+    level: "AA (token-level)",
+    evidence: "external",
+    required: false,
+    tier: 2,
+  },
+  {
+    id: "design.opacity-contrast",
+    area: "design",
+    label: "Effective contrast under opacity",
+    standard: "WCAG 2.2",
+    target:
+      "Token opacity composited over its backdrop still meets SC 1.4.3/1.4.11 contrast.",
+    level: "AA (token-level)",
+    evidence: "external",
+    required: false,
+    tier: 2,
+  },
+  {
+    id: "design.token-likeness",
+    area: "design",
+    label: "Token likeness hygiene",
+    standard: "Design-system hygiene",
+    target:
+      "Categorical tokens are perceptibly distinct and no near-duplicate (redundant) tokens collapse the system.",
+    level: "recommended",
+    evidence: "external",
+    required: false,
+    tier: 2,
+  },
+
   // ── Security — OWASP ASVS 5.0.0 ──────────────────────────────────────────
   {
     id: "security.asvs",
@@ -551,6 +613,24 @@ const ENVELOPE = {
     withCognitiveDisabilities: req(vBool),
     criticalTasksPassed: req(vBool),
   })),
+  // design-token accessibility
+  palette: opt(vObject({
+    cvdSafe: req(vBool),
+    apcaBaseline: req(vBool),
+    nonTextContrast: req(vBool),
+  })),
+  typography: opt(vObject({
+    bodyLineHeight: req(vBool),
+    textSpacingAchievable: req(vBool),
+    minFontSize: req(vBool),
+    weightLegibility: req(vBool),
+  })),
+  targetSize: opt(vObject({ minSizeAA: req(vBool) })),
+  opacityContrast: opt(vObject({ effectiveContrast: req(vBool) })),
+  tokenLikeness: opt(vObject({
+    distinctCategoricals: req(vBool),
+    noRedundantTokens: req(vBool),
+  })),
 };
 
 /**

package/gates/likeness-gate.mjs

@@ -0,0 +1,174 @@
+#!/usr/bin/env node
+// Likeness gate — token-HYGIENE + distinctness member of the Token Accessibility
+// suite. Two perceptual-distance checks over the colour tokens, both built on the
+// CIEDE2000 ΔE primitive the palette gate already ships (no duplication):
+//
+//   1. NEAR-DUPLICATE TOKENS (hygiene) — any two DISTINCT token NAMES whose colours
+//      are within ΔE < ~2 (CIEDE2000) are perceptually identical (ΔE ≈ 2.3 is the
+//      classic "just-noticeable difference" — below it the eye can't tell them
+//      apart). They're redundant: a consolidate-candidate, and a maintenance hazard
+//      (two names that silently mean the same colour drift apart later). Reported as
+//      a WARNING (it's hygiene, not a WCAG failure) — escalate via `dupSeverity`.
+//
+//   2. CONFUSABLE CATEGORICALS (a11y) — colours the consumer DECLARES must stay
+//      mutually distinguishable (status colours, chart series, map keys) are checked
+//      for collapse: every pair must stay ≥ a ΔE floor under NORMAL vision AND under
+//      deuteranopia / protanopia / tritanopia (Machado-2009). A categorical pair
+//      that collapses (especially only under a CVD) is an ERROR — it fails the
+//      design's own distinctness contract for some viewers. This reuses the palette
+//      gate's `evaluateCategorical`. Maps to the spirit of SC 1.4.1 (Use of Colour):
+//      if meaning rides on colour, the colours must actually differ for everyone.
+//
+// HONEST SCOPE: "redundant" is a perceptual claim about the token VALUES; whether a
+// near-duplicate is INTENTIONAL (e.g. a hover state 1 step away) is design intent the
+// gate can't read — hence WARNING, with the ΔE surfaced so a human decides. The
+// distinctness floor is a proxy, not a guarantee of legibility at any size.
+//
+// Zero-dependency; primitives imported from the palette gate. Fail-closed CLI.
+//
+//   node gates/likeness-gate.mjs <tokens.(json|css)> [config.json]
+//
+// INPUTS:
+//   argv[2] / $LIKENESS_TOKENS  the token map (DTCG json | tokens.css).
+//   argv[3] / $LIKENESS_CONFIG  a `config.json`:
+//     { "thresholds": { "dupDeltaE": 2, "collapseDeltaE": 10, "dupSeverity":"warn" },
+//       "ignore": ["tokenA","tokenB"],                  // names to skip in dup scan
+//       "categorical": [ { "name":"status", "members":["enforced","partial",…] } ] }
+//     (a bare `["a","b",…]` categorical array is also accepted = one unnamed group.)
+//   $LIKENESS_REPORT            path to write the machine-readable JSON report.
+//
+// Thresholds (config ⊕ env), fail closed on categorical collapse:
+//   $LIKENESS_DUP_DELTAE       (default 2)   near-duplicate ΔE ceiling
+//   $LIKENESS_COLLAPSE_DELTAE  (default 10)  categorical distinctness floor
+import { readFile, writeFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { parseHex, toHex, rgbToLab, ciede2000, loadTokens, resolveColor, evaluateCategorical } from "./palette-gate.mjs";
+
+export const DEFAULT_THRESHOLDS = {
+  dupDeltaE: 2, // CIEDE2000 — below ≈ JND ⇒ perceptually identical
+  collapseDeltaE: 10, // categorical distinctness floor (normal + CVD)
+  dupSeverity: "warn", // "warn" | "error"
+};
+
+const round2 = (n) => Math.round(n * 100) / 100;
+
+/**
+ * Scan a token map for near-duplicate colours (CIEDE2000 ΔE < dupDeltaE). Returns
+ * the unordered pairs, with ΔE and an `identical` flag (ΔE === 0, e.g. two aliases
+ * of the same primitive). Pure.
+ */
+export function findNearDuplicates(tokenMap, thresholds = DEFAULT_THRESHOLDS, ignore = []) {
+  const t = { ...DEFAULT_THRESHOLDS, ...thresholds };
+  const skip = new Set(ignore);
+  const entries = Object.entries(tokenMap)
+    .filter(([k]) => !skip.has(k))
+    .map(([name, hex]) => { try { return { name, rgb: parseHex(hex), hex: toHex(parseHex(hex)) }; } catch { return null; } })
+    .filter(Boolean);
+  const dups = [];
+  for (let i = 0; i < entries.length; i++) {
+    for (let j = i + 1; j < entries.length; j++) {
+      const A = entries[i], B = entries[j];
+      const dE = ciede2000(rgbToLab(A.rgb), rgbToLab(B.rgb));
+      if (dE + 1e-9 < t.dupDeltaE) {
+        dups.push({ a: A.name, b: B.name, aHex: A.hex, bHex: B.hex, deltaE: round2(dE), identical: dE === 0 });
+      }
+    }
+  }
+  dups.sort((x, y) => x.deltaE - y.deltaE);
+  return { threshold: t.dupDeltaE, count: dups.length, duplicates: dups };
+}
+
+/** Normalize the config's categorical groups to [{ name, members:[{ref,hex}] }]. */
+function resolveGroups(config, map) {
+  let groups = config.categorical || [];
+  if (Array.isArray(groups) && groups.every((g) => typeof g === "string")) groups = [{ name: "categorical", members: groups }];
+  return groups.map((g) => ({
+    name: g.name || "categorical",
+    members: (g.members || []).map((ref) => ({ ref, hex: resolveColor(map, ref) })),
+  }));
+}
+
+/** Whole-suite evaluation → fail-closed report. Pure given resolved inputs. */
+export function evaluateLikeness({ tokenMap = {}, groups = [], thresholds = DEFAULT_THRESHOLDS, ignore = [] } = {}) {
+  const t = { ...DEFAULT_THRESHOLDS, ...thresholds };
+  const near = findNearDuplicates(tokenMap, t, ignore);
+
+  const categorical = groups.map((g) => {
+    const res = evaluateCategorical(g.members, { collapseDeltaE: t.collapseDeltaE });
+    return { name: g.name, members: g.members.map((m) => ({ ref: m.ref, hex: toHex(parseHex(m.hex)) })), ...res };
+  });
+  const collapseCount = categorical.reduce((n, c) => n + c.count, 0);
+
+  const dupIsError = t.dupSeverity === "error";
+  const errors = (dupIsError ? near.count : 0) + collapseCount;
+
+  return {
+    passed: errors === 0,
+    thresholds: t,
+    summary: {
+      tokens: Object.keys(tokenMap).length,
+      nearDuplicates: near.count,
+      identicalPairs: near.duplicates.filter((d) => d.identical).length,
+      categoricalGroups: categorical.length,
+      categoricalCollapses: collapseCount,
+    },
+    nearDuplicates: near,
+    categorical,
+    // Envelope a future lone `likeness.*` criterion can consume.
+    likeness: {
+      distinctCategoricals: collapseCount === 0,
+      noRedundantTokens: near.count === 0,
+    },
+  };
+}
+
+export async function runLikenessGate({ tokens, config = {}, thresholds = {} }) {
+  const map = typeof tokens === "string" ? await loadTokens(tokens) : tokens;
+  const cfg = typeof config === "string" ? JSON.parse(await readFile(config, "utf8")) : config;
+  const groups = resolveGroups(cfg, map);
+  return evaluateLikeness({
+    tokenMap: map,
+    groups,
+    ignore: cfg.ignore || [],
+    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("dupDeltaE", "LIKENESS_DUP_DELTAE");
+  set("collapseDeltaE", "LIKENESS_COLLAPSE_DELTAE");
+  if (process.env.LIKENESS_DUP_SEVERITY) t.dupSeverity = process.env.LIKENESS_DUP_SEVERITY;
+  return t;
+}
+
+async function main() {
+  const argv = process.argv.slice(2).filter((a) => !a.startsWith("--"));
+  const tokens = argv[0] || process.env.LIKENESS_TOKENS;
+  const config = argv[1] || process.env.LIKENESS_CONFIG;
+  if (!tokens) {
+    console.error("✗ likeness-gate: usage: likeness-gate.mjs <tokens.(json|css)> [config.json]  (or set $LIKENESS_TOKENS)");
+    process.exit(2);
+  }
+  const report = await runLikenessGate({ tokens, config: config || {}, thresholds: envThresholds() });
+  if (process.env.LIKENESS_REPORT) await writeFile(resolve(process.env.LIKENESS_REPORT), JSON.stringify(report, null, 2) + "\n");
+
+  const s = report.summary;
+  const line = `likeness-gate: ${s.tokens} token(s) — ${s.nearDuplicates} near-duplicate(s) (${s.identicalPairs} identical), ${s.categoricalCollapses} categorical collapse(s)`;
+  const dupLine = (d) => `  · ${d.identical ? "identical" : "near-dup"}: ${d.a} ≈ ${d.b} (${d.aHex}/${d.bHex}) ΔE ${d.deltaE}`;
+  const colLine = (c) => `  · collapse: ${c.a} vs ${c.b} (${c.aHex}/${c.bHex}) under ${c.condition} — ΔE ${c.deltaE} < ${c.min}`;
+  if (!report.passed) {
+    console.error(`✗ ${line}`);
+    for (const c of report.categorical) for (const x of c.collapses) console.error(colLine(x));
+    if (report.thresholds.dupSeverity === "error") for (const d of report.nearDuplicates.duplicates) console.error(dupLine(d));
+    process.exit(1);
+  }
+  console.log(`✓ ${line}`);
+  for (const d of report.nearDuplicates.duplicates) console.log(dupLine(d)); // hygiene warnings
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main().catch((e) => { console.error("✗ likeness-gate: error —", e.stack || e.message); process.exit(1); });
+}