jig-ui 0.15.1 → 0.16.1

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # 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
+global stylesheet.
+
+### Changed
+
+- **`theme.<mode>.css` for every mode, once there are two.** `init` kept
+  `theme.css` for the first mode and left it wired into the global stylesheet,
+  so a second mode's routes loaded the first mode's tokens globally and their
+  own from their layout, and got whichever came last. Now each barrel names its
+  mode, the global stylesheet keeps only what every route shares (Tailwind and
+  `utilities.css`), and each route's layout imports its own barrel. A project
+  with one mode is unchanged: `theme.css`, wired globally.
+- **A project gaining a second mode is migrated.** An unedited `theme.css`
+  becomes `theme.<first mode>.css`, and every stylesheet import that resolves
+  to it is removed, found by where it points rather than by guessing the file.
+  An edited one is left, with a note on where its edits belong. `check` names a
+  `theme.css` left beside two modes.
+
 ## 0.15.1
 
 ### Fixed

package/README.md

@@ -123,6 +123,11 @@ jig.config.json             route → mode map
 .jig/state.json             bookkeeping — version, modes, checksums
 ```
 
+Declare a second mode and every barrel names its mode instead —
+`theme.editorial.css`, `theme.operator.css` — and none sits in the global
+stylesheet. Each route's layout imports the barrel for its mode; `init` removes
+the import it added and prints which barrel each surface takes.
+
 Nothing you wrote is touched beyond that one import line. Re-running `init`
 never overwrites a config or brand file you have edited.
 
@@ -604,7 +609,7 @@ treatment.
 | `rules/05-copy.md` | Interface text rules |
 | `<css dir>/jig/brand.*.css` | Identity. One per project. |
 | `<css dir>/jig/mode.*.css` | Density, scale, rhythm, motion |
-| `<css dir>/jig/theme.css` | The barrel — brand + mode. This is what you import. |
+| `<css dir>/jig/theme.css` | The barrel — brand + mode. This is what you import. With more than one mode, `theme.<mode>.css`, one per mode, each imported by its routes' layout. |
 | `.jig/state.json` | What `init` wrote, with checksums. `update` reads it to leave your edits alone. |
 | `.jig/specs/`, `.jig/mockups/`, `.jig/critique/` | The design loop's record: what was agreed, what was drawn, what the review found. |
 

package/dist/index.js

@@ -3911,10 +3911,20 @@ function modeWiringProblems(projectRoot) {
   if (modes.length === 0) return [];
   const dir = dirname6(config.brand);
   const rel = (f) => dir === "." ? f : `${dir}/${f}`;
-  if (!existsSync12(join22(projectRoot, rel("theme.css")))) return [];
+  const multi = modes.length > 1;
+  const barrelOf = (mode) => multi ? `theme.${mode}.css` : "theme.css";
+  const anyBarrel = ["theme.css", ...modes.map((m) => `theme.${m}.css`)].some((f) => existsSync12(join22(projectRoot, rel(f))));
+  if (!anyBarrel) return [];
   const problems = [];
-  modes.forEach((mode, i) => {
-    const barrel = rel(i === 0 ? "theme.css" : `theme.${mode}.css`);
+  if (multi && existsSync12(join22(projectRoot, rel("theme.css")))) {
+    problems.push({
+      mode: modes[0],
+      barrel: rel("theme.css"),
+      message: `jig.config.json declares ${modes.length} modes, so each barrel names its mode: ${rel("theme.css")} should be ${rel(barrelOf(modes[0]))}, imported by the layouts that serve it and not by the global stylesheet`
+    });
+  }
+  modes.forEach((mode) => {
+    const barrel = rel(barrelOf(mode));
     const modeFile = `mode.${mode}.css`;
     let body;
     try {
@@ -5084,7 +5094,8 @@ ${configRelPath} already exists and was not created by 'jig init' (or has been e
   }
   const modeAbsPath = modeAbsPaths[primaryMode];
   const brandFileOnly = brandRelPath.split("/").pop();
-  const barrelFor = (mode) => mode === primaryMode ? "theme.css" : `theme.${mode}.css`;
+  const multiMode = declaredModes.length > 1;
+  const barrelFor = (mode) => multiMode ? `theme.${mode}.css` : "theme.css";
   for (const mode of declaredModes) {
     const rel = relKey(...tokensRelDir, barrelFor(mode));
     const abs = join28(opts.projectRoot, ...tokensRelDir, barrelFor(mode));
@@ -5098,6 +5109,20 @@ ${configRelPath} already exists and was not created by 'jig init' (or has been e
     writeFileSync5(abs, content, "utf8");
     files[rel] = checksum(content);
   }
+  if (multiMode) {
+    const rel = relKey(...tokensRelDir, "theme.css");
+    const abs = join28(opts.projectRoot, ...tokensRelDir, "theme.css");
+    if (existsSync15(abs)) {
+      const state = fileState(opts.projectRoot, abs, rel, initManifest);
+      if (state.tracked && !state.modified) {
+        rmSync2(abs);
+        delete files[rel];
+        log(`  Removed ${rel}: with more than one mode, each barrel names its mode (${relKey(...tokensRelDir, barrelFor(primaryMode))}).`);
+      } else {
+        log(`  ${rel} has been edited, so it is left alone. With more than one mode it is replaced by ${relKey(...tokensRelDir, barrelFor(primaryMode))}; move your edits there and delete it.`);
+      }
+    }
+  }
   if (detection.cssSystem === "tailwind-v4") {
     const declared = declaredTokenNames(
       [brandAbsPath, modeAbsPath].map((f) => {
@@ -5148,8 +5173,9 @@ ${configRelPath} already exists and was not created by 'jig init' (or has been e
       }
     }
   }
-  if (declaredModes.length > 1) {
-    log("\nOne barrel per surface. Import each at that route's entry point:");
+  if (multiMode) {
+    log("\nOne barrel per mode, and none in the global stylesheet. Import each in the layout");
+    log("that serves its routes, and keep Tailwind and utilities.css in the global one:");
     for (const surface of effectiveConfig.surfaces) {
       log(`  '${surface.match}' \u2192 ${relKey(...tokensRelDir, barrelFor(surface.mode))}`);
     }
@@ -5174,7 +5200,33 @@ ${configRelPath} already exists and was not created by 'jig init' (or has been e
   }
   const wireTarget = findWireTarget(detection);
   let wiring;
-  if (wireTarget) {
+  if (multiMode) {
+    const bare = join28(opts.projectRoot, ...tokensRelDir, "theme.css");
+    for (const file of detection.cssFiles.filter((f) => !isTokenLayerFile(f))) {
+      const abs = join28(opts.projectRoot, file);
+      try {
+        const before = readFileSync23(abs, "utf8");
+        const after = before.split("\n").filter((l) => {
+          const m = /^\s*@import\s+["']([^"']+)["'];?\s*$/.exec(l);
+          return !(m && !/^[a-z]+:|^\//i.test(m[1]) && resolve2(dirname7(abs), m[1]) === bare);
+        }).join("\n");
+        if (after !== before) {
+          writeFileSync5(abs, after, "utf8");
+          log(`
+Unwired ${file}: removed its import of ${relKey(...tokensRelDir, "theme.css")}.`);
+          log(`  With more than one mode, the global stylesheet imports no barrel: every route would carry that mode's tokens.`);
+        }
+      } catch (err) {
+        log(`
+Could not edit ${file}: ${err.message}. Remove its import of ${relKey(...tokensRelDir, "theme.css")} by hand.`);
+      }
+    }
+    wiring = {
+      target: null,
+      status: "per-route",
+      snippet: effectiveConfig.surfaces.map((s) => `${s.match} \u2192 ${relKey(...tokensRelDir, barrelFor(s.mode))}`).join("\n")
+    };
+  } else if (wireTarget) {
     const targetAbsDir = dirname7(join28(opts.projectRoot, wireTarget));
     const barrelImport = relativeImportPath(
       targetAbsDir,
@@ -5262,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";
@@ -5296,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) {
@@ -5406,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: {
@@ -5825,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;
@@ -5904,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.`
@@ -5949,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);
@@ -5958,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;
@@ -5986,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}` : ""}`;
@@ -5998,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.15.1",
+  "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/02-tokens.md

@@ -25,9 +25,11 @@ lives in `src/styles/`, `app/assets/stylesheets/jig/` in a Rails app. Set `brand
 in `jig.config.json` to put it elsewhere. Projects set up before 0.7.0 keep their
 `.jig/tokens/` layout; `update` does not move them.
 
-So **never hardcode that path**. `init` writes one barrel per surface, `theme.css`,
-which imports the brand and the mode in the right order — import the barrel, and
-relocating the layer changes one line instead of every stylesheet:
+So **never hardcode that path**. `init` writes a barrel, `theme.css`, which imports
+the brand and the mode in the right order — import the barrel, and relocating the
+layer changes one line instead of every stylesheet. With more than one mode, every
+barrel names its mode instead (`theme.editorial.css`, `theme.operator.css`); see
+"Multiple modes in one app" below:
 
 ```css
 /* src/styles/jig/theme.css — written by init */
@@ -512,8 +514,14 @@ the same token names with different values, so importing all three into one
 document leaves only the last — the other two are inert. That is the mechanical
 reason behind the seam rule below.
 
-**Multiple modes in one app** — scope by route, not by class. Each surface imports its own
-barrel — `jig/theme.css` for the primary surface, `jig/theme.<mode>.css` for the
-others — at that route's layout or entry level. `init` names them and does not
-wire them: which entry point serves `/admin/**` is your routing, which it cannot
-see. Do not attempt to nest two modes in one document (`01-modes.md`, seam rules).
+**Multiple modes in one app** — scope by route, not by class. Every barrel names its
+mode, `jig/theme.<mode>.css`, and each route's layout or entry point imports the
+one for its mode. The global stylesheet imports **no** barrel: one imported there
+puts that mode's tokens under every route, so the operator pages carry editorial's
+too and get whichever loaded last. It keeps what every route shares — Tailwind and
+`utilities.css`, whose aliases name tokens rather than values and so hold for any
+mode. When a second mode is declared, `init` replaces `theme.css` with
+`theme.<first mode>.css` and removes the import it had wired, then prints which
+barrel each surface imports; which layout serves `/admin/**` is your routing, which
+it cannot see. Do not attempt to nest two modes in one document (`01-modes.md`,
+seam rules).

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