@fringetools/cli 0.2.0 → 0.2.1

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`. |
@@ -157,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.
 
@@ -180,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.
 

package/dist/bin.js

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

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

@@ -4,7 +4,7 @@ import { existsSync as existsSync3, readFileSync as readFileSync8, statSync } fr
 import { dirname as dirname2, join as join8, resolve } from "path";
 
 // src/version.ts
-var VERSION = "0.2.0";
+var VERSION = "0.2.1";
 
 // src/check.ts
 import { readFileSync as readFileSync5 } from "fs";
@@ -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));
 }
@@ -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.",
@@ -1452,6 +1599,63 @@ 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"],
@@ -1558,6 +1762,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
@@ -1646,6 +1851,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-Z4UN7OMW.js";
 export {
   runCli
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fringetools/cli",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "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.