jig-ui 0.7.1 → 0.8.1

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/01-modes.md

@@ -205,17 +205,3 @@ Per project, one file supplying:
 - **Voice** — sentence case or title case, contraction policy, error-message tone.
 
 Default when no brand is supplied: warm neutral ramp anchored on `--color-bg-base` (`oklch(0.980 0.004 95)`, a warm off-white), no accent, 8px base radius (`--radius-sm`), border-led elevation. Greyscale output plus a stated question beats an invented purple (`A-01`).
-
----
-
-## Notes for the author (not for the agent)
-
-**Decided, not derived.** These numbers are internally consistent and defensible, but several are judgement calls that should be tuned once you have run real work through them: the operator row height, the three section-rhythm values, and the motion durations. Change them in `tokens/mode.*.css`, never at the call site — this file describes them, `02-tokens.md` resolves them, and neither is where they live.
-
-**Where your taste is recorded here:**
-- The zero-JS default in `editorial` — a stronger position than most systems take, and consistent with your writing on JS-dependent forms.
-- Absolute-first timestamps in `operator` — that is the procurement instinct: the record is evidence before it is a convenience.
-- Typed confirmation for destructive operator actions, and no hover-hidden information in all-day tools.
-- Border-led elevation as the unbranded default.
-
-**Open question worth resolving before tokens.** `product` is currently defined as the midpoint of the other two, which is how it earns its place, but it is also the mode that most often needs to lean. A customer dashboard leans editorial; a billing admin screen leans operator. Consider whether `product` needs a documented `dense` variant, or whether such surfaces should simply be declared `operator`. My inclination is the latter — three modes you apply confidently beat five you deliberate over — but it is your call, and it affects how many token sets `02` has to emit.

package/rules/02-tokens.md

@@ -48,7 +48,7 @@ They are the only token format every web framework consumes natively with no bui
 | Consumer | Usage |
 | --- | --- |
 | Plain CSS / any framework | `color: var(--color-text-strong)` |
-| Tailwind v4 | Wrap in `@theme { }` — generates utilities automatically |
+| Tailwind v4 | `@import` the barrel flat, alongside `@import "tailwindcss"` — see [Colour architecture](#colour-architecture). Utility classes are opt-in and need an alias block |
 | CSS-in-JS (styled-components, emotion) | `color: var(--color-text-strong)` inside template literals |
 | Vue / Svelte / Angular | Identical to plain CSS, scoped or global |
 | React inline styles | `style={{ color: 'var(--color-text-strong)' }}` |
@@ -281,7 +281,7 @@ Resist per-component tokens (`--button-bg`). They multiply fast and rarely earn
 
 ## Naming contract
 
-Names align to Tailwind v4's theme namespaces. This is free for other frameworks — they are ordinary custom properties — and means the same file can be wrapped in `@theme` to generate utilities without any framework taking a dependency on Tailwind.
+Names align to Tailwind v4's theme namespaces. This is free for other frameworks — they are ordinary custom properties — and means an alias block can expose any of them as Tailwind utilities without any framework taking a dependency on Tailwind.
 
 | Namespace | Holds | Layer |
 | --- | --- | --- |
@@ -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/03-patterns.md

@@ -510,17 +510,3 @@ Before writing a new component, check whether it is a composite of things that a
 A new pattern earns a place here when it has been built three times. Before then it is a component, not a pattern.
 
 Each entry states: anatomy in order, complete state list, rules that are decidable, and mode variance. If a rule cannot be checked by looking at the output, it belongs in `04-principles.md`.
-
----
-
-## Notes for the author (not for the agent)
-
-**Where your taste is recorded here:**
-- `P-01` — the whole feedback table is a position. Toasts are over-used because they are easy to build and require no layout decisions; treating them as the narrowest case rather than the default is deliberate.
-- `P-03` help-text-before-control. Contested — many systems put it after. Placing it before means it is read before the user commits to typing, which matters more in forms people fill once.
-- `P-04` one-column forms, and the no-JS baseline for the primary action.
-- `P-06` stable row identity, absolute timestamps, no hover-only truncation. The procurement instinct again: the record is evidence before it is a convenience.
-
-**Deliberately absent.** Navigation, cards, tabs, and toasts-as-a-component. Navigation and cards vary too much by project to have decidable rules yet — they would produce prose, not constraints. Add them once you have built enough to see the invariant.
-
-**Worth testing before extending.** These 12 cover most of what generated UI gets wrong. Point an agent at a form and a table with `00`, `01`, `02` and `03` loaded, and compare against the same task with nothing loaded. If `P-03` and `P-05` do not visibly change the output, the rules are not decidable enough and the fix is more specificity, not more patterns.

package/rules/04-principles.md

@@ -138,17 +138,3 @@ An invented accent, a decorative animation, a gradient filling an empty space
 A codebase with one consistent approach is more maintainable than one with a better approach applied to 30% of it. Note the divergence, raise it, change it deliberately as its own work — not silently, mid-task.
 
 **This tiebreaker outranks the other six.** It does not outrank Part 1: a local convention creating a genuine accessibility risk is a defect to raise, not a convention to match.
-
----
-
-## Notes for the author (not for the agent)
-
-**What changed in v0.2.** Part 1 did not exist. The file was adjudicative only — seven tiebreakers that fire when rules collide, with no method for producing a rule not yet written. That meant the system handed an agent 51 known failures and no way to recognise the 52nd. The four frames are that method.
-
-Frame 3 is the most immediately useful, because it is the only idea here that produces a number. Everything else in this system is checked by inspection; interaction cost is checked by counting, which makes it the one principle an agent can be held to objectively.
-
-Frames 1 and 2 are close to reasoning already embedded in `00` — the risk frame is *why* most of those rules exist, and the rationale requirement is the decidability test that let them in. Stating them explicitly means the next rule can be derived rather than remembered.
-
-**Tiebreaker 7 remains the one to argue about**, and now has a stated ceiling: it loses to Frame 1. Without that boundary, "match the codebase" would license inheriting anything.
-
-Tiebreakers 1 and 2 are the same instinct from two directions, and both come from outside software — a document that looks wrong gets marked and filed, never destroyed.

package/rules/05-copy.md

@@ -141,13 +141,3 @@ See `P-01` for *where* the message goes and `F-37` for field-level validation te
 6. Numerals as figures, formatted consistently? (`I-83`)
 7. One word per concept across the whole product? (`I-87`)
 8. Every error saying what happened and what to do next? (`I-90`)
-
----
-
-## Notes for the author (not for the agent)
-
-**Where your taste is recorded here:** the ban on apology words in errors, and `I-90`'s requirement that the heading and button work without the body text. Both come from the same instinct as the rest of the system — the person reading is trying to get something done, and the interface should not make them wade.
-
-`I-87` is the rule most likely to need a project-specific companion. A term list belongs in the brand file's voice section, not here; this rule only says that one must exist and be followed.
-
-Deliberately absent: tone-of-voice guidance beyond plain language. Tone is a brand decision and varies per client, so it belongs in `03-brand.md` when that file exists.

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