@fringetools/cli 0.2.0 → 0.2.2

package/README.md

@@ -23,7 +23,8 @@ Prefer a permanent command? `npm install -D @fringetools/cli`, then `npx fringe
 |---|---|
 | `fringe check [dir\|file]` | Scan a directory (default `.`) or judge one file (the project root is found by climbing to the nearest `package.json`). Prints findings and the health score. Exit `1` on any `error`. |
 | `fringe plan [dir\|file] [--json] [--limit n]` | **Fix order for a repo with many findings**: P0 (errors in shared components or critical paths) → P1 (other errors, mechanical first) → P2 review → P3 polish, each cluster with its fix recipe. Never gates (exit 0). `--json` = `fringe/plan.v1`. |
-| `fringe explain [FR-203]` | Why a rule matters, the preferred fix and the tempting fix to avoid. No id lists all 29 rules. |
+| `fringe explain [FR-203]` | Why a rule matters, the preferred fix and the tempting fix to avoid. No id lists all 36 rules. |
+| `fringe explain pattern [form]` | Build-time best-practice checklist for a component type (`form`, `modal`, `navigation`, `data-view`); each item is marked *verified* (a rule checks it) or *judged*. |
 | `fringe check --json` | Full report as JSON, schema `fringe/check.v1` (stack, files, findings, counts, score). |
 | `fringe check --claude-hook` | **For Claude Code hooks.** Silent when clean; on errors prints `{"decision":"block","reason":…}` (exit 0) so the agent sees and fixes them. |
 | `fringe check --hook` | One-line `fringe/hook.v1` JSON for CI / pre-commit. Exits `1` on errors. Claude Code does **not** feed this back — use `--claude-hook` for agents. Wins over `--json`. |
@@ -118,6 +119,8 @@ After each edit the hook runs; with errors it returns, for example:
 {"decision":"block","reason":"Fringe found 2 accessibility error(s). Fix them before finishing:\n- FR-203 src/Signup.tsx:9 — input not associated with a label (add id + <label htmlFor>, or aria-label)\n…"}
 ```
 
+The hook also keeps `.fringe/last.json` (the previous run's errors) and tells the agent what its **last edit broke**: "Your last edit introduced 1 new error(s) and fixed 2; 3 failing in total", with the new ones listed first and marked `NEW`. If that file is missing or unreadable it simply skips the comparison. It still blocks on every remaining error; on a legacy repo use the baseline so old debt is not nagged about.
+
 This was verified end to end with real agent runs: the agent receives the findings and fixes them (see [docs/architecture.md](../../docs/architecture.md)). Why `--claude-hook` and not `--hook`: Claude Code only passes a hook's output to the agent as `decision`/`reason` JSON on exit 0 (or stderr on exit 2); the CI contract `--hook` exits 1 and is ignored.
 
 **Skills** — `fringe init` installs five into `.claude/skills/` (sources in [skill/](skill/), one folder each); the Claude Code plugin ships the same folders, namespaced `/fringe:…`: `fringe` (below), `fringe-review` ("review this page": ranked, plain-English findings with fixes), `fringe-audit` (whole-repo plan: top rules and files, a fix order, offers `--update-baseline`), `fringe-debt` (lists `fringe-ignore` suppressions and the baseline) and `fringe-help` (quick reference). Invoke as `/fringe-review` etc. Reviews run `fringe check`, so Claude Code will ask you to approve that command once (or allow `Bash(fringe:*)` / `Bash(npx:*)`).
@@ -157,6 +160,12 @@ Severity `error` fails the run; `review` and `signal` are heuristics that need a
 | FR-213 | review | | dark pattern — infinite scroll without opt-out |
 | FR-214 | review | | dark pattern — bait-and-switch ("free", then a price) pricing |
 | FR-215 | review | | generic error copy ("something went wrong") with no recovery action — no retry, link, or contact |
+| FR-216 | review | | form basics — email/phone field with the wrong `type`, password field with no `autocomplete` |
+| FR-217 | review | | link text that says nothing out of context ("click here"), `href="#"` / `javascript:` links |
+| FR-218 | review | 3.1.1 · 2.4.2 · 1.4.4 | full HTML documents: no `lang`, no `<title>`, viewport that blocks pinch-zoom (fragments are skipped) |
+| FR-219 | review | | `@keyframes` animation in a stylesheet with no `prefers-reduced-motion` handling (judged per file) |
+| FR-220 | review | 1.4.2 | `<video>`/`<audio>` that autoplays with sound |
+| FR-221 | review | 1.4.13 | element that reacts to hover only (no focus, click or touch handler) |
 
 The dark-pattern taxonomy (FR-210–214) is adapted, with attribution, from [Design with Intent](https://designwithintent.ai)'s CC0 anti-pattern library.
 
@@ -180,6 +189,7 @@ The dark-pattern taxonomy (FR-210–214) is adapted, with attribution, from [Des
 | FR-367 | signal | | numbered section labels — "01 Discover" style kickers |
 | FR-368 | signal | | the purple AI gradient — violet/indigo Tailwind gradient or its CSS hex equivalent |
 | FR-369 | signal | | emoji in headings |
+| FR-222 | signal | | lorem ipsum / TODO / `[insert …]` text left in the UI |
 
 **FR-304 scope in v1:** contrast is checked only on CSS pairs — a `color` declaration and a `background-color` (or pure-color `background`) in the *same* CSS rule block. Tailwind utility classes in markup are not pair-checked, and translucent colors (alpha < 1) are skipped because contrast over an unknown backdrop is unknowable.
 

package/dist/bin.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   runCli
-} from "./chunk-ZK2GPUZF.js";
+} from "./chunk-TNZKMKKQ.js";
 
 // src/bin.ts
 process.exitCode = await runCli(process.argv.slice(2));

package/dist/{chunk-ZK2GPUZF.js → chunk-TNZKMKKQ.js}

@@ -1,10 +1,10 @@
 // src/index.ts
 import { randomUUID } from "crypto";
-import { existsSync as existsSync3, readFileSync as readFileSync8, statSync } from "fs";
-import { dirname as dirname2, join as join8, resolve } from "path";
+import { existsSync as existsSync3, readFileSync as readFileSync9, statSync } from "fs";
+import { dirname as dirname2, join as join9, resolve } from "path";
 
 // src/version.ts
-var VERSION = "0.2.0";
+var VERSION = "0.2.2";
 
 // src/check.ts
 import { readFileSync as readFileSync5 } from "fs";
@@ -144,7 +144,7 @@ function collectText(node) {
   }
   return t.trim();
 }
