jig-ui 0.7.1 → 0.8.0

package/rules/00-anti-patterns.md

@@ -24,6 +24,7 @@ These are the strongest defaults in a model's training data and the fastest way
 ### A-01 Purple and violet as the unspecified default
 ❌ A violet or indigo fill, or a violet→pink gradient, chosen because no colour was specified
 ✅ Use `--color-brand` from the brand file. The unbranded default resolves it to near-black, which ships a coherent monochrome UI and makes the missing decision visible. Then ask.
+**Being asked to propose a colour does not discharge this.** A proposal is a question with a suggested answer, not a decision — so suggest one freely when asked, but ship the unbranded default alongside it and leave the brand file unchanged until a human confirms. Two agents given the same brief split on exactly this point, one deferring and one treating its own proposal as the answer, and both cited the same conflict-resolution clause to get there. The task can ask you for a recommendation; it cannot make you the one who decided.
 
 ### A-02 Gradient text on headings
 ❌ `background-clip: text` with a gradient fill and transparent text colour
@@ -90,6 +91,7 @@ In `operator`, `--radius-surface` also selects `sm`, so cards, buttons and input
 ### B-11 Unbounded line length
 ❌ Paragraphs spanning the full width of a wide viewport
 ✅ Cap at `--measure-prose` (68ch editorial, 60ch product, 72ch operator). Applies to any run of prose in any mode.
+**And do not let a layout choice push it far under.** The readable band is 40–80 characters (`02-tokens.md`); the cap is the only half stated here, so a column can be halved indefinitely and still satisfy this rule while reading worse at every step. A narrow viewport that cannot reach 40 is a constraint and fine. Splitting a capped column into two side-by-side panels, and rendering prose at 41 characters in a mode whose own measure selects 68, is a choice — and it is choosing density over legibility, which is the trade `M-01` says editorial does not make.
 
 ### B-12 Centred or justified body text
 ❌ A centred paragraph of four lines. Justified text of any length.
@@ -503,7 +505,28 @@ Load `05-copy.md` whenever writing or reviewing a user-facing string.
 
 Run this against what you produced. Any "no" is a defect to fix, not a note to mention.
 
-1. Would this look different from a generic template if the accent colour were removed? (A-01 → A-10)
+1. **The generic-AI tells, named rather than gestured at.** This used to read
+   "would this look different from a generic template if the accent colour were
+   removed?", which an agent that has just produced a generic template answers
+   yes to — and its `A-01 → A-10` range silently excluded `A-58`, `A-59`, `A-60`
+   and `A-67`. Check each:
+   - Was the accent colour **chosen**, or did it appear because none was
+     specified? (`A-01`)
+   - Any gradient text, decorative blobs, glassmorphism or neumorphism?
+     (`A-02`, `A-03`, `A-04`)
+   - Emoji standing in for icons — including ones marked `aria-hidden`?
+     (`A-05`)
+   - Three things in a three-column icon-and-heading grid because there were
+     three of them? (`A-06`)
+   - One radius on every element regardless of its size; shadow doing all the
+     depth work? (`A-07`, `A-08`)
+   - Marketing voice in an application, or placeholder content still in place?
+     (`A-09`, `A-10`)
+   - Decoration that mimics a functional signal — colour picked for variety, an
+     icon that looks pressable and is not? (`A-58`)
+   - Every list item restating the context they share? (`A-59`)
+   - Icons at equal weight competing with the text they support? (`A-60`)
+   - A border, card or panel around every group on the page? (`A-67`)
 2. Is every run of prose measure-capped and left-aligned? (B-11, B-12)
 3. Does any text or placeholder fall below 4.5:1? (C-19)
 4. Is every spacing value a `--spacing-*` token, and does `--spacing-heading-before` exceed `--spacing-heading-after`? (D-23, D-24)
@@ -523,16 +546,3 @@ Run this against what you produced. Any "no" is a defect to fix, not a note to m
 9. Does the primary action still work with JavaScript disabled? (F-41)
 10. Is there a `prefers-reduced-motion` path? (G-43)
 11. Did you reuse existing components and tokens rather than adding new ones? (H-45, H-47)
-
----
-
-## Notes for the author (not for the agent)
-
-Rules carrying a deliberate house position rather than a general best practice — these are where your taste is recorded, and they should be defended or changed consciously:
-
-- **C-18** — off-white over pure white. Already evidenced in your site's `#fafaf7`, now the anchor of the default neutral ramp.
-- **A-07, A-08** — bordered, low-radius, low-shadow surfaces. This is a stance, not a consensus.
-- **F-41, G-42** — resilience and restraint weighted above visual richness. Connects directly to your writing on JS-dependent form fields.
-- **D-24** — heading space asymmetry. Universal advice, but stating a ratio makes it enforceable.
-
-Candidates deferred to mode profiles because they are not universal: information density, table row height, use of colour fills for status, page-section rhythm, hero presence, illustration and imagery policy, animation budget.

package/rules/02-tokens.md

