jig-ui 0.5.0 → 0.6.0

package/README.md

@@ -251,6 +251,19 @@ contrast below the floor (`C-19`), removed focus rings (`E-29`), gradient text
 (`A-02`), backdrop blur (`A-04`), pure black and white (`C-18`), and the
 violet-band hue check (`A-01`, which asks rather than fails).
 
+**It also reads the token layer itself.** `.jig/tokens/*.css` is not application
+code, so no detector scans it — but it is where a mistake costs most, since every
+call site inherits it. `check` reads back what is declared there and holds it to
+the floors the token layer claims: 4.5:1 for text roles, 3:1 for interface
+strokes, **in both light and dark**, plus `--text-prose` at 18px and
+`--size-touch-target` at 48px. Only floors, never density: `--size-control` at
+28px is a deliberate `operator` choice, and reporting it would teach you to
+ignore the ones that matter.
+
+This is what makes a hand-written or agent-written token layer safe to have.
+`init` validates a colour once, when it writes it; without this, anything edited
+afterwards was never looked at again.
+
 Two deliberate limits. A bare `p-4` is **not** a finding — it resolves through a
 scale, which is what a scale is for, and the scale is your project's decision.
 And a colour outside the framework's default palette is not resolved rather than
@@ -300,12 +313,32 @@ Drop this in the project root so mode selection does not require asking on every
 ```jsonc
 // jig.config.json
 {
-  "brand": ".jig/tokens/brand.acme.css",
+  // Where the token layer lives. `init` writes the brand file here and puts
+  // the mode files beside it. Omit it and you get `.jig/tokens/`.
+  "brand": "src/styles/jig/brand.acme.css",
+
+  // One entry per surface. This outranks an agent's own reading of the
+  // project, so it is worth getting right before `init` runs.
   "surfaces": [
     { "match": "/",         "mode": "editorial" },
     { "match": "/app/**",   "mode": "product"   },
     { "match": "/admin/**", "mode": "operator"  }
-  ]
+  ],
+
+  // Files that render OUTSIDE the cascade, where a literal is the only thing
+  // that works: an OG card serialised into an SVG `foreignObject` carries no
+  // stylesheet, and a PDF drawn by a React renderer never sees CSS.
+  //
+  // Prefer an exact path. An exemption is a claim about ONE file's rendering
+  // context, and that is usually literally true of one file. Reach for a glob
+  // only where the directory exists to hold them — `src/cv/pdf/**` is a fact
+  // about that tree; `**/*-card.tsx` is a naming coincidence that would also
+  // excuse every real card component you have.
+  //
+  // `check` names the pattern and its match count on every run, and says so
+  // when one is excusing enough files to look like a mistake. Nothing is ever
+  // exempt by default: this list is the only source.
+  "exempt": ["src/components/og-card.tsx", "src/cv/pdf/**"]
 }
 ```
 

package/dist/index.js

@@ -2,9 +2,9 @@
 
 // src/index.ts
 import { Command } from "commander";
-import { readFileSync as readFileSync17 } from "fs";
+import { readFileSync as readFileSync19 } from "fs";
 import { homedir } from "os";
-import { join as join22 } from "path";
+import { join as join24 } from "path";
 
 // src/paths.ts
 import { existsSync } from "fs";
