@fringetools/cli 0.1.4 → 0.2.1

package/README.md

@@ -21,7 +21,10 @@ Prefer a permanent command? `npm install -D @fringetools/cli`, then `npx fringe
 
 | Command | What it does |
 |---|---|
-| `fringe check [path]` | Scan a directory (default `.`) and print findings + health score. Exit `1` on any `error`. |
+| `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 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`. |
@@ -31,7 +34,7 @@ Prefer a permanent command? `npm install -D @fringetools/cli`, then `npx fringe
 | `fringe open [path] [--port <n>]` | Serve the ledger as a plain HTML page on `127.0.0.1:4173` (loopback only). Ctrl+C to stop. |
 | `fringe --help` · `--version` | Usage / version. |
 
-Notes: the first path is the check root (config + scan); extra paths are accepted and ignored so agent-invoked runs never crash. v0.1 takes directories, not single files. Unknown flags warn on stderr and are ignored.
+Notes: the first path is the check root (config + scan); extra paths are accepted and ignored so agent-invoked runs never crash. Unknown flags warn on stderr and are ignored.
 
 Default (human) output:
 
@@ -57,6 +60,23 @@ When a baseline or inline suppressions are in play, the last line adds `· N bas
 
 Each finding costs its weight (default error 10, review 3, signal 1). The total is scaled to a 10-file baseline (`× 10 / max(files, 10)`), so repo size doesn't flatten the score. Score = `100 − penalty` up to a penalty of 75; beyond that it decays smoothly (`25·75/penalty`) and never pins at 0. Repos under 10 files score exactly `100 − total`. Weights live in `fringe.config.json`.
 
+## Priority, clusters and fix plans
+
+Every finding in `--json` carries `priority`, `cluster` and `fixability`, and the result has a `clusters` list. A cluster is one rule in one file: usually one root cause and one fix.
+
+`priority = tier + WCAG level + critical path + blast radius`
+
+| Part | Value |
+|---|---|
+| Tier | error 1000 · review 400 · signal 100 (so any error outranks any review, whatever else is true) |
+| WCAG level | A +30 · AA +15 |
+| Critical path | +40 when the file matches `critical` in `fringe.config.json` (e.g. `"critical": ["src/checkout/**", "src/auth/**"]`) |
+| Blast radius | up to +20, growing with the number of files that import this one |
+
+A cluster is a **shared component** when 3 or more files import its file; fix those first, since one change clears every use. Repeats lift a cluster slightly (never across a tier). Blast radius matches importers by file base name, a deliberate shortcut.
+
+`fringe plan` turns this into the work order; `fringe explain FR-203` gives the recipe for one rule. The `--claude-hook` message includes each shown rule's recipe once, so the agent gets "how to fix it well", not just "what is wrong".
+
 ## Baseline
 
 Adopting Fringe on a repo that already has problems? Don't fix 300 findings first.
@@ -138,6 +158,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.
 
@@ -161,6 +187,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.
 
@@ -170,12 +197,13 @@ Optional, at the check root. Everything defaults sensibly; all keys are optional
 
 ```json
 {
-  "ignore": ["node_modules/**", "dist/**", "build/**", "out/**", "coverage/**", ".fringe/**", "*.min.*", "examples/**"],
+  "ignore": ["node_modules/**", "**/dist/**", "**/build/**", "**/out/**", "**/coverage/**", ".fringe/**", "*.min.*", "examples/**"],
   "disable": ["FR-214"],
   "weights": { "error": 10, "review": 3, "signal": 1 }
 }
 ```
 
+- `critical` — globs for the files that matter most (checkout, auth, sign-up). Their findings rank higher in `plan` and `--json`.
 - `ignore` — glob list matched against paths relative to the root. **Use the `dir/**` form to skip a directory** — a bare-dir glob like `"dist"` matches only the directory entry itself and does **not** prune the files inside it. (`node_modules` and dot-directories are always skipped.)
 - `disable` — rule IDs to turn off.
 - `weights` — per-finding penalties into the health score (see [Health score](#health-score)).

package/dist/bin.js

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

package/dist/{chunk-WXASOIWD.js → chunk-Z4UN7OMW.js}

@@ -1,10 +1,10 @@
 // src/index.ts
 import { randomUUID } from "crypto";
-import { readFileSync as readFileSync8 } from "fs";
-import { resolve } from "path";
+import { existsSync as existsSync3, readFileSync as readFileSync8, statSync } from "fs";
+import { dirname as dirname2, join as join8, resolve } from "path";
 
 // src/version.ts
-var VERSION = "0.1.4";
+var VERSION = "0.2.1";
 
 // src/check.ts
 import { readFileSync as readFileSync5 } from "fs";
@@ -13,7 +13,8 @@ import { readFileSync as readFileSync5 } from "fs";
 import { readFileSync } from "fs";
 import { join } from "path";
 var DEFAULT_CONFIG = {
-  ignore: ["node_modules/**", "dist/**", "build/**", "out/**", "coverage/**", ".fringe/**", "*.min.*"],
+  // Both forms: `dist/**` matches only at the root, `**/dist/**` matches nested build output (e.g. frontend/dist).
+  ignore: ["node_modules/**", "dist/**", "build/**", "out/**", "coverage/**", "**/dist/**", "**/build/**", "**/out/**", "**/coverage/**", ".fringe/**", "*.min.*"],
   disable: [],
   weights: { error: 10, review: 3, signal: 1 }
 };
@@ -28,6 +29,10 @@ function loadConfig(root) {
       weights: { ...DEFAULT_CONFIG.weights, ...user.weights ?? {} }
     };
     validateWeights(cfg.weights);
+    if (user.critical !== void 0) {
+      if (!Array.isArray(user.critical) || user.critical.some((g) => typeof g !== "string")) throw new Error("fringe.config.json: critical must be an array of glob strings");
+      cfg.critical = user.critical;
+    }
     if (user.tokenSource !== void 0) {
       cfg.tokenSource = validateTokenSource(user.tokenSource);
     }
@@ -452,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) {
@@ -914,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));
 }
@@ -1013,8 +1125,260 @@ function suppressedIds(lines, line) {
   return ids;
 }
 
+// src/prioritize.ts
+import { basename, extname, relative as relative3 } from "path";
+
+// src/guidance.ts
+var GUIDANCE = {
+  "FR-201": {
+    why: "A screen reader announces an image with no alt as its file name, or skips it.",
+    recipe: 'Informative image: describe its purpose, not its look (alt="Order #4521 receipt"). Decorative image: alt="".',
+    avoid: 'alt="image", alt="photo", or the file name.',
+    example: { before: '<img src="/hero.png" />', after: '<img src="/hero.png" alt="Team reviewing a dashboard" />' },
+    fixability: "judgment"
+  },
+  "FR-202": {
+    why: 'A button or link with no text is announced as just "button" or "link".',
+    recipe: 'Put visible text inside it. For an icon-only control, add aria-label naming the action and aria-hidden="true" on the icon.',
+    avoid: 'title alone (not reliably announced) or an aria-label that repeats the icon name ("cross").',
+    example: { before: "<button><CloseIcon /></button>", after: '<button aria-label="Close dialog"><CloseIcon aria-hidden="true" /></button>' },
+    fixability: "mechanical"
+  },
+  "FR-203": {
+    why: "A form field with no label is announced without a name, and the placeholder vanishes as soon as the user types.",
+    recipe: "Add a visible <label htmlFor> bound to the input id. Use aria-label only where a visible label is genuinely wrong for the design (e.g. a search box beside a magnifier button).",
+    avoid: "Placeholder as the only label; aria-label when a visible label would fit.",
+    example: { before: '<input id="email" placeholder="Email" />', after: '<label htmlFor="email">Email</label>\n<input id="email" />' },
+    fixability: "mechanical"
+  },
+  "FR-204": {
+    why: "Screen reader users navigate by headings; skipped levels or several h1s break the outline.",
+    recipe: "Use one h1 per page, then h2, h3 in order. Choose the level by structure and style it with CSS.",
+    avoid: "Picking h3 because it looks smaller.",
+    fixability: "mechanical"
+  },
+  "FR-205": {
+    why: "Keyboard users cannot see where focus is when the outline is removed.",
+    recipe: "Keep a visible focus style. Replace outline-none with focus-visible:outline-2 focus-visible:outline-offset-2 (or a :focus-visible rule with a visible outline).",
+    avoid: "outline: none with no replacement; styling :focus only for mouse users.",
+    fixability: "mechanical"
+  },
+  "FR-206": {
+    why: "A clickable div is not reachable by keyboard and has no role for assistive technology.",
+    recipe: 'Use a <button> (or <a href> for navigation). Only if that is impossible, add role="button", tabIndex={0} and Enter/Space key handlers.',
+    avoid: 'role="button" without keyboard handlers.',
+    example: { before: "<div onClick={open}>Open</div>", after: '<button type="button" onClick={open}>Open</button>' },
+    fixability: "mechanical"
+  },
+  "FR-207": {
+    why: "A positive tabIndex pulls the element out of the natural order and makes focus jump unpredictably.",
+    recipe: "Use tabIndex={0} (join the natural order) or -1 (focusable by script only), and fix the order by moving the element in the DOM.",
+    avoid: "tabIndex={1}, {2}... to force an order.",
+    fixability: "mechanical"
+  },
+  "FR-208": {
+    why: "Data that loads, comes back empty or fails leaves the user staring at nothing.",
+    recipe: "Render three states next to the data: loading (skeleton or spinner with a text label), empty (what to do next), error (what failed and a retry).",
+    avoid: "A spinner with no failure path.",
+    fixability: "judgment"
+  },
+  "FR-209": {
+    why: "A misspelled aria-* attribute is ignored, so the intended name or state never reaches the user.",
+    recipe: "Correct the attribute name against the ARIA spec (aria-labelledby, aria-describedby, aria-expanded...).",
+    example: { before: '<input aria-labeledby="h" />', after: '<input aria-labelledby="h" />' },
+    fixability: "mechanical"
+  },
+  "FR-210": {
+    why: "A fake countdown pressures users into rushed decisions.",
+    recipe: "State the real deadline as a date, or remove the urgency wording.",
+    fixability: "judgment"
+  },
+  "FR-211": {
+    why: "A pre-checked consent box opts people in without a decision.",
+    recipe: "Leave consent boxes unchecked and make the choice explicit.",
+    fixability: "mechanical"
+  },
+  "FR-212": {
+    why: "Guilt-trip wording on the decline option manipulates the choice.",
+    recipe: 'Make both options neutral ("No thanks").',
+    fixability: "judgment"
+  },
+  "FR-213": {
+    why: "Infinite scroll with no way to stop traps keyboard users and buries the footer.",
+    recipe: 'Offer a "Load more" button or pagination, and keep the footer reachable.',
+    fixability: "judgment"
+  },
+  "FR-214": {
+    why: '"Free", then a price later, erodes trust.',
+    recipe: "Show the full price up front, including recurring cost.",
+    fixability: "judgment"
+  },
+  "FR-215": {
+    why: '"Something went wrong" tells the user nothing about what to do next.',
+    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.",
+    fixability: "mechanical"
+  },
+  "FR-302": {
+    why: "Off-scale font sizes break the type rhythm.",
+    recipe: "Use the type scale (text-sm, text-base, ...) or add the size to the theme.",
+    fixability: "mechanical"
+  },
+  "FR-303": {
+    why: "Off-scale spacing makes layouts inconsistent.",
+    recipe: "Use the spacing scale (p-4, gap-2, ...) or extend the theme.",
+    fixability: "mechanical"
+  },
+  "FR-304": {
+    why: "Low contrast text is hard to read for many people, and unreadable in sunlight.",
+    recipe: "Raise the contrast to at least 4.5:1 for body text (3:1 for large text) by darkening the text or lightening the background.",
+    fixability: "judgment"
+  },
+  "FR-305": {
+    why: "Tiny hit areas are hard to tap, especially for people with motor impairments.",
+    recipe: "Give interactive elements at least 24x24px (44x44px on touch) with padding, not just font size.",
+    fixability: "mechanical"
+  },
+  "FR-361": {
+    why: "Italic serif display headlines are a recognisable AI-generated look.",
+    recipe: "Choose type from the project design system for headlines.",
+    fixability: "judgment"
+  },
+  "FR-362": {
+    why: "The uppercase eyebrow chip above a headline is a recognisable AI-generated look.",
+    recipe: "Drop the chip or fold the content into the heading or subheading.",
+    fixability: "judgment"
+  },
+  "FR-363": {
+    why: "Cards nested in cards add visual noise and hide hierarchy.",
+    recipe: "Flatten: use spacing and one border level.",
+    fixability: "judgment"
+  },
+  "FR-364": {
+    why: "A stack of icon tiles is a recognisable AI-generated layout.",
+    recipe: "Replace with content that carries information, or vary the structure.",
+    fixability: "judgment"
+  },
+  "FR-365": {
+    why: "A thin border with a wide shadow signals elevation inconsistently.",
+    recipe: "Pick one: a border for flat surfaces or a soft shadow for raised ones.",
+    fixability: "judgment"
+  },
+  "FR-366": {
+    why: "Many status chips make a page read as noise.",
+    recipe: "Keep chips that carry state the user acts on; merge or drop the rest.",
+    fixability: "judgment"
+  },
+  "FR-367": {
+    why: '"01 Discover" style labels are a recognisable AI-generated look.',
+    recipe: "Use plain section headings.",
+    fixability: "judgment"
+  },
+  "FR-368": {
+    why: "The violet/indigo gradient is a recognisable AI-generated look.",
+    recipe: "Use the project brand colors.",
+    fixability: "judgment"
+  },
+  "FR-369": {
+    why: "Emoji in headings read as decoration and can be announced noisily.",
+    recipe: "Remove the emoji, or put a real icon beside the heading with aria-hidden.",
+    fixability: "judgment"
+  }
+};
+function renderExplain(id) {
+  if (!id) return ALL_RULES.map((r) => `${r.id}  ${r.severity.padEnd(6)} ${GUIDANCE[r.id].why}`).join("\n");
+  const rule = ALL_RULES.find((r) => r.id === id.toUpperCase());
+  if (!rule) return void 0;
+  const g = GUIDANCE[rule.id];
+  const out = [`${rule.id} \xB7 ${rule.severity} \xB7 ${g.fixability} fix`, `Why:     ${g.why}`, `Fix:     ${g.recipe}`];
+  if (g.avoid) out.push(`Avoid:   ${g.avoid}`);
+  if (g.example) out.push("Before:  " + g.example.before.replace(/\n/g, "\n         "), "After:   " + g.example.after.replace(/\n/g, "\n         "));
+  return out.join("\n");
+}
+
+// src/prioritize.ts
+var TIER = { error: 1e3, review: 400, signal: 100 };
+var WCAG_A = /* @__PURE__ */ new Set(["1.1.1", "1.3.1", "2.1.1", "2.4.3", "3.3.2", "4.1.2"]);
+var WCAG_AA = /* @__PURE__ */ new Set(["1.4.3", "2.4.7", "2.5.8"]);
+var CRITICAL_BONUS = 40;
+var SHARED_FROM = 3;
+var IMPORT = /(?:from\s+|import\s*\(\s*|require\(\s*)['"]([^'"]+)['"]/g;
+function importerCounts(sources) {
+  const counts = /* @__PURE__ */ new Map();
+  for (const src of sources.values()) {
+    const seen = /* @__PURE__ */ new Set();
+    for (const m of src.matchAll(IMPORT)) seen.add(basename(m[1], extname(m[1])));
+    for (const b of seen) counts.set(b, (counts.get(b) ?? 0) + 1);
+  }
+  return counts;
+}
+function prioritize(findings, sources, root, critical) {
+  const crit = critical.map(globToRegex);
+  const importers = importerCounts(sources);
+  const clusters = /* @__PURE__ */ new Map();
+  const out = findings.map((f) => {
+    const rel = relative3(root, f.loc.file);
+    const blast = Math.min(20, 4 * Math.log2(1 + (importers.get(basename(rel, extname(rel))) ?? 0)));
+    const level = f.wcag && WCAG_A.has(f.wcag) ? 30 : f.wcag && WCAG_AA.has(f.wcag) ? 15 : 0;
+    const priority = Math.round(TIER[f.severity] + level + (crit.some((r) => r.test(rel)) ? CRITICAL_BONUS : 0) + blast);
+    const id = `${f.rule}@${rel}`;
+    const by = importers.get(basename(rel, extname(rel))) ?? 0;
+    const c = clusters.get(id) ?? { id, rule: f.rule, file: rel, count: 0, priority: 0, fixability: GUIDANCE[f.rule]?.fixability ?? "judgment", rootCause: by >= SHARED_FROM ? "shared component" : "local", importedBy: by, critical: crit.some((r) => r.test(rel)) };
+    c.count++;
+    c.priority = Math.max(c.priority, priority);
+    clusters.set(id, c);
+    return { ...f, priority, cluster: id, fixability: c.fixability };
+  });
+  for (const c of clusters.values()) c.priority += Math.round(Math.min(15, 3 * Math.log2(c.count)));
+  return { findings: out, clusters: [...clusters.values()].sort((a, b) => b.priority - a.priority || a.id.localeCompare(b.id)) };
+}
+
 // src/check.ts
-async function runCheck(root, cfg = loadConfig(root), useBaseline = true) {
+async function runCheck(root, cfg = loadConfig(root), useBaseline = true, only) {
   const stack = detectStack(root);
   const files = walk(root, cfg);
   const rules = activeRules(cfg);
@@ -1050,6 +1414,7 @@ async function runCheck(root, cfg = loadConfig(root), useBaseline = true) {
   const tokenColors = gatherTokenColors(root, cfg, cssSources);
   for (const ctx of contexts) ctx.tokenColors = tokenColors;
   for (const ctx of contexts) {
+    if (only && !only.has(ctx.file)) continue;
     for (const rule of rules) findings.push(...rule.check(ctx));
   }
   const lines = new Map(contexts.map((c) => [c.file, c.source.split("\n")]));
@@ -1058,7 +1423,8 @@ async function runCheck(root, cfg = loadConfig(root), useBaseline = true) {
   const { fresh, known } = useBaseline ? applyBaseline(root, live) : { fresh: live, known: 0 };
   const counts = { error: 0, review: 0, signal: 0 };
   for (const f of fresh) counts[f.severity]++;
-  return { stack, files: files.length, skipped, findings: fresh, counts, score: score(counts, cfg.weights, files.length), ...known ? { baselined: known } : {}, ...suppressed ? { suppressed } : {} };
+  const ranked = prioritize(fresh, new Map(contexts.map((c) => [c.file, c.source])), root, cfg.critical ?? []);
+  return { stack, files: only ? only.size : files.length, skipped, findings: ranked.findings, clusters: ranked.clusters, counts, score: score(counts, cfg.weights, only ? only.size : files.length), ...known ? { baselined: known } : {}, ...suppressed ? { suppressed } : {} };
 }
 
 // src/report/json.ts
@@ -1067,7 +1433,7 @@ function toJson(r) {
 }
 
 // src/report/hook.ts
-import { relative as relative3 } from "path";
+import { relative as relative4 } from "path";
 var RANK = { error: 0, review: 1, signal: 2 };
 function topFinding(r) {
   return [...r.findings].sort((a, b) => {
@@ -1091,13 +1457,20 @@ function toHook(r) {
 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} ${relative3(root, f.loc.file)}:${f.loc.line} \u2014 ${f.message} (${f.hint})`);
+  const shown = errs.slice(0, 8).map((f) => `- ${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];
+    return g ? `- ${id}: ${g.recipe}${g.avoid ? ` Avoid: ${g.avoid}` : ""}` : "";
+  }).filter(Boolean);
   const more = errs.length > shown.length ? `
 \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:
 ${shown.join("\n")}${more}
+How to fix them well:
+${recipes.join("\n")}
 Use a fringe-ignore comment only for a genuine false positive, and say so.`
   });
 }
@@ -1226,6 +1599,123 @@ function initProject(root) {
   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"],
+  P1: ["Then the other errors", "blocking problems; mechanical fixes first"],
+  P2: ["Review", "heuristics that need your judgment"],
+  P3: ["Polish", "advice only; never blocks"]
+};
+function buildPlan(r, limit = 15) {
+  const lines = /* @__PURE__ */ new Map();
+  for (const f of r.findings) if (f.cluster) lines.set(f.cluster, [...lines.get(f.cluster) ?? [], f.loc.line]);
+  const sev = new Map(r.findings.map((f) => [f.cluster, f.severity]));
+  const items = (r.clusters ?? []).map((c) => ({ ...c, lines: lines.get(c.id) ?? [], recipe: GUIDANCE[c.rule]?.recipe, avoid: GUIDANCE[c.rule]?.avoid }));
+  const mechFirst = (a, b) => (a.fixability === b.fixability ? 0 : a.fixability === "mechanical" ? -1 : 1) || b.priority - a.priority;
+  const pick = (id) => items.filter((c) => {
+    const s = sev.get(c.id);
+    if (id === "P0") return s === "error" && (c.rootCause === "shared component" || c.critical);
+    if (id === "P1") return s === "error" && !(c.rootCause === "shared component" || c.critical);
+    return s === (id === "P2" ? "review" : "signal");
+  }).sort(id === "P1" ? mechFirst : (a, b) => b.priority - a.priority);
+  return ["P0", "P1", "P2", "P3"].map((id) => {
+    const all = pick(id);
+    return { id, title: TITLES[id][0], why: TITLES[id][1], items: all.slice(0, limit), more: Math.max(0, all.length - limit) };
+  }).filter((b) => b.items.length > 0);
+}
+function toPlanJson(r, limit) {
+  return JSON.stringify({ schema: "fringe/plan.v1", score: r.score, counts: r.counts, batches: buildPlan(r, limit) }, null, 2);
+}
+function toPlanMarkdown(r, target, limit) {
+  const batches = buildPlan(r, limit);
+  const head = `# Fringe fix plan
+
+health ${r.score}/100 \xB7 ${r.counts.error} errors \xB7 ${r.counts.review} review \xB7 ${r.counts.signal} signals`;
+  if (batches.length === 0) return `${head}
+
+Nothing to fix.`;
+  const out = [head];
+  for (const b of batches) {
+    out.push(`
+## ${b.id} \xB7 ${b.title}
+_${b.why}_`);
+    const shown = /* @__PURE__ */ new Set();
+    for (const c of b.items) {
+      const tags = [c.rootCause === "shared component" ? `shared component, imported by ${c.importedBy} files` : "", c.critical ? "critical path" : "", `${c.fixability} fix`].filter(Boolean);
+      out.push(`
+### ${c.rule} \xB7 \xD7${c.count} \xB7 ${c.file} (${tags.join("; ")})`);
+      out.push(`Lines: ${c.lines.slice(0, 8).join(", ")}${c.lines.length > 8 ? ", \u2026" : ""}`);
+      if (c.recipe && !shown.has(c.rule)) {
+        shown.add(c.rule);
+        out.push(`Fix: ${c.recipe}${c.avoid ? `
+Avoid: ${c.avoid}` : ""}`);
+      } else if (c.recipe) out.push(`Fix: as for ${c.rule} above (\`fringe explain ${c.rule}\`).`);
+    }
+    if (b.more) out.push(`
+\u2026and ${b.more} more in this batch (raise --limit).`);
+  }
+  out.push(`
+After each batch, verify: \`fringe check ${target}\``);
+  return out.join("\n");
+}
+
 // src/index.ts
 var log = (o) => o.log ?? ((s) => console.log(s));
 var err = (o) => o.err ?? ((s) => process.stderr.write(s));
@@ -1255,10 +1745,25 @@ function readManifest(path2, warn) {
     return void 0;
   }
 }
+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"))) {
+      dir = d;
+      break;
+    }
+    if (dirname2(d) === d) break;
+  }
+  return { root: dir, only: /* @__PURE__ */ new Set([arg]) };
+}
 var weakEvidence = (e) => typeof e !== "string" || e.trim().length < 12 || /^(n\/?a|none|tbd|obvious|unnecessary|clutter|unused)\.?$/i.test(e.trim());
 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
 fringe --help | --version`;
@@ -1290,7 +1795,7 @@ async function runCli(argv, opts = {}) {
     try {
       const paths = parseArgs(rest, err(opts));
       const cwd = opts.cwd ?? process.cwd();
-      const root = paths.length > 0 ? resolve(cwd, paths[0]) : cwd;
+      const { root, only } = resolveTarget(paths.length > 0 ? resolve(cwd, paths[0]) : cwd);
       const cfg = loadConfig(root);
       if (rest.includes("--update-baseline")) {
         const all = await runCheck(root, cfg, false);
@@ -1298,7 +1803,7 @@ async function runCli(argv, opts = {}) {
         log(opts)(`fringe: baseline written \u2014 ${all.findings.length} known findings in fringe.baseline.json (commit it); only new ones gate from now on`);
         return 0;
       }
-      const result = await runCheck(root, cfg);
+      const result = await runCheck(root, cfg, true, only);
       if (rest.includes("--claude-hook")) {
         const out = toClaudeHook(result, root);
         if (out) log(opts)(out);
@@ -1330,6 +1835,42 @@ async function runCli(argv, opts = {}) {
       return 2;
     }
   }
+  if (cmd === "plan") {
+    try {
+      const li = rest.indexOf("--limit");
+      const limit = li !== -1 ? Number(rest[li + 1]) || void 0 : void 0;
+      const paths = parseArgs(rest.filter((a, i) => a !== "--limit" && rest[i - 1] !== "--limit" && a !== "--json"), err(opts));
+      const arg = resolve(opts.cwd ?? process.cwd(), paths[0] ?? ".");
+      const { root, only } = resolveTarget(arg);
+      const result = await runCheck(root, loadConfig(root), true, only);
+      log(opts)(rest.includes("--json") ? toPlanJson(result, limit) : toPlanMarkdown(result, paths[0] ?? ".", limit));
+      return 0;
+    } catch (e) {
+      err(opts)(`fringe: internal error: ${e.message}
+`);
+      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) {
+      err(opts)(`fringe: unknown rule '${rest[0]}' \u2014 run 'fringe explain' to list them
+`);
+      return 2;
+    }
+    log(opts)(out);
+    return 0;
+  }
   if (cmd === "init") {
     try {
       for (const line of initProject(resolve(opts.cwd ?? process.cwd(), rest[0] ?? "."))) log(opts)(`fringe: ${line}`);

package/dist/index.js

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

package/package.json

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

package/skill/fringe/SKILL.md

@@ -9,8 +9,10 @@ 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.
 3. **Polish (verified, never gates).** Run `fringe check` once before finishing. Fix `review` items you agree with. Fix `signal` items that are cheap. Say which you left and why.
 
 When done: `fringe check --record --manifest .fringe/manifest.json`. Report the health score as measured; never estimate it yourself.

package/skill/fringe-audit/SKILL.md

@@ -7,7 +7,7 @@ description: Use when the user wants a whole-repo UX/accessibility audit, a plan
 
 Command: use `fringe` if it is on the PATH, otherwise `npx -y @fringetools/cli` in its place (e.g. `npx -y @fringetools/cli check --json .`).
 
-1. Run `fringe check --json .` and note the totals. Do not print every finding.
+1. Run `fringe plan --json --limit 5` (or `fringe plan` for Markdown). It already orders the work: P0 errors in shared components or critical paths, P1 other errors with mechanical fixes first, P2 review, P3 polish, each cluster with its recipe. Use that order; do not re-derive it. Add `"critical": ["src/checkout/**"]` to `fringe.config.json` if the user names the pages that matter most. Do not print every finding.
 2. Summarize as a plan:
    - Totals by severity and the health score, plus files scanned and skipped.
    - **Top rules** by count, and **top files** by error count (the 5 worst of each).

package/skill/fringe-help/SKILL.md

@@ -24,6 +24,8 @@ Fringe checks agent-written frontends for accessibility, state, dark-pattern and
 | `check [dir]` | Scan and print findings and the health score; exit 1 on any error |
 | `check --json` / `--hook` / `--claude-hook` | Machine output; CI gate; agent feedback form |
 | `check --update-baseline` | Accept today's findings; only new ones gate |
+| `plan [dir\|file]` | Ordered fix batches (shared components first) with recipes |
+| `explain [FR-203]` | Why a rule matters and how to fix it well |
 | `check --record [--manifest f]` | Append the run to `.fringe/ledger.jsonl` |
 | `init` | Add the hook and install the skills |
 | `open` | View the ledger at 127.0.0.1:4173 |

package/skill/fringe-review/SKILL.md

@@ -7,7 +7,7 @@ description: Use when the user asks to review, check or critique a UI, page or c
 
 Command: use `fringe` if it is on the PATH, otherwise `npx -y @fringetools/cli` in its place (e.g. `npx -y @fringetools/cli check --json .`).
 
-1. Run `fringe check --json .` from the project root. Fringe takes directories, not single files, so if the user named one file or page, run on the folder and keep only the findings whose `loc.file` matches it.
+1. Run `fringe check --json <file or folder>` from the project root: the file or page the user named, else `.`. Each finding already carries `priority` and `fixability`; report highest priority first. For the fix text use `fringe explain <rule>` (why, recipe, what to avoid) rather than improvising.
 2. Report in plain English, no jargon left unexplained:
    - **Must fix** — `error` findings. Group by rule. For each: where (`file:line`), what is wrong in one sentence, the exact fix, and who is hurt (for example "a screen reader says only 'button'"). Cite the `wcag` criterion when present.
    - **Worth a look** — `review` findings. These are heuristics: say they need your judgment, and give your call on each.