@@ -390,14 +390,89 @@ In dark, elevated surfaces get **lighter**, not shadowed. Border-led elevation s
 }
 ```
 
-**Tailwind v4** — wrap the barrel, nothing else changes
+**Tailwind v4** — the barrel is imported flat, exactly as anywhere else
+
+```css
+@import "tailwindcss";
+@import "./jig/theme.css";
+```
+
+That is all that is required, and it is what `init` writes. Every token is
+readable as `var(--color-text-strong)` in any stylesheet or component.
+
+**Do not nest the import inside `@theme`.** Earlier versions of this file told
+you to, and Tailwind rejects it outright:
+
+```
+@theme blocks must only contain custom properties or @keyframes.
+```
+
+`@theme` takes declarations, not an `@import`, and Jig's tokens cannot move into
+one regardless: `@theme` requires them top-level and unnested, while Jig's live
+in `:root` and are redeclared under `[data-theme="dark"]` and a
+`prefers-color-scheme` query. That structure is what makes dark mode work.
+
+### Optional: Tailwind utility classes
+
+The flat import gives you the tokens. It does **not** give you `p-card` or
+`rounded-surface` as classes — Tailwind only generates utilities for names
+declared in `@theme`. If you want them, add one alias block:
+
+```css
+/* jig/utilities.css — one per project, not one per mode */
+@theme inline {
+  --color-text-strong: var(--color-text-strong);
+  --color-bg-base:     var(--color-bg-base);
+  --spacing-card:      var(--spacing-card);
+  --radius-surface:    var(--radius-surface);
+  /* …every token you want as a utility */
+}
+```
+
 ```css
+/* your root stylesheet */
 @import "tailwindcss";
+@import "./jig/utilities.css";
+```
+
+Then `<article class="bg-bg-base p-card rounded-surface">` works, and the value
+still comes from whichever mode barrel that route loaded — so one set of
+utilities serves every mode, with no `dark:` variants and nothing per-mode.
+
+**`@theme` and `@theme inline` behave identically here.** Both generate the
+utilities; both also emit a self-referential declaration you will see in the
+compiled CSS:
+
+```css
+@layer theme { :root, :host { --radius-surface: var(--radius-surface) } }  /* Tailwind's */
+:root { --radius-surface: var(--radius-md) }                              /* Jig's */
+```
+
+**This is not a bug and must not be "fixed".** Tailwind's copy is inside
+`@layer theme`; Jig's is unlayered. Unlayered declarations beat layered ones in
+the cascade regardless of source order, so Jig's value always wins. Removing
+either one breaks something: drop the alias and the utility stops existing, drop
+Jig's and the token has no value.
+
+**The alternative, if the duplicate bothers you:** alias to *different* names,
+the way a project with its own semantic layer would.
+
+```css
 @theme {
-  @import "./jig/theme.css";
+  --color-ink:   var(--color-text-strong);
+  --color-paper: var(--color-bg-base);
 }
 ```
-Yields `bg-surface`, `rounded-surface`, `p-card`, `text-body` as utilities.
+
+Utilities become `text-ink`, `bg-paper`. No self-reference, no duplicate
+declaration, and the names read as yours rather than as Jig's. The cost is a
+mapping to maintain. Both arrangements are correct; this is a naming preference,
+not a correctness one.
+
+**A missing alias fails silently.** A class whose token is not in the block
+renders onto the element and matches no rule — no error, no warning, no style.
+Generate the block rather than hand-maintaining it, and regenerate it when the
+token layer changes.
 
 **In a monorepo, add `@source` for every workspace package that uses these
 utilities.** Tailwind v4's content detection does not cross package boundaries:

package/rules.index.json

@@ -84,9 +84,10 @@
   },
   {
     "id": "A-05",
-    "bucket": "judgment",
-    "severity": "note",
-    "since": "0.1.0"
+    "bucket": "mechanical",
+    "severity": "warning",
+    "since": "0.1.0",
+    "detector": "emoji-icon"
   },
   {
     "id": "A-06",
@@ -108,15 +109,17 @@
   },
   {
     "id": "A-09",
-    "bucket": "judgment",
-    "severity": "note",
-    "since": "0.1.0"
+    "bucket": "mechanical",
+    "severity": "warning",
+    "since": "0.1.0",
+    "detector": "marketing-voice"
   },
   {
     "id": "A-10",
-    "bucket": "judgment",
-    "severity": "note",
-    "since": "0.1.0"
+    "bucket": "mechanical",
+    "severity": "warning",
+    "since": "0.1.0",
+    "detector": "placeholder-content"
   },
   {
     "id": "B-11",

package/templates/SKILL.md.tmpl

@@ -23,6 +23,29 @@ cite the number when you follow or deliberately break one.
 
 Load `{{rules_path}}/04-principles.md` only when two rules conflict.
 
+## If the project uses Tailwind v4
+
+Jig needs nothing from Tailwind and Tailwind needs nothing from Jig: the flat
+`@import` of the token barrel is enough, and every token is readable as
+`var(--color-text-strong)` from any component. Build that way unless the user
+tells you otherwise.
+
+Tailwind can additionally generate utility classes (`p-card`, `rounded-surface`)
+from Jig's tokens, but only if the project declares an alias block. **That is
+the user's decision, not yours.** It changes how every component in the codebase
+is written, and both arrangements are correct — so when you find Tailwind v4 in
+a project without one:
+
+1. Say you found it, and that the token layer works today without any change.
+2. Show them the two arrangements from "Optional: Tailwind utility classes" in
+   `{{rules_path}}/02-tokens.md` — self-referential aliases keeping Jig's names,
+   or aliases to names of their own.
+3. Ask which they want, and **wait**. Do not pick one and proceed.
+
+Never write `@import "tailwindcss"` into a project that does not already have
+it. Jig is framework-agnostic by design, and a token layer that drags in a CSS
+framework has stopped being one.
+
 ## Commands
 
 {{available_commands}}
@@ -55,7 +78,7 @@ changed since, do not re-run it.
 Before you finish a task that generated or modified UI, emit this line:
 
 ```text
-JIG_CHECK: version=<version> mode=<mode> mechanical=<pass|fail|skipped>:<n> judgment=<ran|skipped>
+JIG_CHECK: version=<version> mode=<mode> mechanical=<pass|fail|skipped>:<n> judgment=<ran|skipped> files=<n> styled=<n>
 ```
 
 `jig check` emits this same line for the half it can do, with