-function parseJsx(file, source) {
+function parseJsx(file2, source) {
   let ast;
   try {
     ast = parse(source, { sourceType: "unambiguous", plugins: ["jsx", "typescript"], errorRecovery: false });
@@ -162,7 +162,7 @@ function parseJsx(file, source) {
       for (const a of node.openingElement.attributes) {
         if (a.type === "JSXAttribute") attrs[a.name.name] = attrValue(a.value);
       }
-      const el = { tag: tag2, attrs, text: collectText(node), loc: { file, line: node.loc?.start.line ?? 0, col: node.loc?.start.column ?? 0 } };
+      const el = { tag: tag2, attrs, text: collectText(node), loc: { file: file2, line: node.loc?.start.line ?? 0, col: node.loc?.start.column ?? 0 } };
       if (parent) el.parentTag = parent.tag;
       if (parent?.inLabel) el.inLabel = true;
       if (parent?.attrs?.className !== void 0) el.parentClass = parent.attrs.className;
@@ -181,7 +181,7 @@ function parseJsx(file, source) {
 // src/parse/html.ts
 import { parse as parse2 } from "parse5";
 var textOf = (n) => n.nodeName === "#text" ? n.value : (n.childNodes ?? []).map(textOf).join("");
-function parseHtml(file, source) {
+function parseHtml(file2, source) {
   const doc = parse2(source, { sourceCodeLocationInfo: true });
   const elems = [];
   (function walkNode(node, parent) {
@@ -189,7 +189,7 @@ function parseHtml(file, source) {
       const attrs = {};
       for (const a of node.attrs ?? []) attrs[a.name] = a.value;
       const text = textOf(node).trim();
-      const el = { tag: node.tagName, attrs, text, loc: { file, line: node.sourceCodeLocation?.startLine ?? 0, col: node.sourceCodeLocation?.startCol ?? 0 } };
+      const el = { tag: node.tagName, attrs, text, loc: { file: file2, line: node.sourceCodeLocation?.startLine ?? 0, col: node.sourceCodeLocation?.startCol ?? 0 } };
       if (parent) el.parentTag = parent.tag;
       if (parent?.inLabel) el.inLabel = true;
       if (parent?.attrs?.class !== void 0) el.parentClass = parent.attrs.class;
@@ -204,12 +204,12 @@ function parseHtml(file, source) {
 
 // src/parse/css.ts
 import postcss from "postcss";
-function parseCss(file, source) {
+function parseCss(file2, source) {
   const decls = [];
   const rec = (node, selector) => {
     for (const child of node.nodes ?? []) {
       if (child.type === "decl") {
-        decls.push({ prop: child.prop, value: String(child.value), selector, loc: { file, line: child.source?.start?.line ?? 0, col: child.source?.start?.column ?? 0 } });
+        decls.push({ prop: child.prop, value: String(child.value), selector, loc: { file: file2, line: child.source?.start?.line ?? 0, col: child.source?.start?.column ?? 0 } });
       } else if (child.type === "rule" || child.type === "atrule") {
         rec(child, child.type === "rule" ? child.selector : selector);
       }
@@ -457,6 +457,113 @@ var fr215 = {
   }
 };
 
+// src/rules/fr216.ts
+var NOT_TEXT = /* @__PURE__ */ new Set(["hidden", "checkbox", "radio", "submit", "button", "file", "range", "color", "image", "reset"]);
+var short = (s = "") => s.length <= 24 ? s : "";
+var cat = (a) => `${a.name ?? ""} ${a.id ?? ""} ${short(a.placeholder)} ${short(a["aria-label"])}`.toLowerCase();
+var fr216 = {
+  id: "FR-216",
+  rung: 2,
+  severity: "review",
+  check: (ctx) => {
+    const out = [];
+    for (const e of ctx.elems) {
+      if (e.tag !== "input" || e.attrs.type === "{\u2026}") continue;
+      const type = (e.attrs.type ?? "text").toLowerCase();
+      if (NOT_TEXT.has(type)) continue;
+      const hint = cat(e.attrs);
+      if (/search|filter|find/.test(hint)) continue;
+      const flag = (message, h) => out.push({ rule: "FR-216", severity: "review", message, hint: h, loc: e.loc });
+      if (/e-?mail/.test(hint) && type !== "email") flag(`email field is type="${type}"`, 'use type="email" so phones show the right keyboard and the browser validates');
+      else if (/\b(tel|phone|mobile)\b/.test(hint) && type !== "tel") flag(`phone field is type="${type}"`, 'use type="tel" for the numeric keypad');
+      if (type === "password" && e.attrs.autocomplete === void 0 && e.attrs.autoComplete === void 0) flag("password field without autocomplete", 'add autoComplete="current-password" or "new-password" so password managers work');
+    }
+    return out;
+  }
+};
+
+// src/rules/fr217.ts
+var VAGUE = /^(click here|here|read more|more|link|this link)$/i;
+var fr217 = {
+  id: "FR-217",
+  rung: 2,
+  severity: "review",
+  check: (ctx) => {
+    const out = [];
+    for (const e of ctx.elems) {
+      if (e.tag !== "a") continue;
+      const href = e.attrs.href ?? "";
+      if (VAGUE.test(e.text) && !e.attrs["aria-label"] && !e.attrs["aria-labelledby"])
+        out.push({ rule: "FR-217", severity: "review", message: `link text "${e.text}" says nothing out of context`, hint: 'name the destination or action ("Read the pricing guide"); screen reader users list links on their own', loc: e.loc });
+      if (href === "#" || /^javascript:/i.test(href))
+        out.push({ rule: "FR-217", severity: "review", message: `link with href="${href.slice(0, 11)}" goes nowhere`, hint: "use a <button> for an action, or a real URL for navigation", loc: e.loc });
+    }
+    return out;
+  }
+};
+
+// src/rules/fr218.ts
+var fr218 = {
+  id: "FR-218",
+  rung: 2,
+  severity: "review",
+  check: (ctx) => {
+    if (!/<html[\s>]/i.test(ctx.source)) return [];
+    const out = [];
+    const html = ctx.elems.find((e) => e.tag === "html");
+    if (html && html.attrs.lang === void 0)
+      out.push({ rule: "FR-218", severity: "review", message: "<html> has no lang attribute", hint: 'add lang="en" (or the page language) so screen readers pick the right voice', loc: html.loc, wcag: "3.1.1" });
+    if (!/<title[\s>]/i.test(ctx.source) && html && /<head[\s>]/i.test(ctx.source))
+      out.push({ rule: "FR-218", severity: "review", message: "page has no <title>", hint: "add a unique, descriptive <title>: it is the first thing a screen reader announces and the browser tab label", loc: html.loc, wcag: "2.4.2" });
+    for (const m of ctx.elems.filter((e) => e.tag === "meta" && e.attrs.name === "viewport")) {
+      if (/user-scalable\s*=\s*(no|0)|maximum-scale\s*=\s*1(\.0)?\b/i.test(m.attrs.content ?? ""))
+        out.push({ rule: "FR-218", severity: "review", message: "viewport meta blocks pinch-zoom", hint: "remove user-scalable=no / maximum-scale=1: low-vision users rely on zoom", loc: m.loc, wcag: "1.4.4" });
+    }
+    return out;
+  }
+};
+
+// src/rules/fr219.ts
+var fr219 = {
+  id: "FR-219",
+  rung: 3,
+  severity: "review",
+  check: (ctx) => {
+    if (!/@keyframes/.test(ctx.source) || /prefers-reduced-motion/.test(ctx.source)) return [];
+    const d = ctx.css.find((x) => x.prop === "animation" || x.prop === "animation-name");
+    if (!d) return [];
+    return [{ rule: "FR-219", severity: "review", message: "animation defined with no prefers-reduced-motion handling", hint: "wrap it in @media (prefers-reduced-motion: no-preference), or turn it off under (prefers-reduced-motion: reduce)", loc: d.loc }];
+  }
+};
+
+// src/rules/fr220.ts
+var fr220 = {
+  id: "FR-220",
+  rung: 2,
+  severity: "review",
+  check: (ctx) => ctx.elems.filter((e) => (e.tag === "video" || e.tag === "audio") && (e.attrs.autoPlay !== void 0 || e.attrs.autoplay !== void 0) && e.attrs.muted === void 0).map((e) => ({ rule: "FR-220", severity: "review", message: `<${e.tag}> autoplays with sound`, hint: "start muted (and offer controls), or wait for a user action; browsers block it anyway and it startles screen reader users", loc: e.loc, wcag: "1.4.2" }))
+};
+
+// src/rules/fr221.ts
+var HOVER = ["onMouseEnter", "onMouseOver", "onmouseenter", "onmouseover"];
+var FOCUS = ["onFocus", "onfocus"];
+var PRESS = ["onClick", "onclick", "onTouchStart", "ontouchstart"];
+var fr221 = {
+  id: "FR-221",
+  rung: 2,
+  severity: "review",
+  check: (ctx) => ctx.elems.filter((e) => HOVER.some((h) => e.attrs[h] !== void 0) && !FOCUS.some((f) => e.attrs[f] !== void 0) && !PRESS.some((p) => e.attrs[p] !== void 0)).map((e) => ({ rule: "FR-221", severity: "review", message: `<${e.tag}> reacts to hover only`, hint: "mirror it on focus (onFocus/onBlur) and tap: keyboard and touch users cannot hover", loc: e.loc, wcag: "1.4.13" }))
+};
+
+// src/rules/fr222.ts
+var FILLER = /\blorem ipsum\b|\b(TODO|FIXME|TBD)\b|\[(insert|your)[^\]]*\]/i;
+var fr222 = {
+  id: "FR-222",
+  rung: 3,
+  severity: "signal",
+  check: (ctx) => ctx.elems.filter((e) => FILLER.test(e.text) || FILLER.test(e.attrs.placeholder ?? "") || FILLER.test(e.attrs["aria-label"] ?? "")).map((e) => ({ rule: "FR-222", severity: "signal", message: "placeholder or unfinished text in the UI", hint: "replace lorem ipsum / TODO / [insert ...] with real copy before shipping", loc: e.loc }))
+};
+
 // src/color.ts
 var clamp255 = (n) => Math.min(255, Math.max(0, Math.round(n)));
 function splitArgs(argStr) {
@@ -919,7 +1026,7 @@ var fr369 = {
 
 // src/rules/registry.ts
 var ALL_RULES = [];
-ALL_RULES.push(fr201, fr202, fr203, fr204, fr205, fr206, fr207, fr208, fr209, fr210, fr211, fr212, fr213, fr214, fr215, fr301, fr302, fr303, fr304, fr305, fr361, fr362, fr363, fr364, fr366, fr365, fr367, fr368, fr369);
+ALL_RULES.push(fr201, fr202, fr203, fr204, fr205, fr206, fr207, fr208, fr209, fr210, fr211, fr212, fr213, fr214, fr215, fr216, fr217, fr218, fr219, fr220, fr221, fr222, fr301, fr302, fr303, fr304, fr305, fr361, fr362, fr363, fr364, fr366, fr365, fr367, fr368, fr369);
 function activeRules(cfg) {
   return ALL_RULES.filter((r) => !cfg.disable.includes(r.id));
 }
@@ -949,10 +1056,10 @@ function gatherTokenColors(root, cfg, cssSources) {
   const kind = cfg.tokenSource?.kind;
   if (kind === "design-tokens-json") {
     const rel = cfg.tokenSource?.path ?? "";
-    const file = isAbsolute(rel) ? rel : join4(root, rel);
+    const file2 = isAbsolute(rel) ? rel : join4(root, rel);
     let json;
     try {
-      json = JSON.parse(readFileSync3(file, "utf8"));
+      json = JSON.parse(readFileSync3(file2, "utf8"));
     } catch {
       return out;
     }
@@ -1111,6 +1218,46 @@ var GUIDANCE = {
     recipe: "Say what failed in plain words and give a next step: retry, a link, or a way to contact support.",
     fixability: "judgment"
   },
+  "FR-216": {
+    why: "The wrong input type gives the wrong keyboard on phones and skips built-in validation; no autocomplete blocks password managers and autofill.",
+    recipe: 'Use type="email" / "tel" / "password", and set autoComplete (email, tel, current-password, new-password, name).',
+    avoid: 'type="text" for everything.',
+    example: { before: '<input type="text" name="email" />', after: '<input type="email" name="email" autoComplete="email" />' },
+    fixability: "mechanical"
+  },
+  "FR-217": {
+    why: 'Screen reader users browse a list of links out of context, so "click here" says nothing; href="#" links go nowhere.',
+    recipe: "Name the destination or action in the link text. Use a <button> for an action, a real URL for navigation.",
+    avoid: '"click here", "read more", or href="#" with an onClick.',
+    example: { before: '<a href="#" onClick={save}>Save</a>', after: '<button type="button" onClick={save}>Save</button>' },
+    fixability: "mechanical"
+  },
+  "FR-218": {
+    why: "A missing lang makes screen readers use the wrong voice; a missing title leaves the tab and the page unnamed; a viewport that blocks zoom shuts out low-vision users.",
+    recipe: 'Set <html lang="en"> (the real language), add a unique <title>, and remove user-scalable=no / maximum-scale=1 from the viewport meta.',
+    avoid: 'Blocking zoom to "fix" a layout problem.',
+    fixability: "mechanical"
+  },
+  "FR-219": {
+    why: "Motion can trigger nausea or distraction for some users, and they can ask their system to reduce it.",
+    recipe: "Wrap the animation in @media (prefers-reduced-motion: no-preference), or disable it under (prefers-reduced-motion: reduce).",
+    fixability: "mechanical"
+  },
+  "FR-220": {
+    why: "Sound that starts on its own startles users and talks over a screen reader; browsers block it anyway.",
+    recipe: "Start muted and show controls, or play only after a user action.",
+    fixability: "mechanical"
+  },
+  "FR-221": {
+    why: "A hover-only reaction cannot be reached with a keyboard or a touchscreen.",
+    recipe: "Do the same on focus (onFocus/onBlur) and on tap/click, and make the element focusable.",
+    fixability: "mechanical"
+  },
+  "FR-222": {
+    why: "Lorem ipsum and TODO text that ships makes the product look unfinished.",
+    recipe: "Replace it with real copy before release.",
+    fixability: "judgment"
+  },
   "FR-301": {
     why: "Hardcoded colors drift from the design system and make theming painful.",
     recipe: "Use the project tokens (CSS variables or palette utilities) instead of literal hex values.",
@@ -1239,25 +1386,25 @@ async function runCheck(root, cfg = loadConfig(root), useBaseline = true, only)
   const skipped = [];
   const cssSources = [];
   const contexts = [];
-  for (const file of files) {
+  for (const file2 of files) {
     let source = "";
     try {
-      source = readFileSync5(file, "utf8");
+      source = readFileSync5(file2, "utf8");
     } catch {
-      skipped.push(file);
+      skipped.push(file2);
       continue;
     }
-    const ctx = { file, source, elems: [], css: [], tokenColors: [] };
+    const ctx = { file: file2, source, elems: [], css: [], tokenColors: [] };
     try {
-      if (/\.(jsx|tsx|js|ts)$/.test(file)) ctx.elems = parseJsx(file, source);
-      else if (/\.html$/.test(file)) ctx.elems = parseHtml(file, source);
-      else if (/\.(css|scss)$/.test(file)) {
-        ctx.css = parseCss(file, source);
-        cssSources.push({ file, source });
+      if (/\.(jsx|tsx|js|ts)$/.test(file2)) ctx.elems = parseJsx(file2, source);
+      else if (/\.html$/.test(file2)) ctx.elems = parseHtml(file2, source);
+      else if (/\.(css|scss)$/.test(file2)) {
+        ctx.css = parseCss(file2, source);
+        cssSources.push({ file: file2, source });
       }
     } catch (e) {
       if (e.message.startsWith("parse-skip")) {
-        skipped.push(file);
+        skipped.push(file2);
         continue;
       }
       throw e;
@@ -1307,10 +1454,14 @@ function toHook(r) {
     reason
   });
 }
-function toClaudeHook(r, root) {
-  const errs = r.findings.filter((f) => f.severity === "error");
-  if (errs.length === 0) return "";
-  const shown = errs.slice(0, 8).map((f) => `- ${f.rule} ${relative4(root, f.loc.file)}:${f.loc.line} \u2014 ${f.message} (${f.hint})`);
+function toClaudeHook(r, root, history) {
+  const all = r.findings.filter((f) => f.severity === "error");
+  if (all.length === 0) return "";
+  const fresh = new Set(history?.introduced);
+  const errs = [...all.filter((f) => fresh.has(f)), ...all.filter((f) => !fresh.has(f))];
+  const note = history && (history.introduced.length > 0 || history.fixed > 0) ? `Your last edit introduced ${history.introduced.length} new error(s)${history.fixed ? ` and fixed ${history.fixed}` : ""}; ${errs.length} failing in total. New ones are marked NEW.
+` : "";
+  const shown = errs.slice(0, 8).map((f) => `- ${fresh.has(f) ? "NEW " : ""}${f.rule} ${relative4(root, f.loc.file)}:${f.loc.line} \u2014 ${f.message} (${f.hint})`);
   const shownRules = [...new Set(errs.slice(0, 8).map((f) => f.rule))];
   const recipes = shownRules.map((id) => {
     const g = GUIDANCE[id];
@@ -1320,7 +1471,7 @@ function toClaudeHook(r, root) {
 \u2026and ${errs.length - shown.length} more (run \`fringe check\`).` : "";
   return JSON.stringify({
     decision: "block",
-    reason: `Fringe found ${errs.length} accessibility error(s). Fix them before finishing:
+    reason: `${note}Fringe found ${errs.length} accessibility error(s). Fix them before finishing:
 ${shown.join("\n")}${more}
 How to fix them well:
 ${recipes.join("\n")}
@@ -1415,19 +1566,51 @@ function startBoard(root, port) {
   });
 }
 
+// src/receipts.ts
+import { mkdirSync as mkdirSync2, readFileSync as readFileSync7, writeFileSync as writeFileSync2 } from "fs";
+import { join as join7 } from "path";
+var file = (root) => join7(root, ".fringe", "last.json");
+function receipts(root, findings) {
+  const errs = findings.filter((f) => f.severity === "error");
+  const keys = errs.map((f) => keyOf(root, f));
+  let prev;
+  try {
+    const p = JSON.parse(readFileSync7(file(root), "utf8"));
+    if (Array.isArray(p)) prev = p;
+  } catch {
+  }
+  try {
+    mkdirSync2(join7(root, ".fringe"), { recursive: true });
+    writeFileSync2(file(root), JSON.stringify(keys));
+  } catch {
+  }
+  if (!prev) return void 0;
+  const left = /* @__PURE__ */ new Map();
+  for (const k of prev) left.set(k, (left.get(k) ?? 0) + 1);
+  const introduced = errs.filter((f, i) => {
+    const n = left.get(keys[i]) ?? 0;
+    if (n > 0) {
+      left.set(keys[i], n - 1);
+      return false;
+    }
+    return true;
+  });
+  return { introduced, fixed: [...left.values()].reduce((a, b) => a + b, 0) };
+}
+
 // src/init.ts
-import { existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync as readFileSync7, readdirSync as readdirSync3, writeFileSync as writeFileSync2, copyFileSync } from "fs";
-import { dirname, join as join7 } from "path";
+import { existsSync as existsSync2, mkdirSync as mkdirSync3, readFileSync as readFileSync8, readdirSync as readdirSync3, writeFileSync as writeFileSync3, copyFileSync } from "fs";
+import { dirname, join as join8 } from "path";
 import { fileURLToPath } from "url";
 var HOOK = "npx -y @fringetools/cli check --claude-hook";
 var SKILL_DIR = fileURLToPath(new URL("../skill/", import.meta.url));
 function initProject(root) {
   const done = [];
-  const settingsPath = join7(root, ".claude", "settings.json");
+  const settingsPath = join8(root, ".claude", "settings.json");
   let settings = {};
   if (existsSync2(settingsPath)) {
     try {
-      settings = JSON.parse(readFileSync7(settingsPath, "utf8"));
+      settings = JSON.parse(readFileSync8(settingsPath, "utf8"));
     } catch {
       throw new Error(`${settingsPath} is not valid JSON \u2014 fix it and rerun`);
     }
@@ -1436,22 +1619,79 @@ function initProject(root) {
   if (/(fringe|@fringetools\/cli) check/.test(JSON.stringify(post))) done.push("hook already present");
   else {
     post.push({ matcher: "Edit|Write", hooks: [{ type: "command", command: HOOK }] });
-    mkdirSync2(dirname(settingsPath), { recursive: true });
-    writeFileSync2(settingsPath, JSON.stringify(settings, null, 2) + "\n");
+    mkdirSync3(dirname(settingsPath), { recursive: true });
+    writeFileSync3(settingsPath, JSON.stringify(settings, null, 2) + "\n");
     done.push(`hook added to ${settingsPath}`);
   }
   for (const name of readdirSync3(SKILL_DIR)) {
-    const skillPath = join7(root, ".claude", "skills", name, "SKILL.md");
+    const skillPath = join8(root, ".claude", "skills", name, "SKILL.md");
     if (existsSync2(skillPath)) done.push(`skill ${name} already present`);
     else {
-      mkdirSync2(dirname(skillPath), { recursive: true });
-      copyFileSync(join7(SKILL_DIR, name, "SKILL.md"), skillPath);
+      mkdirSync3(dirname(skillPath), { recursive: true });
+      copyFileSync(join8(SKILL_DIR, name, "SKILL.md"), skillPath);
       done.push(`skill ${name} installed`);
     }
   }
   return done;
 }
 
+// src/patterns.ts
+var PATTERNS = {
+  form: {
+    title: "Form",
+    items: [
+      { text: "Every field has a visible <label> bound with htmlFor/id", rules: ["FR-203"] },
+      { text: "Right input type and autocomplete (email, tel, current-password, new-password, name)", rules: ["FR-216"] },
+      { text: "Required fields are marked in text, not by color alone" },
+      { text: "Errors appear next to the field in words, linked with aria-describedby and aria-invalid; focus moves to the first error on submit" },
+      { text: "The submit button shows a pending state and cannot be double-submitted" },
+      { text: "Input is kept when an error occurs; validation runs on blur, not on every keystroke" }
+    ]
+  },
+  modal: {
+    title: "Modal dialog",
+    items: [
+      { text: 'role="dialog" with aria-modal="true" and a name (aria-labelledby the title)', rules: ["FR-209"] },
+      { text: "Focus moves in on open, stays trapped inside, and returns to the trigger on close" },
+      { text: "A visible Close button with an accessible name, and Escape closes", rules: ["FR-202"] },
+      { text: "Clicking the backdrop may close it but is never the only way", rules: ["FR-206"] },
+      { text: "The page behind is inert and does not scroll" }
+    ]
+  },
+  navigation: {
+    title: "Navigation",
+    items: [
+      { text: "Links use real hrefs and describe the destination", rules: ["FR-217"] },
+      { text: "A <nav> landmark (labelled if there are several), one <main>, and a skip-to-content link" },
+      { text: 'The current page is marked with aria-current="page"' },
+      { text: "Menus open by keyboard and tap, not by hover alone", rules: ["FR-221"] },
+      { text: "Focus is always visible", rules: ["FR-205"] },
+      { text: "Tap targets are large enough", rules: ["FR-305"] }
+    ]
+  },
+  "data-view": {
+    title: "Data view (list, table, dashboard)",
+    items: [
+      { text: "A loading state with a text label, an empty state that says what to do next, and an error state with a retry", rules: ["FR-208", "FR-215"] },
+      { text: "Layout does not jump when data arrives (reserve the space)" },
+      { text: "Async updates are announced (aria-live) when the user did not trigger them" },
+      { text: "Table headers use <th> and a caption or accessible name" }
+    ]
+  }
+};
+function renderPatterns(name) {
+  if (!name) return Object.entries(PATTERNS).map(([k, p2]) => `${k.padEnd(11)} ${p2.title}`).join("\n");
+  const p = PATTERNS[name.toLowerCase()];
+  if (!p) return void 0;
+  const mark = (i) => i.rules ? `[verified: ${i.rules.join(", ")}]` : "[judged]";
+  return [
+    `${p.title}: build it like this`,
+    ...p.items.map((i) => `- ${i.text}  ${mark(i)}`),
+    "",
+    "verified = Fringe checks it; judged = you decide, so state your evidence in the final message."
+  ].join("\n");
+}
+
 // src/report/plan.ts
 var TITLES = {
   P0: ["Fix first", "errors in shared components or critical paths: one fix clears many uses"],
@@ -1518,7 +1758,7 @@ var err = (o) => o.err ?? ((s) => process.stderr.write(s));
 function readManifest(path2, warn) {
   let raw;
   try {
-    raw = readFileSync8(path2, "utf8");
+    raw = readFileSync9(path2, "utf8");
   } catch {
     warn(`fringe: warning: manifest not found at ${path2} \u2014 continuing without
 `);
@@ -1545,7 +1785,7 @@ function resolveTarget(arg) {
   if (!statSync(arg).isFile()) return { root: arg };
   let dir = dirname2(arg);
   for (let d = dir, i = 0; i < 12; i++, d = dirname2(d)) {
-    if (existsSync3(join8(d, "package.json")) || existsSync3(join8(d, "fringe.config.json"))) {
+    if (existsSync3(join9(d, "package.json")) || existsSync3(join9(d, "fringe.config.json"))) {
       dir = d;
       break;
     }
@@ -1558,6 +1798,7 @@ var HELP = `fringe check [--json] [--hook] [--record] [--manifest <path>] [path]
 fringe check --claude-hook [path]       for Claude Code hooks (feeds errors back to the agent)
 fringe check --update-baseline [path]   accept today's findings; only new ones gate
 fringe plan [dir|file] [--json] [--limit n]   ordered fix batches with recipes
+fringe explain pattern [form]           best-practice checklist for a component type
 fringe explain [FR-203]                 why a rule matters and how to fix it well
 fringe init [path]                       add the Claude Code hook + skill
 fringe open [path] [--port <n>]   serve the .fringe ledger on 127.0.0.1
@@ -1600,7 +1841,7 @@ async function runCli(argv, opts = {}) {
       }
       const result = await runCheck(root, cfg, true, only);
       if (rest.includes("--claude-hook")) {
-        const out = toClaudeHook(result, root);
+        const out = toClaudeHook(result, root, receipts(root, result.findings));
         if (out) log(opts)(out);
         return 0;
       }
@@ -1646,6 +1887,16 @@ async function runCli(argv, opts = {}) {
       return 2;
     }
   }
+  if (cmd === "explain" && rest[0] === "pattern") {
+    const out = renderPatterns(rest[1]);
+    if (out === void 0) {
+      err(opts)(`fringe: unknown pattern '${rest[1]}' \u2014 run 'fringe explain pattern' to list them
+`);
+      return 2;
+    }
+    log(opts)(out);
+    return 0;
+  }
   if (cmd === "explain") {
     const out = renderExplain(rest[0]);
     if (out === void 0) {

package/dist/index.js

@@ -1,6 +1,6 @@
 import {
   runCli
-} from "./chunk-ZK2GPUZF.js";
+} from "./chunk-TNZKMKKQ.js";
 export {
   runCli
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fringetools/cli",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "license": "MIT",
   "type": "module",
   "bin": {

package/skill/fringe/SKILL.md

@@ -9,6 +9,7 @@ Command: use `fringe` if it is on the PATH, otherwise `npx -y @fringetools/cli`
 
 Ponytail trims your code. Fringe handles your edges. Work the ladder in order.
 
+0. **Building a form, modal, navigation or data view?** Run `fringe explain pattern <form|modal|navigation|data-view>` first: a short best-practice checklist, each item marked verified (Fringe checks it) or judged (you decide and say why).
 1. **Flow (judged).** Before building, ask what the user can skip. Cut steps, screens or options nobody needs. Write each decision with its evidence to `.fringe/manifest.json`: `{"flows":[{"action":"cut"|"kept","what":"...","evidence":"..."}]}`. No evidence, no cut.
 2. **Edges (verified, gates).** After every edit the hook runs `fringe check --claude-hook` and feeds errors back to you. Fix every listed finding. If there is no hook, run `fringe check --hook` yourself from the project root and do not finish while `block` is `true`.
    On a repo with many existing findings, run `fringe plan` and work it batch by batch (shared components first, since one fix clears many uses), re-running `fringe check` after each batch. `fringe explain <rule>` gives the recipe and what to avoid.