jig-ui 0.7.1 → 0.8.0

package/README.md

@@ -75,25 +75,63 @@ skill.
 npx jig-ui@latest init
 ```
 
-`init` is the only command that writes into your repo. It detects your CSS
-system (Tailwind v4, Tailwind v3, plain CSS), derives a brand colour from what
-your project already has — custom properties first, then a Tailwind config, then
-the most frequent literal colour — rather than interviewing you cold, validates
-that colour against the contrast and collision requirements in Jig's own brand
-file, writes the token files, wires the `@import`s into your stylesheet when
-there is one unambiguous place for them, and runs a baseline `check` so you have
-a number to move.
+`init` is the only command that writes into your repo. It runs on a project
+with nothing in it and on one with years of CSS, and behaves differently in
+each — because the useful thing to do differs.
 
-A single-mode project ends up with four files, all of them yours:
+### An existing site
+
+`init` reads what you already have. It detects the CSS system (Tailwind v4,
+Tailwind v3, plain CSS), derives a brand colour from the project rather than
+interviewing you cold — custom properties first, then a Tailwind config, then
+the most frequent literal colour — and validates that colour against the
+contrast and collision requirements in Jig's own brand file. It puts the token
+layer **beside the stylesheet it wires**, and adds one import to it:
 
 ```
+src/styles/app.css          ← @import "./jig/theme.css"; added at the top
+src/styles/jig/
+  brand.<project>.css       your identity, edit freely
+  mode.<mode>.css           a copy of Jig's mode file, refreshed by `update`
+  theme.css                 the barrel: brand + mode, in order
 jig.config.json             route → mode map
-.jig/
-  state.json                bookkeeping — version, modes in use, checksums
-  tokens/
-    brand.<project>.css     your identity, edit freely
-    <mode>.css              a copy of Jig's mode file, refreshed by `update`
+.jig/state.json             bookkeeping — version, modes, checksums
+```
+
+Nothing you wrote is touched beyond that one import line. Re-running `init`
+never overwrites a config or brand file you have edited.
+
+### A brand-new site
+
+There is no CSS to read, so there is nothing to derive from and nowhere obvious
+to wire. `init` says so rather than guessing:
+
 ```
+Detected: unknown
+Token layer: jig/ — no stylesheet found to follow, so the project root.
+Could not find a single unambiguous stylesheet to wire the import into.
+Add this near the top of your global stylesheet:
+  @import "./jig/theme.css";
+```
+
+The brand colour resolves to the unbranded near-black default, which ships a
+coherent monochrome UI and makes the missing decision visible instead of
+inventing a purple (`A-01`). Set `--brand-h/-s/-l` in the brand file when you
+have decided, or tell your agent to ask you.
+
+Add `--yes` to accept every derived default non-interactively — the mode CI and
+agents run in.
+
+### Where the token layer goes
+
+Beside the stylesheet it wires, so it sits with the rest of your CSS rather than
+in a dotfolder next to your lockfile. `src/styles/jig/` in a project whose CSS
+lives in `src/styles/`, `app/assets/stylesheets/jig/` in a Rails app, `jig/` at
+the root when there is no stylesheet to follow. `init` prints the path it chose.
+
+Set `brand` in `jig.config.json` to put it somewhere else. Projects set up
+before 0.7.0 keep their `.jig/tokens/` layout; `update` does not move them, and
+`init` offers to.
 
 The mode file is the one thing genuinely copied: a stylesheet `@import` is an
 edge in a build graph and has to resolve locally, on every machine that builds.
@@ -143,7 +181,7 @@ on the result — the CLI reports, the agent applies the judgment half.
 | Slash command | Equivalent |
 | --- | --- |
 | `/jig init` | `jig init` — then states the mode it chose and what it wired |
-| `/jig check` | `jig check` — then applies the 97 judgment rules and reports both halves |
+| `/jig check` | `jig check` — then applies the 94 judgment rules and reports both halves |
 | `/jig explain C-19` | `jig explain C-19` — prints the rule as-is, without paraphrasing it |
 | `/jig explain contrast` | `jig explain contrast` — every rule matching a word, when you do not have an id |
 | `/jig install --agent cursor` | `jig install --agent cursor` |
@@ -224,7 +262,7 @@ In CI:
 code — nothing model-dependent, no network. As a pre-commit hook, plain `check`
 looks at changed files only.
 
-What you will not get from the CLI alone is the other 97 rules. `check` says so
+What you will not get from the CLI alone is the other 94 rules. `check` says so
 rather than letting a narrow pass read as a broad one.
 
 ## What `check` covers
@@ -251,7 +289,7 @@ 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
+**It also reads the token layer itself.** The token layer 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
@@ -298,8 +336,9 @@ treatment.
 | `rules/03-patterns.md` | Component anatomy and behaviour |
 | `rules/04-principles.md` | Five frames + seven tiebreakers |
 | `rules/05-copy.md` | Interface text rules |
-| `.jig/tokens/brand.*.css` | Identity. One per project. |
-| `.jig/tokens/mode.*.css` | Density, scale, rhythm, motion |
+| `<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. |
 
 `rules/*` and `rules.index.json` live beside your installed skill file, not
 in the project — see above.
