jig-ui 0.16.0 → 0.16.1

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 0.16.1
+
+### Fixed
+
+- **The corpus's own headings follow I-118.** Twelve `R-` titles ("Frame 1:
+  Minimise usability risk", the seven tiebreakers) and `L-01`'s six steps used
+  an em dash. Headings are interface text wherever they show, in `explain`, in
+  `check` output and on a rendered page, so they now use a colon.
+- **A quotation keeps its own punctuation.** I-118 now says text marked as a
+  quotation with `<blockquote>` or `<q>` is the source's words, and changing
+  it would misquote it; the page's own copy around it is still held to the
+  rule. The render probe leaves quoted text out of its dash scan. Without
+  this, a page quoting a rule verbatim could never pass its review.
+- **A spec's `indexable:` is `true` or `false`.** A sentence on that line was
+  read as nothing, the mode's default was used, and a correct page was
+  reported as contradicting J-123. Anything else is now a spec-shape problem,
+  and an error in `verdicts` that names the field.
+
 ## 0.16.0
 
 With more than one mode, every barrel names its mode, and none sits in the

package/dist/index.js

@@ -5314,8 +5314,8 @@ Could not write to ${wireTarget}: ${err.message}`);
 }
 
 // src/commands/verdicts.ts
-import { existsSync as existsSync20, readFileSync as readFileSync27 } from "fs";
-import { join as join34, resolve as resolve4 } from "path";
+import { existsSync as existsSync21, readFileSync as readFileSync28 } from "fs";
+import { join as join35, resolve as resolve4 } from "path";
 
 // src/rules/citations.ts
 import { join as join29 } from "path";
@@ -5348,6 +5348,14 @@ var PROBE_SCRIPT = `(async () => {
   const defaultFont = getComputedStyle(probe).fontFamily;
   probe.remove();
   const text = document.body.innerText || '';
+  // I-118: a verbatim quotation keeps its own punctuation. Text marked as a
+  // quotation is the source's words, so it is taken out before the dash scan;
+  // the page's own copy around it still counts.
+  let ownText = text;
+  for (const q of document.querySelectorAll('blockquote, q')) {
+    const quoted = (q.innerText || '').trim();
+    if (quoted) ownText = ownText.split(quoted).join('\\n');
+  }
   const junk = [...new Set(text.match(/\\$\\{|\\{\\{|\\bundefined\\b|\\bNaN\\b|\\[object Object\\]/g) || [])];
   const unresolved = new Set();
   for (const sheet of document.styleSheets) {
@@ -5458,7 +5466,7 @@ var PROBE_SCRIPT = `(async () => {
     defaultFont: getComputedStyle(document.body).fontFamily === defaultFont,
     unresolvedTokens: [...unresolved],
     junkText: junk,
-    emDashes: [...new Set((text.match(/[^.!?\\n]{0,28}\u2014[^.!?\\n]{0,28}/g) || []).map((t) => t.trim()))].slice(0, 5),
+    emDashes: [...new Set((ownText.match(/[^.!?\\n]{0,28}\u2014[^.!?\\n]{0,28}/g) || []).map((t) => t.trim()))].slice(0, 5),
     brokenImages: [...document.images].filter((i) => i.complete && i.naturalWidth === 0).length,
     navLinksVisible: navAtRest,
     head: {
@@ -5877,35 +5885,120 @@ function decisionNames(projectRoot) {
   return names;
 }
 
+// src/check/spec-shape.ts
+import { existsSync as existsSync20, readFileSync as readFileSync27, readdirSync as readdirSync14, statSync as statSync2 } from "fs";
+import { join as join34 } from "path";
+function newestSpec(projectRoot) {
+  const dir = join34(projectRoot, ".jig", "specs");
+  if (!existsSync20(dir)) return void 0;
+  const files = readdirSync14(dir).filter((f) => f.endsWith(".md"));
+  if (files.length === 0) return void 0;
+  const newest = files.map((f) => ({ f, at: statSync2(join34(dir, f)).mtimeMs })).sort((a, b) => b.at - a.at)[0].f;
+  return { path: `.jig/specs/${newest}`, slug: newest.replace(/\.spec\.md$|\.md$/, ""), body: readFileSync27(join34(dir, newest), "utf8") };
+}
+function specProblems(spec) {
+  const parts = spec.body.split(/^---\s*$/m);
+  const front = parts.length >= 3 ? parts[1] : "";
+  if (!front.trim()) {
+    return [`${spec.path} has no frontmatter. A spec is the frontmatter \u2014 feature, surface, mode, sizes (phone, tablet, desktop), states, decisions, later, mockup, confirmed \u2014 with the reasoning below it. Rewrite it in that shape.`];
+  }
+  const problems = [];
+  const has = (field) => new RegExp(`^\\s*${field}\\s*:`, "im").test(front);
+  if (specIndexableField(front) === "unreadable") {
+    problems.push(`${spec.path}: \`indexable:\` is neither true nor false. Write \`indexable: true\` or \`indexable: false\`; a per-page override and its reason go in the body, where they can be read without being parsed.`);
+  }
+  for (const field of ["feature", "surface", "mode", "sizes", "confirmed", "mockup"]) {
+    if (!has(field)) problems.push(`${spec.path} frontmatter has no \`${field}:\`.`);
+  }
+  const sizes = front.split(/^sizes\s*:/im)[1] ?? "";
+  for (const size of ["phone", "tablet", "desktop", "wide"]) {
+    const line = new RegExp(`^\\s+${size}\\s*:(.*)$`, "im").exec(sizes);
+    if (!line) {
+      problems.push(`${spec.path} has no \`${size}:\` composition under \`sizes:\`. Every size is written in full, phone first; \`same-as:\` needs a \`why:\`.`);
+      continue;
+    }
+    if (line[1].trim()) {
+      problems.push(`${spec.path}: \`${size}:\` is a one-line description. A size is a composition \u2014 \`regions:\` in order, \`hierarchy:\`, \`nav:\` \u2014 each on its own line, or \`same-as:\` with a \`why:\`.`);
+      continue;
+    }
+    const block = sizeBlock(sizes, size);
+    if (/^\s*same-as\s*:/im.test(block)) {
+      if (!/^\s*why\s*:/im.test(block)) problems.push(`${spec.path}: \`${size}\` claims \`same-as:\` with no \`why:\`. The claim is checked on a render, so it says why it holds.`);
+      continue;
+    }
+    for (const field of ["regions", "nav"]) {
+      if (!new RegExp(`^\\s*${field}\\s*:`, "im").test(block)) {
+        problems.push(`${spec.path}: \`${size}\` has no \`${field}:\`. Every size names its regions in order and what its navigation is at that width (\`nav: none\` when the screen has none).`);
+      }
+    }
+  }
+  return problems;
+}
+function sizeBlock(sizes, size) {
+  const start = new RegExp(`^\\s+${size}\\s*:.*$`, "im").exec(sizes);
+  if (!start) return "";
+  const rest = sizes.slice(start.index + start[0].length);
+  const indent = /^\s*/.exec(start[0])[0].length;
+  const lines = [];
+  for (const line of rest.split("\n")) {
+    if (line.trim() && /^\s*/.exec(line)[0].length <= indent) break;
+    lines.push(line);
+  }
+  return lines.join("\n");
+}
+var MENU_RE = /(?<!\b(?:no|not|without|never)\s)(?<!\bno\s\w{1,12}\s)\b(menu|hamburger|drawer|burger)\b/i;
+var NONE_RE = /^\s*(none|no navigation|n\/a|-)\b/i;
+function navProblems(spec) {
+  const front = spec.body.split(/^---\s*$/m)[1] ?? "";
+  const sizes = front.split(/^sizes\s*:/im)[1] ?? "";
+  const problems = [];
+  for (const size of ["tablet", "landscape", "desktop", "wide"]) {
+    const block = sizeBlock(sizes, size);
+    const nav = /^\s*nav\s*:\s*(.+)$/im.exec(block)?.[1]?.trim();
+    if (!nav || NONE_RE.test(nav)) continue;
+    if (MENU_RE.test(nav) && !/\bopen\b|\bexpanded\b/i.test(nav)) {
+      problems.push(`${spec.path}: \`${size}\` has \`nav: ${nav}\`. Run P-14's table at that width \u2014 where every destination fits, the links show and there is no menu button. A decision about where the button sits is about position, not whether it exists.`);
+    }
+  }
+  return problems;
+}
+function specIndexableField(front) {
+  const line = /^\s*indexable\s*:(.*)$/im.exec(front);
+  if (!line) return "absent";
+  const value = line[1].trim().replace(/^["']|["']$/g, "").toLowerCase();
+  if (value === "true" || value === "yes") return true;
+  if (value === "false" || value === "no") return false;
+  return "unreadable";
+}
+
 // src/commands/verdicts.ts
 var VERDICTS = ["ok", "finding", "n/a"];
 var ABSENCE = /\b(rule (not found|does not exist)|context unavailable|cannot (find|read|access) (the )?rule|not in (the )?(accessible )?corpus)\b/i;
 function readJson(path, errors) {
-  if (!existsSync20(path)) return null;
+  if (!existsSync21(path)) return null;
   try {
-    return JSON.parse(readFileSync27(path, "utf8"));
+    return JSON.parse(readFileSync28(path, "utf8"));
   } catch (e) {
     errors.push(`${path}: not valid JSON (${e.message})`);
     return {};
   }
 }
 function specIndexable(projectRoot, surface) {
-  const path = join34(projectRoot, ".jig", "specs", `${surface}.spec.md`);
+  const path = join35(projectRoot, ".jig", "specs", `${surface}.spec.md`);
   let front = "";
   try {
-    front = readFileSync27(path, "utf8").split(/^---\s*$/m)[1] ?? "";
+    front = readFileSync28(path, "utf8").split(/^---\s*$/m)[1] ?? "";
   } catch {
   }
-  const declared = /^\s*indexable\s*:\s*(\w+)/im.exec(front)?.[1]?.toLowerCase();
-  if (declared === "true" || declared === "yes") return true;
-  if (declared === "false" || declared === "no") return false;
+  const declared = specIndexableField(front);
+  if (declared === true || declared === false) return declared;
   const mode = /^\s*mode\s*:\s*(\w+)/im.exec(front)?.[1]?.toLowerCase();
   return mode !== "product" && mode !== "operator";
 }
 function specNeedsNav(projectRoot, surface) {
-  const path = join34(projectRoot, ".jig", "specs", `${surface}.spec.md`);
-  if (!existsSync20(path)) return false;
-  const front = readFileSync27(path, "utf8").split(/^---\s*$/m)[1] ?? "";
+  const path = join35(projectRoot, ".jig", "specs", `${surface}.spec.md`);
+  if (!existsSync21(path)) return false;
+  const front = readFileSync28(path, "utf8").split(/^---\s*$/m)[1] ?? "";
   const navField = [...front.matchAll(/^\s*nav:\s*(.+)$/gim)].some((m) => !/^\s*(none|n\/a|-)\b/i.test(m[1]));
   const navRegion = /^\s*-\s*(nav|navigation)\s*:/im.test(front);
   return navField || navRegion;
@@ -5956,7 +6049,7 @@ function checkArm(name, file, required, otherPass, extraAllowed, extraRequired,
 function checkDecisions(projectRoot, dir, errors) {
   const required = decisionNames(projectRoot);
   if (required.length === 0) return { state: "ran", judged: 0, total: 0, findings: 0 };
-  const file = readJson(join34(dir, "decisions.json"), errors);
+  const file = readJson(join35(dir, "decisions.json"), errors);
   if (!file) {
     errors.push(
       `decisions.json is missing. Every decision in DECISIONS.md is judged against the built page, one verdict each: ${required.slice(0, 4).join(", ")}${required.length > 4 ? `, and ${required.length - 4} more` : ""}. A page can satisfy every rule and still break what this project decided.`
@@ -6001,7 +6094,7 @@ function checkDecisions(projectRoot, dir, errors) {
 function verifyVerdicts(opts) {
   const root = opts.packageRoot ?? assetRoot();
   const errors = [];
-  const index = JSON.parse(readFileSync27(join34(root, "rules.index.json"), "utf8"));
+  const index = JSON.parse(readFileSync28(join35(root, "rules.index.json"), "utf8"));
   const judgment = index.filter((r) => r.bucket === "judgment");
   const screenIds = judgment.filter((r) => r.pass === "screen").map((r) => r.id);
   const codeIds = judgment.filter((r) => r.pass === "code").map((r) => r.id);
@@ -6010,16 +6103,16 @@ function verifyVerdicts(opts) {
     ...judgment.map((r) => [r.id, r.pass ?? ""])
   ]);
   const specIds = new Set(citableIds(root).filter((id) => /^[PMLRT]-\d+$/.test(id)));
-  const dir = join34(opts.projectRoot, ".jig", "critique", opts.surface);
-  const screenFile = readJson(join34(dir, "screen.json"), errors);
-  const codeFile = readJson(join34(dir, "code.json"), errors);
+  const dir = join35(opts.projectRoot, ".jig", "critique", opts.surface);
+  const screenFile = readJson(join35(dir, "screen.json"), errors);
+  const codeFile = readJson(join35(dir, "code.json"), errors);
   const screenExtraRequired = specNeedsNav(opts.projectRoot, opts.surface) ? ["P-14"] : [];
   const screen = checkArm("screen", screenFile, screenIds, passOf, specIds, screenExtraRequired, errors);
   const code = checkArm("code", codeFile, codeIds, passOf, specIds, [], errors);
   let rendered = false;
   if (screenFile && screenFile.rendered === true) {
     const artefacts = Array.isArray(screenFile.artefacts) ? screenFile.artefacts.filter((a) => typeof a === "string") : [];
-    const absent = artefacts.filter((a) => !existsSync20(resolve4(opts.projectRoot, a)));
+    const absent = artefacts.filter((a) => !existsSync21(resolve4(opts.projectRoot, a)));
     if (artefacts.length === 0) errors.push("screen.json says rendered: true but lists no artefacts. A render leaves a screenshot.");
     else if (absent.length) errors.push(`screen.json says rendered: true, but these artefacts do not exist: ${absent.join(", ")}.`);
     else rendered = true;
@@ -6038,7 +6131,16 @@ function verifyVerdicts(opts) {
     const v = screenVerdicts.find((x) => typeof x.id === "string" && x.id.trim().toUpperCase() === id);
     return typeof v?.verdict === "string" ? v.verdict : void 0;
   };
-  errors.push(...probeContradictions(probes, verdictOf, specIndexable(opts.projectRoot, opts.surface)));
+  let specFront = "";
+  try {
+    specFront = readFileSync28(join35(opts.projectRoot, ".jig", "specs", `${opts.surface}.spec.md`), "utf8").split(/^---\s*$/m)[1] ?? "";
+  } catch {
+  }
+  if (specIndexableField(specFront) === "unreadable") {
+    errors.push(`.jig/specs/${opts.surface}.spec.md: \`indexable:\` is neither true nor false, so this review cannot tell whether the page is meant to be found and does not guess. Write \`indexable: true\` or \`indexable: false\`, and put the reason in the spec's body.`);
+  } else {
+    errors.push(...probeContradictions(probes, verdictOf, specIndexable(opts.projectRoot, opts.surface)));
+  }
   if (screen.state === "ran" && !rendered) screen.state = "skipped";
   const decisions = checkDecisions(opts.projectRoot, dir, errors);
   const field = (a) => a.state === "ran" ? `ran:${a.judged}` : `${a.state}:${a.judged}${a.state === "incomplete" ? `/${a.total}` : ""}`;
@@ -6050,83 +6152,6 @@ function verifyVerdicts(opts) {
 import { existsSync as existsSync22, mkdirSync as mkdirSync8, readdirSync as readdirSync15, readFileSync as readFileSync29, writeFileSync as writeFileSync7 } from "fs";
 import { createHash as createHash2 } from "crypto";
 import { join as join36 } from "path";
-
-// src/check/spec-shape.ts
-import { existsSync as existsSync21, readFileSync as readFileSync28, readdirSync as readdirSync14, statSync as statSync2 } from "fs";
-import { join as join35 } from "path";
-function newestSpec(projectRoot) {
-  const dir = join35(projectRoot, ".jig", "specs");
-  if (!existsSync21(dir)) return void 0;
-  const files = readdirSync14(dir).filter((f) => f.endsWith(".md"));
-  if (files.length === 0) return void 0;
-  const newest = files.map((f) => ({ f, at: statSync2(join35(dir, f)).mtimeMs })).sort((a, b) => b.at - a.at)[0].f;
-  return { path: `.jig/specs/${newest}`, slug: newest.replace(/\.spec\.md$|\.md$/, ""), body: readFileSync28(join35(dir, newest), "utf8") };
-}
-function specProblems(spec) {
-  const parts = spec.body.split(/^---\s*$/m);
-  const front = parts.length >= 3 ? parts[1] : "";
-  if (!front.trim()) {
-    return [`${spec.path} has no frontmatter. A spec is the frontmatter \u2014 feature, surface, mode, sizes (phone, tablet, desktop), states, decisions, later, mockup, confirmed \u2014 with the reasoning below it. Rewrite it in that shape.`];
-  }
-  const problems = [];
-  const has = (field) => new RegExp(`^\\s*${field}\\s*:`, "im").test(front);
-  for (const field of ["feature", "surface", "mode", "sizes", "confirmed", "mockup"]) {
-    if (!has(field)) problems.push(`${spec.path} frontmatter has no \`${field}:\`.`);
-  }
-  const sizes = front.split(/^sizes\s*:/im)[1] ?? "";
-  for (const size of ["phone", "tablet", "desktop", "wide"]) {
-    const line = new RegExp(`^\\s+${size}\\s*:(.*)$`, "im").exec(sizes);
-    if (!line) {
-      problems.push(`${spec.path} has no \`${size}:\` composition under \`sizes:\`. Every size is written in full, phone first; \`same-as:\` needs a \`why:\`.`);
-      continue;
-    }
-    if (line[1].trim()) {
-      problems.push(`${spec.path}: \`${size}:\` is a one-line description. A size is a composition \u2014 \`regions:\` in order, \`hierarchy:\`, \`nav:\` \u2014 each on its own line, or \`same-as:\` with a \`why:\`.`);
-      continue;
-    }
-    const block = sizeBlock(sizes, size);
-    if (/^\s*same-as\s*:/im.test(block)) {
-      if (!/^\s*why\s*:/im.test(block)) problems.push(`${spec.path}: \`${size}\` claims \`same-as:\` with no \`why:\`. The claim is checked on a render, so it says why it holds.`);
-      continue;
-    }
-    for (const field of ["regions", "nav"]) {
-      if (!new RegExp(`^\\s*${field}\\s*:`, "im").test(block)) {
-        problems.push(`${spec.path}: \`${size}\` has no \`${field}:\`. Every size names its regions in order and what its navigation is at that width (\`nav: none\` when the screen has none).`);
-      }
-    }
-  }
-  return problems;
-}
-function sizeBlock(sizes, size) {
-  const start = new RegExp(`^\\s+${size}\\s*:.*$`, "im").exec(sizes);
-  if (!start) return "";
-  const rest = sizes.slice(start.index + start[0].length);
-  const indent = /^\s*/.exec(start[0])[0].length;
-  const lines = [];
-  for (const line of rest.split("\n")) {
-    if (line.trim() && /^\s*/.exec(line)[0].length <= indent) break;
-    lines.push(line);
-  }
-  return lines.join("\n");
-}
-var MENU_RE = /(?<!\b(?:no|not|without|never)\s)(?<!\bno\s\w{1,12}\s)\b(menu|hamburger|drawer|burger)\b/i;
-var NONE_RE = /^\s*(none|no navigation|n\/a|-)\b/i;
-function navProblems(spec) {
-  const front = spec.body.split(/^---\s*$/m)[1] ?? "";
-  const sizes = front.split(/^sizes\s*:/im)[1] ?? "";
-  const problems = [];
-  for (const size of ["tablet", "landscape", "desktop", "wide"]) {
-    const block = sizeBlock(sizes, size);
-    const nav = /^\s*nav\s*:\s*(.+)$/im.exec(block)?.[1]?.trim();
-    if (!nav || NONE_RE.test(nav)) continue;
-    if (MENU_RE.test(nav) && !/\bopen\b|\bexpanded\b/i.test(nav)) {
-      problems.push(`${spec.path}: \`${size}\` has \`nav: ${nav}\`. Run P-14's table at that width \u2014 where every destination fits, the links show and there is no menu button. A decision about where the button sits is about position, not whether it exists.`);
-    }
-  }
-  return problems;
-}
-
-// src/commands/gate.ts
 var MAX_BLOCKS = 3;
 function lastJigCommand(transcriptPath) {
   if (!transcriptPath || !existsSync22(transcriptPath)) return void 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jig-ui",
-  "version": "0.16.0",
+  "version": "0.16.1",
   "description": "A design system for coding agents. 130 numbered UI rules, brand x mode design tokens, and an installer for Claude Code, Codex, Cursor and opencode.",
   "license": "Apache-2.0",
   "type": "module",

package/rules/03-patterns.md

@@ -479,7 +479,7 @@ Compose it for the phone first. Mobile navigation is a different control — not
 
 Not a component. The procedure for structuring any screen, before styling anything.
 
-### Step 1 — Group
+### Step 1: Group
 
 Four tools, weakest to strongest. Use the weakest that works (`A-67`):
 
@@ -492,7 +492,7 @@ Four tools, weakest to strongest. Use the weakest that works (`A-67`):
 
 Combine them and the container usually becomes unnecessary — a table's rows are already aligned, alike and close. Break continuity deliberately to mark the end of a group, or to interrupt a list with something that is not part of it.
 
-### Step 2 — Order by importance
+### Step 2: Order by importance
 
 Six variables carry hierarchy: **size**, **colour**, **contrast**, **spacing**, **position**, **depth**. The procedure:
 
@@ -504,11 +504,11 @@ Position does more than it looks: people best recall the **first and last** item
 
 Give elements *similar* prominence where they should be read as a pair — matching a label's weight to its icon's balances them instead of letting one shout.
 
-### Step 3 — Space from the inside out
+### Step 3: Space from the inside out
 
 Start at XS on the innermost rectangle and step up moving outward (`D-69`). Between two options, take the larger.
 
-### Step 4 — Align to a grid
+### Step 4: Align to a grid
 
 Main containers align to a 12-column grid; small elements *inside* them do not — those use the spacing options.
 
@@ -516,7 +516,7 @@ Main containers align to a 12-column grid; small elements *inside* them do not
 - **Gutters** fixed, narrower than columns, and kept empty. `--grid-gutter`.
 - **Margins** keep content off the screen edge, wider on large screens. `--grid-margin`.
 
-### Step 5 — The squint test
+### Step 5: The squint test
 
 Blur the design, zoom out, or step back. You should still be able to tell what the screen is for and which element matters most. If everything reads at one weight the hierarchy has failed; if elements smear together the white space is too tight.
 
@@ -524,7 +524,7 @@ Blur the design, zoom out, or step back. You should still be able to tell what t
 
 **When nothing can render it, use the analogue:** if all type were one size and one colour, would the layout still communicate its order? If the hierarchy depends entirely on type styling, it is too weak. The analogue is a fallback, not an equal — a reading of the source is not a look at the page.
 
-### Step 6 — Decide how it collapses
+### Step 6: Decide how it collapses
 
 A spec writes a composition per size. This step is what happens **between** them:
 the same content, arranged for less room. Six rules, and the first is the one

package/rules/04-principles.md

@@ -15,7 +15,7 @@ If you reach for Part 2 often, the rules in `00`–`03` are underspecified and t
 
 # Part 1 · Frames
 
-## R-01 · Frame 1 — Minimise usability risk
+## R-01 · Frame 1: Minimise usability risk
 
 **Ask: who could struggle with this, and why?**
 
@@ -35,7 +35,7 @@ The risk is rarely to the median user. It falls on people with reduced vision, l
 
 **Floor:** WCAG 2.1 level AA. Meeting AA is the starting point, not the achievement.
 
-## R-02 · Frame 2 — Every detail has a reason you can state
+## R-02 · Frame 2: Every detail has a reason you can state
 
 **Ask: why this way rather than another way?**
 
@@ -45,7 +45,7 @@ This is the test every rule in this system had to pass, and it is why the token
 
 **Use it like this:** when you make a call the rules do not cover, state the reason in one line. If you cannot, you are guessing — and a guess should be surfaced as a question, not shipped as a decision (Tiebreaker 5).
 
-## R-03 · Frame 3 — Minimise interaction cost
+## R-03 · Frame 3: Minimise interaction cost
 
 **Ask: what does this cost the user, counted?**
 
@@ -59,7 +59,7 @@ Three reliable reductions:
 
 **Use it like this:** count before and after, and state it. "3 clicks + 1 scroll → 2 clicks" is reviewable. "Improved the UX" is not. See `P-10`.
 
-## R-04 · Frame 4 — Minimise cognitive load
+## R-04 · Frame 4: Minimise cognitive load
 
 **Ask: how much thinking does this require that is not the user's actual task?**
 
@@ -73,7 +73,7 @@ Attention spent decoding the interface is unavailable for the work. Reliable red
 
 **Use it like this:** when something feels heavy but no rule is broken, the load is usually ungrouped information or an unnecessary decision. Split it or remove it. A long form becomes steps; a wide table becomes fewer default columns; six equal options become two recommended and four behind "more".
 
-## R-05 · Frame 5 — Optimise for the common path
+## R-05 · Frame 5: Optimise for the common path
 
 **Ask: what are most people here to do?**
 
@@ -91,31 +91,31 @@ Effort should follow it. Make the common task excellent before making the rare o
 
 Seven. Each resolves a specific conflict in a specific direction. A principle that does not tell you what to give up is decoration.
 
-## R-06 · Tiebreaker 1 — Prefer the loud failure
+## R-06 · Tiebreaker 1: Prefer the loud failure
 
 **Between silent failure and visible failure, choose visible.**
 
 A form that discards a submission and shows success is worse than one that errors. A page serving stale data without saying so is worse than a slow one. Silent failure is the most expensive class of defect, because the cost is paid by someone who never finds out.
 
-## R-07 · Tiebreaker 2 — Never destroy on suspicion
+## R-07 · Tiebreaker 2: Never destroy on suspicion
 
 **When the system suspects input is wrong, mark it and hold it. Do not discard it.**
 
 Spam scores, validation failures, duplicate detection — all heuristics, all wrong sometimes. Hold the item, record why, let a person decide. Applies equally to the user's typing: never clear a form, drop a draft, or overwrite without a copy.
 
-## R-08 · Tiebreaker 3 — Recoverable beats correct
+## R-08 · Tiebreaker 3: Recoverable beats correct
 
 **Between preventing a mistake and allowing it to be undone, choose undo.**
 
 Prevention charges every user friction on every interaction to guard against a rare error. Recovery costs nothing until the error happens. Exception: genuinely irreversible operations, which confirm — and in `operator`, confirm by typing.
 
-## R-09 · Tiebreaker 4 — Optimise for who is actually there
+## R-09 · Tiebreaker 4: Optimise for who is actually there
 
 **When density and legibility conflict, decide by the user's real conditions, not by preference.**
 
 A first-time visitor on mobile data in bright sun and an operator at a large display for eight hours need opposite things. Mode encodes this. When the mode is genuinely unclear, ask — do not average, because the average serves neither.
 
-## R-10 · Tiebreaker 5 — Restraint is the default
+## R-10 · Tiebreaker 5: Restraint is the default
 
 **When a decision has not been made, ship the plainer thing and surface the question.**
 
@@ -125,13 +125,13 @@ An invented accent, a decorative animation, a gradient filling an empty space
 
 **Ceiling: restraint applies to decoration, never to information.** Minimal is not the same as simple. A sparse interface that has dropped labels, selected states or visible actions is harder to use than a busier one that keeps them — it just photographs better. Strip styling freely; never strip the answers to *what is this*, *which one is selected*, and *what can I do next* (`E-63`).
 
-## R-11 · Tiebreaker 6 — The platform before the framework
+## R-11 · Tiebreaker 6: The platform before the framework
 
 **When the browser can already do it, use the browser.**
 
 `<dialog>`, `<details>`, `position: sticky`, `:has()`, container queries, native form validation, `popover`. Platform features carry accessibility, keyboard handling and state management that a reimplementation gets wrong and then needs maintaining.
 
-## R-12 · Tiebreaker 7 — Match the codebase before matching this document
+## R-12 · Tiebreaker 7: Match the codebase before matching this document
 
 **When local convention conflicts with these rules, local convention wins.**
 

package/rules/05-copy.md

@@ -89,6 +89,7 @@ Whichever you choose, be consistent across sibling elements — a list where thr
 Interface text is read in fragments, at a glance, in a space someone else's content has to fit too. An em dash is a pause the reader has to interpret: it stands in for a comma, a colon, a bracket or a full stop, and which one it is only becomes clear after reading past it. The punctuation that says exactly one thing is faster.
 It is also the clearest tell of machine-written copy. Generated text reaches for the em dash far more often than a person does, and readers have learned to notice. Copy that reads as generated is copy the reader trusts less, whatever it says.
 This is about interface strings: labels, buttons, headings, errors, empty states, help text, and the prose a page ships. Markdown counts where a framework renders it as a page, which is most of them (`src/content`, `content/`, MDX routes). A repository document does not: `README.md`, `CHANGELOG.md`, `AGENTS.md` and their kin are written for whoever works on the code, and so are your commit messages and this file.
+A verbatim quotation keeps its own punctuation. Text a page quotes from another source (a document, a spec, a person), marked as a quotation with `<blockquote>` or `<q>`, is that source's words, and changing them to satisfy this rule would misquote it. The page's own copy around the quotation, and any heading or label it gives it, is still held to the rule.
 The en dash keeps its one job: ranges, where it is read as "to" (`2–10 seats`, `Mon–Fri`). That is not a pause, and it is not affected.
 
 ### I-87 Inconsistent vocabulary