jig-ui 0.4.0 → 0.6.0

package/README.md

@@ -116,13 +116,14 @@ overwrites a config or brand file you have edited.
 | `init [--yes]` | Sets the project up: CSS system, brand colour, token files, `jig.config.json`, wired imports, baseline check. The only command that writes into your repo. |
 | `check [--all] [--ci] [--json]` | Runs the rules a machine can decide. Reports findings by rule id. |
 | `update` | Refreshes an install to a newer version, leaving alone any file you have edited. |
-| `explain <rule-id>` | Prints a rule in full — what it forbids, what to do instead, the version it arrived in, and who checks it. Also resolves the `P-` pattern and `M-` mode specs, which no rule index contains. |
+| `explain <rule-id \| word> [--list]` | Given an id, prints a rule in full — what it forbids, what to do instead, the version it arrived in, and who checks it. Also resolves the `P-` pattern and `M-` mode specs, which no rule index contains. Given a **word**, searches every title and body and lists what matches, so you can find a rule you cannot name. `--list` prints every id, or one section's. |
 
 Flags worth knowing:
 
 | Flag | Effect |
 | --- | --- |
 | `check --all` | Scan the whole repo instead of just changed files. Use on a first run. |
+| `explain --list` | Every rule id and title. Add a section letter (`explain G --list`) for one section. |
 | `check --ci` | Mechanical bucket only — deterministic, and exits non-zero on any error. |
 | `check --json` | Machine-readable findings, for tooling or for reading every finding when the terminal output elides repeats. |
 | `init --yes` | Non-interactive; accept every derived default. |
@@ -144,6 +145,7 @@ on the result — the CLI reports, the agent applies the judgment half.
 | `/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 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` |
 | `/jig update` | `jig update` |
 
@@ -179,32 +181,6 @@ any UI, takes the mode from `jig.config.json`, loads the pattern section for
 whatever it is building, consumes tokens by name, and cites any rule it
 deliberately breaks.
 
-### Slash commands
-
-`install` also writes a `/jig` command, so the CLI is reachable without leaving
-your session:
-
-```
-/jig init          /jig check --all          /jig update
-```
-
-It runs the CLI and then does the part the CLI cannot — for `/jig check` that
-means applying the 97 judgment rules to the same files and merging both halves
-into one report keyed by rule id.
-
-| Harness | Command file |
-| --- | --- |
-| Claude Code | `.claude/commands/jig.md` |
-| Cursor | `.cursor/commands/jig.md` |
-| opencode | `.opencode/command/jig.md` |
-| Gemini CLI | `.gemini/commands/jig.toml` |
-| Codex | — run the CLI directly; see below |
-| Generic | — no harness to register with |
-
-Codex's custom prompts are not written: `codex exec` does not expand them, so a
-command file could sit there and never fire. Codex users run
-`npx jig-ui@latest check` directly — the skill in `AGENTS.md` is unaffected.
-
 **You still prompt normally.** Ask for a settings page, a data table, an empty
 state — whatever you were going to ask for. What you no longer have to say is
 *how*: "use the design tokens", "handle the loading state", "don't invent a
@@ -275,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
@@ -301,21 +290,21 @@ treatment.
 
 ## Files
 
-| File | Contents | Load |
-| --- | --- | --- |
-| `rules/00-anti-patterns.md` | 87 universal rules with corrections | **Always** |
-| `rules/01-modes.md` | `editorial` / `product` / `operator` profiles | **Always** |
-| `rules/02-tokens.md` | Token contract, naming, consumption | On setup, or when adding a token |
-| `rules/03-patterns.md` | Component anatomy and behaviour | When building a covered pattern |
-| `rules/04-principles.md` | Five frames + seven tiebreakers | Novel decisions, or rule conflicts |
-| `rules/05-copy.md` | Interface text rules | Writing any user-facing string |
-| `.jig/tokens/brand.*.css` | Identity. One per project. | Imported by the app |
-| `.jig/tokens/mode.*.css` | Density, scale, rhythm, motion | One per surface |
+| File | Contents |
+| --- | --- |
+| `rules/00-anti-patterns.md` | 87 universal rules with corrections |
+| `rules/01-modes.md` | `editorial` / `product` / `operator` profiles |
+| `rules/02-tokens.md` | Token contract, naming, consumption |
+| `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 |
 
 `rules/*` and `rules.index.json` live beside your installed skill file, not
 in the project — see above.
 
-`00` and `01` are the always-loaded core and are sized to stay cheap in context. `03` is the largest file and should be loaded per-pattern rather than wholesale.
+Which of these an agent loads, and when, is `AGENTS.md`.
 
 ## Per-project declaration
 
@@ -324,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/**"]
 }
 ```
 
@@ -344,36 +353,7 @@ Without this file, follow the selection procedure in `rules/01-modes.md`: infer,
 
 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`.
 
-## Testing that the rules work
-
-The system is only worth its context cost if it changes output. Test it rather than assuming.
-
-1. Pick a task with known failure modes — a form with validation, or a data table with an empty state.
-2. Run it twice: once with the system loaded, once without.
-3. Diff the output against the self-check in `00`.
-
-A rule that does not change the output is either already the model's default (delete it) or too vague to act on (make it specific). Both are fixes to this system, not to the prompt.
-
-Re-run after any significant edit to `00` or `03`.
-
-## Changing a rule
-
-- Values change in the token files, never at the call site.
-- Rules change in `00`–`03`, never by exception in a project.
-- A rule that needs an exception in two projects is wrong; fix the rule.
-- Anything mode-dependent belongs in a mode profile, not in `00`.
-- A new pattern earns a place in `03` after being built three times.
-
-## Sources
-
-Written from general UI and accessibility practice, plus the constraints specific to agent-generated output — which is where most of the structure comes from: the anti-patterns-first ordering, the mode split, the brand × mode token architecture, and the decidability test applied to every rule.
-
-**The numeric defaults are being reconciled.** Type scale, spacing steps, control sizes
-and motion durations started as internally consistent guesses and are being checked, row by
-row, against an external reference on interface design. `RECONCILE.md` tracks the status of
-each: adopted, deliberately kept different, or still open. The accessibility floors are
-outside that process — contrast ratios and target sizes come from WCAG 2.1 AA and are not
-adjustable.
+---
 
-principles.design informed the rules-versus-principles split, and the standard
-`rules/04-principles.md` is held to.
+Working on Jig itself rather than with it: `AGENTS.md` for how an agent should
+change the rules, `RECONCILE.md` for where each numeric default came from.