@@ -314,7 +353,8 @@ Drop this in the project root so mode selection does not require asking on every
 // jig.config.json
 {
   // 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/`.
+  // the mode files beside it. Omit it and the layer follows your own
+  // layout — beside the stylesheet init wires, or the project root.
   "brand": "src/styles/jig/brand.acme.css",
 
   // One entry per surface. This outranks an agent's own reading of the
@@ -346,12 +386,56 @@ Without this file, follow the selection procedure in `rules/01-modes.md`: infer,
 
 ## Consuming tokens
 
+### Plain CSS, any framework
+
+One import, the barrel:
+
 ```css
-@import ".jig/tokens/brand.acme.css";   /* one per project */
-@import ".jig/tokens/mode.product.css"; /* one per surface  */
+@import "./jig/theme.css";
 ```
 
-Then `var(--color-text-strong)`, `var(--spacing-card)`, `var(--text-body)` in any framework. For Tailwind v4, wrap both imports in `@theme` to generate utilities. See `rules/02-tokens.md`.
+Then `var(--color-text-strong)`, `var(--spacing-card)`, `var(--text-body)`
+anywhere — plain CSS, CSS modules, styled-components, Vue, Svelte, Rails. They
+are ordinary custom properties and nothing takes a dependency on anything.
+
+### Tailwind v4
+
+The same import. Jig needs nothing from Tailwind and Tailwind needs nothing from
+Jig:
+
+```css
+@import "tailwindcss";
+@import "./jig/theme.css";
+```
+
+That is what `init` wires, and it is enough. Every token is readable as
+`var(--color-text-strong)` from any component.
+
+**Optionally**, Tailwind can also generate utility classes from the tokens —
+`p-card`, `rounded-surface`, `text-text-strong`. It only does that for names
+declared in a `@theme` block, so `init` offers to generate one:
+
+```css
+@import "tailwindcss";
+@import "./jig/utilities.css";   /* the generated @theme block */
+```
+
+`init` asks before writing it, because it changes how every component in the
+project is written and both styles are correct. Under `--yes` it declines and
+tells you how to get it.
+
+One set of utilities serves every mode: the utility references the variable
+rather than a resolved value, so whichever mode barrel a route loaded supplies
+it. No `dark:` variants, nothing per-mode.
+
+**Do not nest the import inside `@theme`.** Tailwind rejects it — *"@theme
+blocks must only contain custom properties or @keyframes"* — and Jig's tokens
+cannot move into one regardless, since they live in `:root` and are redeclared
+under `[data-theme="dark"]` and a `prefers-color-scheme` query. That structure
+is what makes dark mode work.
+
+Full detail, including why a duplicate declaration in the compiled CSS is
+correct and must not be "fixed": `rules/02-tokens.md`.
 
 ---
 

package/dist/index.js

@@ -1013,15 +1013,26 @@ function parseRules(markdown, sourceFile) {
         title,
         wrong: "",
         correction: "",
+        notes: [],
+        preamble: [],
         source: `${sourceFile}#${id.toLowerCase()}`
       };
       continue;
     }
     if (!current) continue;