@@ -49,9 +49,9 @@ import { join as join7 } from "path";
 var COMMAND_DESCRIPTION = "Run a Jig design-system command: set the project up, review the UI against the rules, or refresh the install.";
 var SKILL_DESCRIPTION = "Design system rules for generating and reviewing UI. Load before building any interface.";
 function assertSafeRelPath(relPath, adapterName) {
-  const isAbsolute = relPath.startsWith("/") || /^[A-Za-z]:/.test(relPath);
+  const isAbsolute2 = relPath.startsWith("/") || /^[A-Za-z]:/.test(relPath);
   const hasDotDotSegment = relPath.split(/[\\/]/).includes("..");
-  if (isAbsolute || hasDotDotSegment) {
+  if (isAbsolute2 || hasDotDotSegment) {
     throw new Error(`Adapter '${adapterName}' produced an unsafe relPath: ${relPath}`);
   }
 }
@@ -1229,8 +1229,8 @@ function sectionsOf(entries) {
 }
 
 // src/commands/check.ts
-import { existsSync as existsSync10, readFileSync as readFileSync12 } from "fs";
-import { join as join17 } from "path";
+import { existsSync as existsSync12, readFileSync as readFileSync14 } from "fs";
+import { join as join19 } from "path";
 
 // src/check/files.ts
 import { execFileSync } from "child_process";
@@ -1427,6 +1427,17 @@ function formatReport(findings, meta) {
   const rulesFired = new Set(findings.map((f) => f.ruleId)).size;
   const scope = meta.totalSpecs ? `${meta.totalRules} rules (+ ${meta.totalSpecs} pattern and mode specs)` : `${meta.totalRules} rules`;
   lines.push(`  ${summaryParts.join(", ")} \xB7 ${scope}, ${rulesFired} fired`);
+  if (meta.exemptPatterns && meta.exemptPatterns.length > 0) {
+    const n = meta.exempt?.length ?? 0;
+    lines.push(`  ${n} file(s) exempt via jig.config.json and not scanned:`);
+    for (const { pattern, count, tooBroad } of meta.exemptPatterns) {
+      const note = count === 0 ? "matches nothing \u2014 check the path" : tooBroad ? `${count} files \u2014 likely too broad, review it` : `${count} file${count > 1 ? "s" : ""}`;
+      lines.push(`    ${pattern}  (${note})`);
+    }
+    if (n > 0) {
+      lines.push(`    ${meta.exempt.slice(0, 8).join(", ")}${n > 8 ? `, and ${n - 8} more` : ""}`);
+    }
+  }
   if (meta.unscanned && meta.unscanned.count > 0) {
     const exts = meta.unscanned.extensions.join(", ");
     lines.push("");
@@ -2447,13 +2458,38 @@ var COLOR_LITERAL_RE = /#[0-9a-fA-F]{3,8}\b|(?:rgb|hsl)a?\([^)]*\)/;
 var PX_RE = /(-?\d*\.?\d+)px/g;
 var EXCLUDED_PX = /* @__PURE__ */ new Set([0, 1, 2]);
 var KEYFRAME_STEP_RE = /^(from|to|\d+(\.\d+)?%)$/i;
+var PRIMITIVE_RE = /var\(\s*(--(?:brand|error|warning|success|info)-(?:h|s|l|fill-a))\s*[,)]/g;
+var TOKEN_LAYER_RE = /(^|\/)(\.jig\/tokens|jig)\/[^/]+\.css$/;
+function primitiveConsumption(source, file, ctx) {
+  if (TOKEN_LAYER_RE.test(file)) return [];
+  const out = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const m of source.matchAll(PRIMITIVE_RE)) {
+    const token = m[1];
+    const line = source.slice(0, m.index ?? 0).split("\n").length;
+    const key = `${token}:${line}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push(
+      mkFinding(
+        ctx,
+        "hardcoded-value",
+        file,
+        line,
+        `${token} is a raw channel input, not a semantic role \u2014 consuming it bypasses the theme overrides, which remap \`--color-*\` and never the channels. Use the semantic token for what this is (\`--color-text-*\`, \`--color-fill-*\`, \`--color-stroke-*\`).`,
+        sourceLine(source, line)
+      )
+    );
+  }
+  return out;
+}
 var hardcodedValue = {
   name: "hardcoded-value",
   appliesTo: (file) => isStyleBearing(file),
   run(source, file, ctx) {
+    const findings = primitiveConsumption(source, file, ctx);
     const participates = isStyleHost(file) ? ctx.projectParticipates : participatesInTokenLayer(source, ctx.tokens);
-    if (!participates) return [];
-    const findings = [];
+    if (!participates) return findings;
     for (const block of leafBlocks(source)) {
       if (KEYFRAME_STEP_RE.test(block.selector.trim())) continue;
       DECL_RE2.lastIndex = 0;
@@ -2645,16 +2681,214 @@ function loadTokenMap(projectRoot, consumerFiles = []) {
   return tokens;
 }
 
+// src/check/exempt.ts
+import { existsSync as existsSync10, readFileSync as readFileSync12 } from "fs";
+import { join as join17 } from "path";
+function globToRegExp(glob) {
+  let out = "";
+  for (let i = 0; i < glob.length; i++) {
+    const c = glob[i];
+    if (c === "*") {
+      if (glob[i + 1] === "*") {
+        out += ".*";
+        i++;
+        if (glob[i + 1] === "/") i++;
+      } else {
+        out += "[^/]*";
+      }
+    } else if (c === "?") out += "[^/]";
+    else out += c.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+  }
+  return new RegExp(`^${out}$`);
+}
+function readExemptions(projectRoot) {
+  const configPath = join17(projectRoot, "jig.config.json");
+  if (!existsSync10(configPath)) return [];
+  let declared;
+  try {
+    declared = JSON.parse(readFileSync12(configPath, "utf8")).exempt;
+  } catch {
+    return [];
+  }
+  if (!Array.isArray(declared)) return [];
+  return declared.filter(
+    (p) => typeof p === "string" && p.trim() !== "" && !p.startsWith("/") && !p.split("/").includes("..")
+  );
+}
+var LIKELY_TOO_BROAD = 3;
+function applyExemptions(files, patterns) {
+  if (patterns.length === 0) return { scanned: files, exempt: [], byPattern: [] };
+  const compiled = patterns.map((pattern) => ({ pattern, re: globToRegExp(pattern), count: 0 }));
+  const scanned = [];
+  const exempt = [];
+  for (const file of files) {
+    const matches2 = compiled.filter((c) => c.re.test(file));
+    for (const m of matches2) m.count++;
+    (matches2.length > 0 ? exempt : scanned).push(file);
+  }
+  return {
+    scanned,
+    exempt,
+    byPattern: compiled.map(({ pattern, count }) => ({
+      pattern,
+      count,
+      tooBroad: count > LIKELY_TOO_BROAD
+    }))
+  };
+}
+
+// src/check/token-audit.ts
+import { existsSync as existsSync11, readdirSync as readdirSync8, readFileSync as readFileSync13 } from "fs";
+import { join as join18 } from "path";
+var TEXT_FLOOR = 4.5;
+var UI_FLOOR = 3;
+var FOREGROUNDS = [
+  { prefix: "--color-text-", floor: TEXT_FLOOR },
+  { prefix: "--color-stroke-", floor: UI_FLOOR },
+  { prefix: "--color-focus", floor: UI_FLOOR }
+];
+var SURFACES = ["--color-bg-base", "--color-bg-raised", "--color-bg-overlay", "--color-fill"];
+var NUMERIC_FLOORS = [
+  { token: "--text-prose", min: 18, why: "sustained reading (B-75)" },
+  { token: "--size-touch-target", min: 48, why: "hit area, unchanged in every mode" }
+];
+function composite(fg, alpha, bg) {
+  return {
+    r: Math.round(fg.r * alpha + bg.r * (1 - alpha)),
+    g: Math.round(fg.g * alpha + bg.g * (1 - alpha)),
+    b: Math.round(fg.b * alpha + bg.b * (1 - alpha))
+  };
+}
+function isDarkBlock(selector, atRuleDepth) {
+  return /data-theme\s*=\s*["']?dark/.test(selector) || atRuleDepth > 0;
+}
+function collectScopes(files) {
+  const light = {};
+  const darkOverrides = {};
+  for (const { path, source } of files) {
+    for (const block of splitRuleBlocks(source)) {
+      if (block.body.includes("{")) continue;
+      if (!/^:root/.test(block.selector.trim())) continue;
+      const target = isDarkBlock(block.selector, block.atRuleDepth) ? darkOverrides : light;
+      for (const m of block.body.matchAll(/(--[\w-]+)\s*:\s*([^;]+);/g)) {
+        const offsetInBody = m.index ?? 0;
+        target[m[1]] = {
+          value: m[2].trim(),
+          file: path,
+          // `bodyStartLine` is where the block's body begins; add the newlines
+          // before this declaration inside it.
+          line: block.bodyStartLine + block.body.slice(0, offsetInBody).split("\n").length - 1
+        };
+      }
+    }
+  }
+  return { light, dark: { ...light, ...darkOverrides } };
+}
+var asTokenMap = (scope) => Object.fromEntries(Object.entries(scope).map(([k, v]) => [k.replace(/^--/, ""), v.value]));
+function floorFor(token) {
+  if (/^--color-stroke-.*-weak$/.test(token) || token === "--color-stroke-weak") return null;
+  for (const { prefix, floor } of FOREGROUNDS) {
+    if (token.startsWith(prefix)) return floor;
+  }
+  return null;
+}
+function tokenFiles(projectRoot) {
+  const read = (rel) => {
+    try {
+      return readFileSync13(join18(projectRoot, ...rel.split("/")), "utf8");
+    } catch {
+      return null;
+    }
+  };
+  const statePath = join18(projectRoot, ".jig", "state.json");
+  if (existsSync11(statePath)) {
+    try {
+      const state = JSON.parse(readFileSync13(statePath, "utf8"));
+      const recorded = Object.keys(state.files ?? {}).filter((f) => f.endsWith(".css")).sort();
+      const out = recorded.map((path) => ({ path, source: read(path) })).filter((f) => f.source !== null);
+      if (out.length > 0) return out;
+    } catch {
+    }
+  }
+  const legacy = join18(projectRoot, ".jig", "tokens");
+  if (!existsSync11(legacy)) return [];
+  return readdirSync8(legacy).filter((f) => f.endsWith(".css")).sort().map((f) => ({ path: `.jig/tokens/${f}`, source: readFileSync13(join18(legacy, f), "utf8") }));
+}
+function auditTokenLayer(projectRoot) {
+  const files = tokenFiles(projectRoot);
+  if (files.length === 0) return [];
+  const scopes = collectScopes(files);
+  const problems = [];
+  for (const theme of ["light", "dark"]) {
+    const scope = scopes[theme];
+    const map = asTokenMap(scope);
+    const base = extractColorComponents(scope["--color-bg-base"]?.value ?? "", map);
+    const surfaces = [];
+    for (const name of SURFACES) {
+      const decl = scope[name];
+      if (!decl) continue;
+      const c = extractColorComponents(decl.value, map);
+      if (!c) continue;
+      if (c.alpha >= 0.999) surfaces.push({ name, rgb: c.rgb });
+      else if (base && base.alpha >= 0.999) {
+        surfaces.push({ name, rgb: composite(c.rgb, c.alpha, base.rgb) });
+      }
+    }
+    if (surfaces.length === 0) continue;
+    for (const [token, decl] of Object.entries(scope)) {
+      const floor = floorFor(token);
+      if (floor === null) continue;
+      const fg = extractColorComponents(decl.value, map);
+      if (!fg) continue;
+      const failures = surfaces.map((surface) => {
+        const solid = fg.alpha >= 0.999 ? fg.rgb : composite(fg.rgb, fg.alpha, surface.rgb);
+        return { surface: surface.name, ratio: contrastRatio(solid, surface.rgb) };
+      }).filter((f) => f.ratio < floor).sort((a, b) => a.ratio - b.ratio);
+      if (failures.length === 0) continue;
+      const worst = failures[0];
+      const others = failures.length - 1;
+      problems.push({
+        token,
+        surface: worst.surface,
+        theme,
+        ratio: Math.round(worst.ratio * 100) / 100,
+        floor,
+        file: decl.file,
+        line: decl.line,
+        message: `${token} is ${worst.ratio.toFixed(2)}:1 against ${worst.surface} in ${theme} mode, below the ${floor}:1 floor the token layer states for this role` + (others > 0 ? ` (and below it on ${others} other surface${others > 1 ? "s" : ""})` : "") + "."
+      });
+    }
+    for (const { token, min, why } of NUMERIC_FLOORS) {
+      const decl = scope[token];
+      if (!decl) continue;
+      const px = /^([\d.]+)px$/.exec(decl.value.trim());
+      if (!px) continue;
+      const value = Number(px[1]);
+      if (value >= min) continue;
+      problems.push({
+        token,
+        theme,
+        value,
+        floor: min,
+        file: decl.file,
+        line: decl.line,
+        message: `${token} is ${value}px, below the ${min}px floor for ${why}. This is an accessibility limit, not a density setting.`
+      });
+    }
+  }
+  return problems;
+}
+
 // src/commands/check.ts
-var LEGACY_INDEX_REL = join17(".jig", "rules.index.json");
+var LEGACY_INDEX_REL = join19(".jig", "rules.index.json");
 function resolveIndexPath(projectRoot) {
-  const legacy = join17(projectRoot, LEGACY_INDEX_REL);
-  if (existsSync10(legacy)) return legacy;
-  return join17(assetRoot(), "rules.index.json");
+  const legacy = join19(projectRoot, LEGACY_INDEX_REL);
+  if (existsSync12(legacy)) return legacy;
+  return join19(assetRoot(), "rules.index.json");
 }
 function resolveMode(projectRoot) {
   try {
-    const config = JSON.parse(readFileSync12(join17(projectRoot, "jig.config.json"), "utf8"));
+    const config = JSON.parse(readFileSync14(join19(projectRoot, "jig.config.json"), "utf8"));
     const modes = [...new Set((config.surfaces ?? []).map((s) => s.mode).filter(Boolean))];
     if (modes.length === 1) return modes[0];
     return modes.length > 1 ? "mixed" : "unknown";
@@ -2671,28 +2905,46 @@ function summariseUnscanned(files) {
 }
 function countSpecs() {
   try {
-    return loadSpecs(join17(assetRoot(), "rules")).length;
+    return loadSpecs(join19(assetRoot(), "rules")).length;
   } catch {
     return 0;
   }
 }
 function check(opts) {
   const indexPath = resolveIndexPath(opts.projectRoot);
-  const index = validateIndex(JSON.parse(readFileSync12(indexPath, "utf8")));
+  const index = validateIndex(JSON.parse(readFileSync14(indexPath, "utf8")));
   const selection = selectFiles(opts.projectRoot, opts.all);
-  const { files } = selection;
+  const exemptions = readExemptions(opts.projectRoot);
+  const { scanned: files, exempt, byPattern } = applyExemptions(selection.files, exemptions);
   const bucketFilter = opts.ci ? (b) => b === "mechanical" : void 0;
   const stylesheets = selection.mode === "all" ? files : selectFiles(opts.projectRoot, true).files;
   const tokens = loadTokenMap(opts.projectRoot, stylesheets);
   const projectParticipates = stylesheets.some((f) => {
     if (!hasExtension(f, CSS_EXTENSIONS)) return false;
     try {
-      return participatesInTokenLayer(readFileSync12(join17(opts.projectRoot, f), "utf8"), tokens);
+      return participatesInTokenLayer(readFileSync14(join19(opts.projectRoot, f), "utf8"), tokens);
     } catch {
       return false;
     }
   });
   const findings = runChecks(opts.projectRoot, files, index, tokens, bucketFilter, projectParticipates);
+  const TOKEN_RULE = {
+    "--text-prose": "B-75",
+    "--size-touch-target": "E-51"
+  };
+  for (const problem of auditTokenLayer(opts.projectRoot)) {
+    const ruleId = TOKEN_RULE[problem.token] ?? "C-19";
+    const entry = index.find((e) => e.id === ruleId);
+    findings.push({
+      ruleId,
+      detector: "token-layer",
+      bucket: entry?.bucket ?? "mechanical",
+      severity: entry?.severity ?? "error",
+      file: problem.file,
+      line: problem.line,
+      message: problem.message
+    });
+  }
   const hasError = findings.some((f) => f.bucket === "mechanical" && f.severity === "error");
   const cssFiles = files.filter((f) => /\.(css|scss|less)$/i.test(f));
   const noTokenLayer = (
@@ -2700,7 +2952,7 @@ function check(opts) {
     // told to add a token @import it has nowhere to put.
     cssFiles.length > 0 && cssFiles.every((f) => {
       try {
-        return !participatesInTokenLayer(readFileSync12(join17(opts.projectRoot, f), "utf8"), tokens);
+        return !participatesInTokenLayer(readFileSync14(join19(opts.projectRoot, f), "utf8"), tokens);
       } catch {
         return true;
       }
@@ -2715,18 +2967,20 @@ function check(opts) {
     version: opts.version,
     noTokenLayer,
     mode: resolveMode(opts.projectRoot),
-    unscanned: summariseUnscanned(files)
+    unscanned: summariseUnscanned(files),
+    exempt,
+    exemptPatterns: byPattern
   });
   return { findings, report, hasError };
 }
 
 // src/commands/init.ts
-import { existsSync as existsSync11, mkdirSync as mkdirSync5, readFileSync as readFileSync16, writeFileSync as writeFileSync4 } from "fs";
-import { dirname as dirname6, join as join21 } from "path";
+import { existsSync as existsSync13, mkdirSync as mkdirSync5, readdirSync as readdirSync9, readFileSync as readFileSync18, writeFileSync as writeFileSync4 } from "fs";
+import { dirname as dirname6, isAbsolute, join as join23, resolve as resolve2, sep as sep3 } from "path";
 
 // src/init/detect.ts
-import { readFileSync as readFileSync13 } from "fs";
-import { join as join18 } from "path";
+import { readFileSync as readFileSync15 } from "fs";
+import { join as join20 } from "path";
 var TAILWIND_CONFIG_RE = /^tailwind\.config\.(js|ts|mjs|cjs)$/;
 var TAILWIND_V4_IMPORT_RE = /@import\s+["']tailwindcss["']/;
 var TAILWIND_V4_THEME_RE = /@theme\b/;
@@ -2743,7 +2997,7 @@ var FRAMEWORK_DEPS = [
 function detectFramework(projectRoot) {
   let pkg;
   try {
-    pkg = JSON.parse(readFileSync13(join18(projectRoot, "package.json"), "utf8"));
+    pkg = JSON.parse(readFileSync15(join20(projectRoot, "package.json"), "utf8"));
   } catch {
     return void 0;
   }
@@ -2761,7 +3015,7 @@ function detect(projectRoot) {
   for (const f of cssFiles) {
     let source;
     try {
-      source = readFileSync13(join18(projectRoot, f), "utf8");
+      source = readFileSync15(join20(projectRoot, f), "utf8");
     } catch {
       continue;
     }
@@ -2796,8 +3050,8 @@ function isIgnored(projectRoot, relPath) {
 }
 
 // src/init/derive.ts
-import { readFileSync as readFileSync14 } from "fs";
-import { join as join19 } from "path";
+import { readFileSync as readFileSync16 } from "fs";
+import { join as join21 } from "path";
 var DEFAULT_PROPOSAL = {
   h: 264,
   s: 0,
@@ -2830,7 +3084,7 @@ function fromCssCustomProperties(projectRoot, cssFiles) {
   for (const file of cssFiles) {
     let source;
     try {
-      source = readFileSync14(join19(projectRoot, file), "utf8");
+      source = readFileSync16(join21(projectRoot, file), "utf8");
     } catch {
       continue;
     }
@@ -2879,7 +3133,7 @@ function balancedBraceBody(source, openIdx) {
 function fromTailwindConfig(projectRoot, tailwindConfigFile) {
   let source;
   try {
-    source = readFileSync14(join19(projectRoot, tailwindConfigFile), "utf8");
+    source = readFileSync16(join21(projectRoot, tailwindConfigFile), "utf8");
   } catch {
     return null;
   }
@@ -2935,7 +3189,7 @@ function fromLiteralFrequency(projectRoot, cssFiles) {
   for (const file of cssFiles) {
     let source;
     try {
-      source = readFileSync14(join19(projectRoot, file), "utf8");
+      source = readFileSync16(join21(projectRoot, file), "utf8");
     } catch {
       continue;
     }
@@ -3095,8 +3349,8 @@ function relativeImportPath(fromAbsDir, toAbsFile) {
 }
 
 // src/init/project-name.ts
-import { readFileSync as readFileSync15 } from "fs";
-import { basename, join as join20 } from "path";
+import { readFileSync as readFileSync17 } from "fs";
+import { basename, join as join22 } from "path";
 function slugify(name) {
   const withoutScope = name.replace(/^@[^/]+\//, "");
   const slug = withoutScope.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
@@ -3104,7 +3358,7 @@ function slugify(name) {
 }
 function deriveProjectSlug(projectRoot) {
   try {
-    const pkg = JSON.parse(readFileSync15(join20(projectRoot, "package.json"), "utf8"));
+    const pkg = JSON.parse(readFileSync17(join22(projectRoot, "package.json"), "utf8"));
     if (typeof pkg.name === "string" && pkg.name.trim()) return slugify(pkg.name);
   } catch {
   }
@@ -3170,7 +3424,7 @@ function parseSurfaces(answer, fallback) {
   return parsed.length > 0 ? parsed : fallback;
 }
 function fileState(projectRoot, absPath, relPath, initManifest) {
-  const existsOnDisk = existsSync11(absPath);
+  const existsOnDisk = existsSync13(absPath);
   const tracked = !!initManifest && relPath in initManifest.files;
   const modified = tracked && isInitFileModified(projectRoot, relPath, initManifest);
   return { existsOnDisk, tracked, modified };
@@ -3181,11 +3435,11 @@ function isValidSurfaceArray(v) {
   );
 }
 function loadEffectiveConfig(projectRoot, configAbsPath, fallbackBrand, fallbackSurfaces) {
-  if (!existsSync11(configAbsPath)) return { brand: fallbackBrand, surfaces: fallbackSurfaces };
+  if (!existsSync13(configAbsPath)) return { brand: fallbackBrand, surfaces: fallbackSurfaces };
   try {
-    const parsed = JSON.parse(readFileSync16(configAbsPath, "utf8"));
+    const parsed = JSON.parse(readFileSync18(configAbsPath, "utf8"));
     const brandCandidate = typeof parsed.brand === "string" && parsed.brand ? parsed.brand : void 0;
-    const brandResolves = brandCandidate ? existsSync11(join21(projectRoot, ...brandCandidate.split("/"))) : false;
+    const brandResolves = brandCandidate ? existsSync13(join23(projectRoot, ...brandCandidate.split("/"))) : false;
     return {
       brand: brandResolves ? brandCandidate : fallbackBrand,
       surfaces: isValidSurfaceArray(parsed.surfaces) ? parsed.surfaces : fallbackSurfaces
@@ -3194,12 +3448,61 @@ function loadEffectiveConfig(projectRoot, configAbsPath, fallbackBrand, fallback
     return { brand: fallbackBrand, surfaces: fallbackSurfaces };
   }
 }
+function configuredBrandPath(projectRoot, configAbsPath) {
+  if (!existsSync13(configAbsPath)) return { path: null };
+  let declared;
+  try {
+    declared = JSON.parse(readFileSync18(configAbsPath, "utf8")).brand;
+  } catch {
+    return { path: null };
+  }
+  if (typeof declared !== "string" || !declared.trim()) return { path: null };
+  const rel = declared.trim().replace(/\\/g, "/");
+  const abs = resolve2(projectRoot, rel);
+  const root = resolve2(projectRoot);
+  if (isAbsolute(rel) || abs !== root && !abs.startsWith(root + sep3)) {
+    return { path: null, refused: rel };
+  }
+  if (!/\.css$/i.test(rel)) return { path: null, refused: rel };
+  return { path: rel };
+}
+function defaultTokenDir(detection) {
+  const target = findWireTarget(detection);
+  if (target) return [...target.split("/").slice(0, -1), "jig"];
+  const candidates = detection.cssFiles.filter((f) => !isCssModule(f) && !isTokenLayerFile(f));
+  if (candidates.length > 1) {
+    const dirs = new Set(candidates.map((f) => f.split("/").slice(0, -1).join("/")));
+    if (dirs.size === 1) {
+      const only = [...dirs][0];
+      return only ? [...only.split("/"), "jig"] : ["jig"];
+    }
+  }
+  return ["jig"];
+}
+function readConfiguredSurfaces(configAbsPath) {
+  if (!existsSync13(configAbsPath)) return null;
+  try {
+    const parsed = JSON.parse(readFileSync18(configAbsPath, "utf8"));
+    return isValidSurfaceArray(parsed.surfaces) ? parsed.surfaces : null;
+  } catch {
+    return null;
+  }
+}
 function isCssModule(path) {
   return /\.module\.(css|scss)$/i.test(path);
 }
+function legacyBrandFile(projectRoot) {
+  const dir = join23(projectRoot, ".jig", "tokens");
+  if (!existsSync13(dir)) return void 0;
+  const found = readdirSync9(dir).find((f) => /^brand\.[\w.-]+\.css$/.test(f));
+  return found ? relKey(".jig", "tokens", found) : void 0;
+}
+function isTokenLayerFile(f) {
+  return /(^|\/)(\.jig\/tokens|jig)\/[^/]+\.css$/.test(f);
+}
 function findWireTarget(d) {
   if (d.cssSystem === "tailwind-v4" && d.tailwindV4EntryFile) return d.tailwindV4EntryFile;
-  const candidates = d.cssFiles.filter((f) => !isCssModule(f));
+  const candidates = d.cssFiles.filter((f) => !isCssModule(f) && !isTokenLayerFile(f));
   if (candidates.length === 1) return candidates[0];
   return null;
 }
@@ -3210,45 +3513,35 @@ function insertAfterCharset(content, insertion) {
   const charsetLen = m ? m[0].length : 0;
   return content.slice(0, charsetLen) + insertion + content.slice(charsetLen);
 }
-function wireImport(absPath, brandImport, modeImport, mode) {
-  const content = existsSync11(absPath) ? readFileSync16(absPath, "utf8") : "";
-  const brandImportLine = `@import "${brandImport}";`;
-  const modeImportLine = `@import "${modeImport}";`;
-  const brandPresent = content.includes(brandImportLine);
-  const existingModeMatch = MODE_IMPORT_RE.exec(content);
-  if (brandPresent) {
-    if (existingModeMatch && existingModeMatch[0].trim() === modeImportLine) {
-      return { status: "already-present" };
-    }
-    if (existingModeMatch) {
-      const previousMode = existingModeMatch[2];
-      const next3 = content.slice(0, existingModeMatch.index) + `${modeImportLine}
-` + content.slice(existingModeMatch.index + existingModeMatch[0].length);
-      writeFileSync4(absPath, next3, "utf8");
-      return { status: "rewired", detail: `rewired mode: ${previousMode} \u2192 ${mode}` };
-    }
-    const brandIdx = content.indexOf(brandImportLine);
-    let insertAt = brandIdx + brandImportLine.length;
-    if (content[insertAt] === "\r") insertAt++;
-    if (content[insertAt] === "\n") insertAt++;
-    const next2 = content.slice(0, insertAt) + modeImportLine + "\n" + content.slice(insertAt);
-    writeFileSync4(absPath, next2, "utf8");
-    return { status: "rewired", detail: `added missing mode import: ${mode}` };
-  }
-  const lines = `${brandImportLine}
-${modeImportLine}
+function barrelBody(fileName, brandFile, mode, version2) {
+  return vendorHeader(fileName, version2, "css", null) + `/* The token layer for one surface, in one import.
+   Brand declares the options; the mode selects from them. */
+@import "./${brandFile}";
+@import "./mode.${mode}.css";
 `;
-  const tailwindImportMatch = /@import\s+["']tailwindcss["'];?\r?\n?/.exec(content);
-  let next;
-  if (tailwindImportMatch) {
-    const idx = tailwindImportMatch.index + tailwindImportMatch[0].length;
-    next = content.slice(0, idx) + lines + content.slice(idx);
-  } else {
-    next = insertAfterCharset(content, content ? `${lines}
-` : lines);
+}
+var LEGACY_PAIR_RE = new RegExp(
+  `@import\\s+["'][^"']*brand\\.[\\w.-]+\\.css["'];?\\r?\\n?\\s*@import\\s+["'][^"']*mode\\.(?:${MODES.join("|")})\\.css["'];?\\r?\\n?`
+);
+function wireBarrel(absPath, barrelImport) {
+  const content = existsSync13(absPath) ? readFileSync18(absPath, "utf8") : "";
+  const line = `@import "${barrelImport}";`;
+  if (content.includes(line)) return { status: "already-present" };
+  const legacy = LEGACY_PAIR_RE.exec(content);
+  if (legacy) {
+    const next2 = content.slice(0, legacy.index) + `${line}
+` + content.slice(legacy.index + legacy[0].length);
+    writeFileSync4(absPath, next2, "utf8");
+    return { status: "rewired", detail: "replaced the separate brand and mode imports with the barrel" };
   }
+  const tailwind = /@import\s+["']tailwindcss["'];?\r?\n?/.exec(content);
+  const next = tailwind ? content.slice(0, tailwind.index + tailwind[0].length) + `${line}
+` + content.slice(tailwind.index + tailwind[0].length) : insertAfterCharset(content, content ? `${line}
+
+` : `${line}
+`);
   mkdirSync5(dirname6(absPath), { recursive: true });
-  writeFileSync4(absPath, next, "utf8");
+  writeFileSync4(next === content ? absPath : absPath, next, "utf8");
   return { status: "wired" };
 }
 async function init(opts) {
@@ -3314,8 +3607,11 @@ async function init(opts) {
     }
   }
   if (opts.yes) {
+    const declared = readConfiguredSurfaces(join23(opts.projectRoot, "jig.config.json"));
+    const inEffect = declared ?? surfaces;
+    const map = inEffect.map((x) => `'${x.match}' \u2192 ${x.mode}`).join(", ");
     log(
-      `Surface \u2192 mode: ${surfaces.map((s) => `'${s.match}' \u2192 ${s.mode}`).join(", ")} \u2014 the default, not inferred from this project. Mode sets density, type scale and control sizes, and it wins over an agent's own inference, so change it in jig.config.json if another mode fits (${MODES.join("/")}).`
+      declared ? `Surface \u2192 mode: ${map} \u2014 from jig.config.json. Mode sets density, type scale and control sizes, and it outranks an agent's own reading of the project.` : `Surface \u2192 mode: ${map} \u2014 the default, not inferred from this project. Mode sets density, type scale and control sizes, and it wins over an agent's own inference, so change it in jig.config.json if another mode fits (${MODES.join("/")}).`
     );
   }
   if (!validation.passesContrast && validation.nearestPassingLightness !== void 0) {
@@ -3329,11 +3625,30 @@ Brand colour adjusted to clear the 4.5:1 contrast floor: l:${originalL}% \u2192
   }
   const finalColor = { h: proposal.h, s: proposal.s, l: proposal.l };
   const projectSlug = deriveProjectSlug(opts.projectRoot);
-  const brandRelPath = relKey(".jig", "tokens", brandFileName(projectSlug));
-  const brandAbsPath = join21(opts.projectRoot, ".jig", "tokens", brandFileName(projectSlug));
   const configRelPath = "jig.config.json";
-  const configAbsPath = join21(opts.projectRoot, configRelPath);
-  const initManifest = readInitManifest(opts.projectRoot);
+  const configAbsPath = join23(opts.projectRoot, configRelPath);
+  const configuredBrand = configuredBrandPath(opts.projectRoot, configAbsPath);
+  if (configuredBrand.refused) {
+    log(
+      `jig.config.json names brand '${configuredBrand.refused}', which is outside the project or is not a .css file \u2014 ignoring it and using the default location.`
+    );
+  }
+  const priorManifest = readInitManifest(opts.projectRoot);
+  const priorBrand = Object.keys(priorManifest?.files ?? {}).find((f) => /(^|\/)brand\.[\w.-]+\.css$/.test(f)) ?? // Also honour a brand file that is simply THERE. A project may hold one
+  // init never recorded — written by hand, or by a version that predates the
+  // sidecar — and writing a second one somewhere else would leave two token
+  // layers, which is worse than either location.
+  detection.cssFiles.find((f) => isTokenLayerFile(f) && /(^|\/)brand\./.test(f)) ?? // `.jig/` is a dotdir, so detection never walks into it. Probe it directly:
+  // a project holding a legacy token layer must keep it rather than gain a
+  // second one somewhere else.
+  legacyBrandFile(opts.projectRoot);
+  const brandRelPath = configuredBrand.path ?? priorBrand ?? relKey(...defaultTokenDir(detection), brandFileName(projectSlug));
+  const brandAbsPath = join23(opts.projectRoot, ...brandRelPath.split("/"));
+  const tokensRelDir = brandRelPath.split("/").slice(0, -1);
+  log(
+    `Token layer: ${tokensRelDir.join("/") || "."}/ \u2014 ` + (configuredBrand.path ? "from jig.config.json." : priorBrand ? "the layout this project already had. Set `brand` in jig.config.json to move it." : findWireTarget(detection) ? "beside the stylesheet being wired. Set `brand` in jig.config.json to put it elsewhere." : "no stylesheet found to follow, so the project root. Set `brand` in jig.config.json to move it.")
+  );
+  const initManifest = priorManifest;
   const files = { ...initManifest?.files ?? {} };
   const brandState = fileState(opts.projectRoot, brandAbsPath, brandRelPath, initManifest);
   const configState = fileState(opts.projectRoot, configAbsPath, configRelPath, initManifest);
@@ -3361,7 +3676,7 @@ ${configRelPath} already exists and was not created by 'jig init' (or has been e
     if (configAction !== "written") log(`  ${configRelPath} exists and is not jig-tracked \u2014 leaving it alone (re-run without --yes to refresh).`);
   }
   if (brandAction === "written") {
-    const defaultCssRaw = readFileSync16(join21(opts.packageRoot, "tokens", "brand.default.css"), "utf8");
+    const defaultCssRaw = readFileSync18(join23(opts.packageRoot, "tokens", "brand.default.css"), "utf8");
     const content = renderBrandFile(defaultCssRaw, projectSlug, opts.version, proposal);
     mkdirSync5(dirname6(brandAbsPath), { recursive: true });
     writeFileSync4(brandAbsPath, content, "utf8");
@@ -3376,12 +3691,12 @@ ${configRelPath} already exists and was not created by 'jig init' (or has been e
   } else if (configAction === "merged") {
     let existing = {};
     try {
-      existing = JSON.parse(readFileSync16(configAbsPath, "utf8"));
+      existing = JSON.parse(readFileSync18(configAbsPath, "utf8"));
     } catch {
       existing = {};
     }
     const existingBrand = typeof existing.brand === "string" ? existing.brand : void 0;
-    const brandStillResolves = existingBrand ? existsSync11(join21(opts.projectRoot, ...existingBrand.split("/"))) : false;
+    const brandStillResolves = existingBrand ? existsSync13(join23(opts.projectRoot, ...existingBrand.split("/"))) : false;
     const merged = {
       brand: brandStillResolves ? existingBrand : brandRelPath,
       surfaces: Array.isArray(existing.surfaces) && existing.surfaces.length > 0 ? existing.surfaces : surfaces
@@ -3393,20 +3708,20 @@ ${configRelPath} already exists and was not created by 'jig init' (or has been e
   }
   const effectiveConfig = loadEffectiveConfig(opts.projectRoot, configAbsPath, brandRelPath, surfaces);
   const primaryMode = effectiveConfig.surfaces[0]?.mode ?? "product";
-  const wiringBrandAbsPath = join21(opts.projectRoot, ...effectiveConfig.brand.split("/"));
+  const wiringBrandAbsPath = join23(opts.projectRoot, ...effectiveConfig.brand.split("/"));
   const declaredModes = [...new Set(effectiveConfig.surfaces.map((s) => s.mode))];
   const modeAbsPaths = {};
   for (const mode of declaredModes) {
     const modeFileName = `mode.${mode}.css`;
-    const modeAbsPath2 = join21(opts.projectRoot, ".jig", "tokens", modeFileName);
+    const modeAbsPath2 = join23(opts.projectRoot, ...tokensRelDir, modeFileName);
     modeAbsPaths[mode] = modeAbsPath2;
-    const modeRelPath = relKey(".jig", "tokens", modeFileName);
+    const modeRelPath = relKey(...tokensRelDir, modeFileName);
     const modeState = fileState(opts.projectRoot, modeAbsPath2, modeRelPath, initManifest);
     let modeAction = "written";
     if (modeState.existsOnDisk && !modeState.tracked) modeAction = "skipped-untracked";
     else if (modeState.modified) modeAction = "skipped-edited";
     if (modeAction === "written") {
-      const modeSourceRaw = readFileSync16(join21(opts.packageRoot, "tokens", modeFileName), "utf8");
+      const modeSourceRaw = readFileSync18(join23(opts.packageRoot, "tokens", modeFileName), "utf8");
       const content = vendorHeader(modeFileName, opts.version, "css", null) + modeSourceRaw;
       mkdirSync5(dirname6(modeAbsPath2), { recursive: true });
       writeFileSync4(modeAbsPath2, content, "utf8");
@@ -3416,17 +3731,39 @@ ${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`;
+  for (const mode of declaredModes) {
+    const rel = relKey(...tokensRelDir, barrelFor(mode));
+    const abs = join23(opts.projectRoot, ...tokensRelDir, barrelFor(mode));
+    const state = fileState(opts.projectRoot, abs, rel, initManifest);
+    if (state.existsOnDisk && (!state.tracked || state.modified)) {
+      log(`  ${rel} exists and is not jig-tracked (or has been edited) \u2014 leaving it alone.`);
+      continue;
+    }
+    const content = barrelBody(barrelFor(mode), brandFileOnly, mode, opts.version);
+    mkdirSync5(dirname6(abs), { recursive: true });
+    writeFileSync4(abs, content, "utf8");
+    files[rel] = checksum(content);
+  }
+  if (declaredModes.length > 1) {
+    log("\nOne barrel per surface. Import each at that route's entry point:");
+    for (const surface of effectiveConfig.surfaces) {
+      log(`  '${surface.match}' \u2192 ${relKey(...tokensRelDir, barrelFor(surface.mode))}`);
+    }
+  }
   writeInitManifest(opts.projectRoot, { version: opts.version, modes: declaredModes, files });
   const wireTarget = findWireTarget(detection);
   let wiring;
   if (wireTarget) {
-    const targetAbsDir = dirname6(join21(opts.projectRoot, wireTarget));
-    const brandImport = relativeImportPath(targetAbsDir, wiringBrandAbsPath);
-    const modeImport = relativeImportPath(targetAbsDir, modeAbsPath);
-    const snippet = `@import "${brandImport}";
-@import "${modeImport}";`;
+    const targetAbsDir = dirname6(join23(opts.projectRoot, wireTarget));
+    const barrelImport = relativeImportPath(
+      targetAbsDir,
+      join23(opts.projectRoot, ...tokensRelDir, "theme.css")
+    );
+    const snippet = `@import "${barrelImport}";`;
     try {
-      const outcome = wireImport(join21(opts.projectRoot, wireTarget), brandImport, modeImport, primaryMode);
+      const outcome = wireBarrel(join23(opts.projectRoot, wireTarget), barrelImport);
       wiring = { target: wireTarget, status: outcome.status, snippet };
       const verb = outcome.status === "wired" ? "Wired" : outcome.status === "rewired" ? "Rewired" : "Already present in";
       log(`
@@ -3451,7 +3788,7 @@ Could not write to ${wireTarget}: ${err.message}`);
     if (pasteTargets.length > 0) {
       log("Paste the block for whichever of these is your global stylesheet:");
       for (const target of pasteTargets) {
-        const dir = dirname6(join21(opts.projectRoot, target));
+        const dir = dirname6(join23(opts.projectRoot, target));
         const forTarget = `@import "${relativeImportPath(dir, wiringBrandAbsPath)}";
 @import "${relativeImportPath(dir, modeAbsPath)}";`;
         log(`
@@ -3492,7 +3829,7 @@ Could not write to ${wireTarget}: ${err.message}`);
 
 // src/index.ts
 var packageRoot = getPackageRoot();
-var { version } = JSON.parse(readFileSync17(join22(packageRoot, "package.json"), "utf8"));
+var { version } = JSON.parse(readFileSync19(join24(packageRoot, "package.json"), "utf8"));
 function warnIfUnpublishedPin() {
   if (isPublishedBuild(packageRoot)) return;
   console.warn(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jig-ui",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "A design system for coding agents. 104 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

@@ -380,14 +380,43 @@ In dark, elevated surfaces get **lighter**, not shadowed. Border-led elevation s
 }
 ```
 
-**Tailwind v4** — wrap the same files, nothing else changes
+**Tailwind v4** — wrap the barrel, nothing else changes
 ```css
 @import "tailwindcss";
 @theme {
-  @import ".jig/tokens/brand.default.css";
-  @import ".jig/tokens/mode.product.css";
+  @import "./jig/theme.css";
 }
 ```
 Yields `bg-surface`, `rounded-surface`, `p-card`, `text-body` as utilities.
 
-**Multiple modes in one app** — scope by route, not by class. Each surface loads its own mode file at the layout or entry level. Do not attempt to nest two modes in one document (`01-modes.md`, seam rules).
+**In a monorepo, add `@source` for every workspace package that uses these
+utilities.** Tailwind v4's content detection does not cross package boundaries:
+a package reached through a `node_modules` symlink is skipped by design, so a
+utility used *only* inside `packages/ui` is never generated.
+
+```css
+@source "../../../../packages/ui/src";
+```
+
+The failure mode is the reason this is worth stating. Nothing errors — the
+class lands on the element and no rule exists to match it, so the style simply
+does not apply. Most utilities survive by coincidence, because the app happens
+to use the same ones; the ones that do not are whatever only the shared package
+uses, which tends to be its theme and state handling. Observed in a real
+project as a theme switch that had silently never worked.
+
+**One import per surface, through a barrel.** `init` writes `jig/theme.css`,
+which imports the brand file and then one mode file, and wires that single line
+into your stylesheet. Your stylesheet then never changes again: switching the
+mode in `jig.config.json` rewrites the barrel, not your CSS.
+
+A barrel holds exactly **one** mode, never a merge. The three mode files declare
+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).

package/templates/COMMAND.md.tmpl

@@ -11,14 +11,42 @@ output — findings are ordered by severity, not position, so `head`, `tail`,
 
 ## init
 
-Report what it detected, the brand colour it derived and where that came from,
-and the mode it wrote. The mode is the load-bearing decision: `jig.config.json`
-outranks your own inference from then on, so if the project's signals point
-elsewhere — the mode table in `{{rules_path}}/01-modes.md` — say so and ask
-before leaving it.
-
-If the token layer does not exist yet, this is the command that creates it. Do
-not author token values yourself under any circumstances.
+**Settle the surfaces before you run it.** Mode is the most consequential thing
+`init` writes and the thing it is worst at choosing: with `--yes` it takes
+`'/' → product` without reading the project at all, and `{{rules_path}}/01-modes.md`
+rule 1 then makes that config outrank your own reading of the project from then
+on. A default chosen in a second binds the project indefinitely, and density is
+expensive to reverse.
+
+You are the half that can fix this, because you are talking to someone who knows
+the answer and the CLI is not. So, first:
+
+1. **Ask what the product is**, in their words rather than Jig's — a marketing
+   or content site, a signed-in application, an internal tool people use all
+   day? A project usually has more than one of these, and each is a surface.
+2. **Map each to a mode** using the table in `{{rules_path}}/01-modes.md`:
+   `editorial` for first-visit content, `product` for the signed-in app,
+   `operator` for dense daily tools. State the mapping in one line and let them
+   correct it.
+3. **Write `jig.config.json`** with those surfaces before running anything.
+   `init` reads an existing config and honours it — writing one mode file per
+   declared mode — so this is how a decision reaches the tokens.
+4. **Then run the command.**
+
+Where there is genuinely one surface, say so and move on; the point is that the
+mode was chosen rather than defaulted into.
+
+Afterwards, report what it detected, the brand colour it derived and where that
+came from, and the surfaces it used — the output says whether they came from
+`jig.config.json` or from the default.
+
+If the token layer does not exist yet, this is the command that creates it. **Do
+not author token values yourself.** `init` derives the brand colour, checks it
+against the contrast floor in both light and dark, and records a checksum for
+each file it writes; a file you write by hand is untracked, so `jig update` can
+never refresh it again. `jig check` now reads the token layer back and holds it
+to those floors either way, so a hand-written value will be caught — but caught
+late, and unmaintainable, is worse than derived.
 
 ## check