+    if (line.startsWith("#")) {
+      push();
+      current = null;
+      continue;
+    }
     if (line.startsWith("\u274C") && !current.wrong) {
       current.wrong = line.slice(1).trim();
     } else if (line.startsWith("\u2705") && !current.correction) {
       current.correction = line.slice(1).trim();
+    } else {
+      const text = line.trim();
+      if (!text || /^-{3,}$/.test(text)) continue;
+      (current.correction ? current.notes : current.preamble).push(text);
     }
   }
   push();
@@ -1140,8 +1151,16 @@ function renderRule(rule) {
   return [
     `${rule.id}  ${rule.title}`,
     "",
+    // Source order: what the rule leads with comes first. C-49's table sets up
+    // the distinction its pair then relies on, and reading them the other way
+    // round is reading the answer before the question.
+    ...rule.preamble.length > 0 ? [...rule.preamble, ""] : [],
     `\u274C ${rule.wrong}`,
     `\u2705 ${rule.correction}`,
+    // The reasoning, where the rule carries any. This was dropped at the parser
+    // for three releases, so `explain` showed the pair and none of the argument
+    // for it — which is the half that tells you when the rule does not apply.
+    ...rule.notes.length > 0 ? ["", ...rule.notes] : [],
     "",
     `   ${rule.bucket} \xB7 ${rule.severity}${rule.detector ? ` \xB7 detector: ${rule.detector}` : ""}`,
     `   since ${rule.since} \xB7 ${rule.source}`
@@ -1410,7 +1429,9 @@ function formatReport(findings, meta) {
     }
     lines.push("");
   } else {
-    lines.push("  No findings.");
+    lines.push(
+      meta.withStyles === 0 && meta.scanned !== void 0 ? "  Nothing inspected." : "  No findings."
+    );
     lines.push("");
     if (meta.noTokenLayer) {
       lines.push("  No file references a Jig token, so H-47 (hard-coded values) was not run.");
@@ -1426,7 +1447,14 @@ function formatReport(findings, meta) {
   if (notes > 0) summaryParts.push(plural(notes, "note"));
   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`);
+  const examined = meta.scanned === void 0 ? "" : ` \xB7 ${plural(meta.scanned, "file")}, ${meta.withStyles ?? 0} with styles`;
+  lines.push(`  ${summaryParts.join(", ")} \xB7 ${scope}${examined}, ${rulesFired} fired`);
+  if (meta.scanned !== void 0 && meta.withStyles === 0) {
+    lines.push("");
+    lines.push(
+      `  No file carried a style region, so the detectors examined nothing. This is not a pass \u2014 a project with no styling and a project with clean styling report the same findings, and only one of them has been checked.`
+    );
+  }
   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:`);
@@ -1448,7 +1476,7 @@ function formatReport(findings, meta) {
   const mechanicalErrors = findings.filter((f) => f.bucket === "mechanical" && f.severity === "error").length;
   const mechStatus = `${mechanicalErrors > 0 ? "fail" : "pass"}:${mechanicalErrors}`;
   lines.push(
-    `  JIG_CHECK: version=${meta.version} mode=${meta.mode ?? "unknown"} mechanical=${mechStatus} judgment=not-run`
+    `  JIG_CHECK: version=${meta.version} mode=${meta.mode ?? "unknown"} mechanical=${mechStatus} judgment=not-run files=${meta.scanned ?? "unknown"} styled=${meta.withStyles ?? "unknown"}`
   );
   return lines.join("\n");
 }
@@ -1622,7 +1650,7 @@ function splitRuleBlocks(source) {
 }
 function blankNested(body) {
   const out = body.split("");
-  const blank2 = (from, to) => {
+  const blank3 = (from, to) => {
     for (let j = from; j < to; j++) if (out[j] !== "\n") out[j] = " ";
   };
   let depth = 0;
@@ -1630,7 +1658,7 @@ function blankNested(body) {
   for (let i = 0; i < body.length; i++) {
     const ch = body[i];
     if (ch === "{") {
-      if (depth === 0) blank2(segmentStart, i);
+      if (depth === 0) blank3(segmentStart, i);
       depth++;
       out[i] = " ";
     } else if (ch === "}") {
@@ -1940,6 +1968,126 @@ var gradientText = {
   }
 };
 
+// src/check/detectors/text-scan.ts
+var blank2 = (m) => m.replace(/[^\n]/g, " ");
+function maskProseComments(raw) {
+  return raw.replace(/\/\*[\s\S]*?\*\//g, blank2).replace(/<!--[\s\S]*?-->/g, blank2).replace(/(^|[^:@\w])\/\/[^\n]*/g, (m, lead) => lead + blank2(m.slice(lead.length)));
+}
+
+// src/check/detectors/emoji-icon.ts
+var EMOJI_RE = /[\u{1F300}-\u{1FAFF}\u{1F000}-\u{1F2FF}\u{2600}-\u{27BF}\u{2B00}-\u{2BFF}\u{FE0F}]/gu;
+var TEXTUAL = /* @__PURE__ */ new Set(["\u2192", "\u2190", "\u2191", "\u2193", "\u2194", "\u21D2", "\u21D0", "\u2122", "\u2713", "\u2717", "\u2212", "\u2217", "\u2318", "\u2325", "\u23CE"]);
+var emojiIcon = {
+  name: "emoji-icon",
+  appliesTo: (file) => isStyleBearing(file),
+  run(_source, file, ctx) {
+    const findings = [];
+    const masked = maskProseComments(ctx.raw);
+    const lines = masked.split("\n");
+    const seen = /* @__PURE__ */ new Set();
+    for (const m of masked.matchAll(EMOJI_RE)) {
+      if (TEXTUAL.has(m[0])) continue;
+      const line = masked.slice(0, m.index).split("\n").length;
+      if (seen.has(line)) continue;
+      seen.add(line);
+      findings.push(
+        mkFinding(
+          ctx,
+          "emoji-icon",
+          file,
+          line,
+          `Emoji used as interface iconography (${m[0]}). Emoji render differently on every platform, carry no consistent weight or colour, and cannot be styled \u2014 use an icon set, or words.`,
+          lines[line - 1] ?? ""
+        )
+      );
+    }
+    return findings;
+  }
+};
+
+// src/check/detectors/marketing-voice.ts
+var PHRASES = [
+  "supercharge",
+  "unleash",
+  "revolutioni",
+  "game-chang",
+  "effortlessly",
+  "seamlessly",
+  "blazing fast",
+  "take it to the next level",
+  "unlock the power",
+  "elevate your",
+  "transform your workflow",
+  "delight your users"
+];
+var RE = new RegExp(`\\b(${PHRASES.join("|")})`, "gi");
+var APPLIES_IN = /* @__PURE__ */ new Set(["product", "operator"]);
+var marketingVoice = {
+  name: "marketing-voice",
+  appliesTo: (file) => isStyleBearing(file),
+  run(_source, file, ctx) {
+    if (!ctx.mode || !APPLIES_IN.has(ctx.mode)) return [];
+    const findings = [];
+    const masked = maskProseComments(ctx.raw);
+    const lines = masked.split("\n");
+    const seen = /* @__PURE__ */ new Set();
+    for (const m of masked.matchAll(RE)) {
+      const line = masked.slice(0, m.index).split("\n").length;
+      if (seen.has(line)) continue;
+      seen.add(line);
+      findings.push(
+        mkFinding(
+          ctx,
+          "marketing-voice",
+          file,
+          line,
+          `Marketing voice in a \`${ctx.mode}\` surface ("${m[0]}"). Someone using this every day wants to know what it does, not how it feels.`,
+          lines[line - 1] ?? ""
+        )
+      );
+    }
+    return findings;
+  }
+};
+
+// src/check/detectors/placeholder-content.ts
+var PATTERNS = [
+  { re: /\blorem\s+ipsum\b/gi, what: "lorem ipsum" },
+  { re: /https?:\/\/(?:www\.)?example\.(?:com|org|net)\b/gi, what: "an example.com URL" },
+  { re: /\b(?:someone|user|test|foo|bar)@example\.(?:com|org|net)\b/gi, what: "a placeholder email" },
+  { re: /\bAcme\s+(?:Inc\.?|Corp\.?|Co\.?|Ltd\.?|LLC|Company)\b/gi, what: "a placeholder company" },
+  { re: /\byour\s+(?:company|brand|product)\s+name\b/gi, what: "a placeholder name" }
+];
+var placeholderContent = {
+  name: "placeholder-content",
+  appliesTo: (file) => isStyleBearing(file),
+  run(_source, file, ctx) {
+    const findings = [];
+    const masked = maskProseComments(ctx.raw);
+    const lines = masked.split("\n");
+    const seen = /* @__PURE__ */ new Set();
+    for (const { re, what } of PATTERNS) {
+      re.lastIndex = 0;
+      for (const m of masked.matchAll(re)) {
+        const line = masked.slice(0, m.index).split("\n").length;
+        if (seen.has(line)) continue;
+        seen.add(line);
+        findings.push(
+          mkFinding(
+            ctx,
+            "placeholder-content",
+            file,
+            line,
+            `Placeholder content shipped \u2014 ${what} ("${m[0]}"). Real content changes layout: names are longer, copy wraps, images are the wrong ratio.`,
+            lines[line - 1] ?? ""
+          )
+        );
+      }
+    }
+    return findings;
+  }
+};
+
 // src/check/color.ts
 var NAMED = {
   white: { r: 255, g: 255, b: 255 },
@@ -2596,6 +2744,9 @@ var violetBandHue = {
 // src/check/registry.ts
 var DETECTORS = [
   gradientText,
+  emojiIcon,
+  marketingVoice,
+  placeholderContent,
   backdropBlur,
   pureBlackWhite,
   contrastFloor,
@@ -2608,7 +2759,7 @@ function getDetector(name) {
 }
 
 // src/check/run.ts
-function runChecks(projectRoot, files, index, tokens, bucketFilter, projectParticipates = false) {
+function runChecks(projectRoot, files, index, tokens, bucketFilter, projectParticipates = false, mode) {
   const findings = [];
   const active = index.filter(
     (e) => !!e.detector && !!getDetector(e.detector)
@@ -2626,7 +2777,7 @@ function runChecks(projectRoot, files, index, tokens, bucketFilter, projectParti
     }
     const source = maskComments(maskNonStyleRegions(raw, file));
     for (const { entry, detector } of applicable) {
-      const ctx = { ruleId: entry.id, bucket: entry.bucket, severity: entry.severity, tokens, projectParticipates, raw };
+      const ctx = { ruleId: entry.id, bucket: entry.bucket, severity: entry.severity, tokens, projectParticipates, raw, mode };
       findings.push(...detector.run(source, file, ctx));
     }
   }
@@ -2927,7 +3078,16 @@ function check(opts) {
       return false;
     }
   });
-  const findings = runChecks(opts.projectRoot, files, index, tokens, bucketFilter, projectParticipates);
+  const withStyles = files.filter((f) => {
+    try {
+      const src = readFileSync14(join19(opts.projectRoot, f), "utf8");
+      return hasExtension(f, CSS_EXTENSIONS) ? src.trim().length > 0 : maskNonStyleRegions(src, f).trim().length > 0;
+    } catch {
+      return false;
+    }
+  }).length;
+  const resolvedMode = resolveMode(opts.projectRoot);
+  const findings = runChecks(opts.projectRoot, files, index, tokens, bucketFilter, projectParticipates, resolvedMode);
   const TOKEN_RULE = {
     "--text-prose": "B-75",
     "--size-touch-target": "E-51"
@@ -2966,8 +3126,10 @@ function check(opts) {
     totalSpecs: countSpecs(),
     version: opts.version,
     noTokenLayer,
-    mode: resolveMode(opts.projectRoot),
+    mode: resolvedMode,
     unscanned: summariseUnscanned(files),
+    scanned: files.length,
+    withStyles,
     exempt,
     exemptPatterns: byPattern
   });
@@ -3365,6 +3527,77 @@ function deriveProjectSlug(projectRoot) {
   return slugify(basename(projectRoot));
 }
 
+// src/init/utilities.ts
+var TAILWIND_NAMESPACES = [
+  "--color-",
+  "--font-",
+  "--text-",
+  "--font-weight-",
+  "--tracking-",
+  "--leading-",
+  "--breakpoint-",
+  "--container-",
+  "--spacing-",
+  "--radius-",
+  "--shadow-",
+  "--inset-shadow-",
+  "--drop-shadow-",
+  "--blur-",
+  "--perspective-",
+  "--aspect-",
+  "--ease-",
+  "--animate-"
+];
+function tailwindNamespaced(names) {
+  const kept = names.filter((n) => TAILWIND_NAMESPACES.some((ns) => n.startsWith(ns)));
+  return [...new Set(kept)].sort();
+}
+function declaredTokenNames(css) {
+  return [...css.matchAll(/(^|[;{\s])(--[\w-]+)\s*:/g)].map((m) => m[2]);
+}
+function utilitiesBody(names, version2) {
+  if (names.length === 0) {
+    throw new Error(
+      "Refusing to write an empty @theme block: it generates no utilities while looking like it should. No token in this layer matches a Tailwind namespace."
+    );
+  }
+  const width = Math.max(...names.map((n) => n.length));
+  const lines = names.map((n) => `  ${n}:${" ".repeat(width - n.length)} var(${n});`);
+  return `/* utilities.css \u2014 vendored from Jig v${version2}.
+   Licensed Apache-2.0. LICENSE and NOTICE ship beside the jig skill.
+
+   Exposes the token layer to Tailwind v4 as utility classes: \`p-card\`,
+   \`rounded-surface\`, \`text-text-strong\`. ONE per project, never one per mode \u2014
+   the utility references the variable rather than a resolved value, so whichever
+   mode barrel a route loads supplies it. One set of utilities serves every mode.
+
+   Import this once, in the stylesheet that imports Tailwind:
+
+     @import "tailwindcss";
+     @import "./utilities.css";
+
+   YOU WILL SEE A DUPLICATE IN THE COMPILED CSS. That is correct:
+
+     @layer theme { :root,:host { --radius-surface: var(--radius-surface) } }
+     :root { --radius-surface: var(--radius-md) }
+
+   The first is Tailwind's, inside \`@layer theme\`. The second is Jig's, unlayered.
+   Unlayered declarations beat layered ones in the cascade regardless of source
+   order, so Jig's value always wins. Do not "fix" it \u2014 deleting the alias
+   removes the utility, deleting Jig's removes the value.
+
+   Only tokens in a Tailwind namespace are listed. \`--size-*\`, \`--measure-*\`,
+   \`--focus-ring-*\` and \`--border-width-*\` have none, so they stay \`var()\`-only.
+
+   Regenerate with \`jig init\` after the token layer changes; a token missing here
+   is a class that renders and matches nothing. */
+
+@theme inline {
+${lines.join("\n")}
+}
+`;
+}
+
 // src/commands/init.ts
 var MODES = ["editorial", "product", "operator"];
 var DEFAULT_SURFACES = [{ match: "/", mode: "product" }];
@@ -3780,6 +4013,56 @@ ${configRelPath} already exists and was not created by 'jig init' (or has been e
     writeFileSync4(abs, content, "utf8");
     files[rel] = checksum(content);
   }
+  if (detection.cssSystem === "tailwind-v4") {
+    const declared = declaredTokenNames(
+      [brandAbsPath, modeAbsPath].map((f) => {
+        try {
+          return readFileSync18(f, "utf8");
+        } catch {
+          return "";
+        }
+      }).join("\n")
+    );
+    const aliasable = tailwindNamespaced(declared);
+    const rel = relKey(...tokensRelDir, "utilities.css");
+    if (aliasable.length === 0) {
+      log(`
+  Tailwind v4 detected, but no token here matches a Tailwind namespace \u2014 skipping ${rel}.`);
+    } else if (opts.yes) {
+      log(`
+  Tailwind v4 detected. Utility classes (\`p-card\`, \`rounded-surface\`) are`);
+      log(`  available but not set up: re-run without --yes to be offered ${rel},`);
+      log(`  or see "Optional: Tailwind utility classes" in 02-tokens.md.`);
+    } else {
+      log(`
+  Tailwind v4 detected. Jig works as-is \u2014 every token reads as`);
+      log(`  var(--color-text-strong) from any component, and nothing further is needed.`);
+      log(`  Optionally, ${aliasable.length} tokens can also become utility classes`);
+      log(`  (\`p-card\`, \`rounded-surface\`, \`text-text-strong\`) via ${rel}.`);
+      log(`  This changes how components are written. Both styles are correct.`);
+      const answer = (await prompt("  Generate it? [y/N]: ")).toLowerCase();
+      if (answer === "y" || answer === "yes") {
+        const abs = join23(opts.projectRoot, ...tokensRelDir, "utilities.css");
+        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.`);
+        } else {
+          const content = utilitiesBody(aliasable, opts.version);
+          mkdirSync5(dirname6(abs), { recursive: true });
+          writeFileSync4(abs, content, "utf8");
+          files[rel] = checksum(content);
+          const target = findWireTarget(detection);
+          const importPath = target ? relativeImportPath(
+            dirname6(join23(opts.projectRoot, target)),
+            join23(opts.projectRoot, ...tokensRelDir, "utilities.css")
+          ) : `./${rel}`;
+          log(`  Wrote ${rel}. Import it in the stylesheet that imports Tailwind:`);
+          log(`    @import "tailwindcss";`);
+          log(`    @import "${importPath}";`);
+        }
+      }
+    }
+  }
   if (declaredModes.length > 1) {
     log("\nOne barrel per surface. Import each at that route's entry point:");
     for (const surface of effectiveConfig.surfaces) {
@@ -3836,10 +4119,11 @@ Could not write to ${wireTarget}: ${err.message}`);
       log(`  ${snippet.split("\n").join("\n  ")}`);
     }
   } else {
-    const brandImport = relativeImportPath(opts.projectRoot, wiringBrandAbsPath);
-    const modeImport = relativeImportPath(opts.projectRoot, modeAbsPath);
-    const snippet = `@import "${brandImport}";
-@import "${modeImport}";`;
+    const barrelImport = relativeImportPath(
+      opts.projectRoot,
+      join23(opts.projectRoot, ...tokensRelDir, "theme.css")
+    );
+    const snippet = `@import "${barrelImport}";`;
     wiring = { target: null, status: "print-only", snippet };
     log("\nCould not find a single unambiguous stylesheet to wire the import into.");
     const pasteTargets = detection.cssFiles.filter((f) => !isCssModule(f));
@@ -3855,7 +4139,7 @@ Could not write to ${wireTarget}: ${err.message}`);
       }
     } else {
       log(
-        "Add this near the top of your global stylesheet. A CSS @import resolves relative to the file it sits in, so these project-root paths need a ../ per directory of depth:"
+        "Add this near the top of your global stylesheet. A CSS @import resolves relative to the file it sits in, so this project-root path needs a ../ per directory of depth:"
       );
       log(`  ${snippet.split("\n").join("\n  ")}`);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jig-ui",
-  "version": "0.7.1",
+  "version": "0.8.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",
@@ -16,7 +16,8 @@
     "rules.index.json",
     "LICENSE",
     "NOTICE",
-    "README.md"
+    "README.md",
+    "CHANGELOG.md"
   ],
   "engines": {
     "node": ">=20"