jig-ui 0.3.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jig-ui",
-  "version": "0.3.0",
+  "version": "0.4.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",
@@ -12,6 +12,7 @@
     "rules",
     "tokens",
     "templates",
+    "references",
     "rules.index.json",
     "LICENSE",
     "NOTICE",

package/rules/00-anti-patterns.md

@@ -260,7 +260,7 @@ Agents render the happy path. This section exists because that is the single mos
 
 ### E-29 Focus removed without replacement
 ❌ `outline: none` with nothing in its place
-✅ A `:focus-visible` rule with a visible indicator built on `--color-focus`. Never remove the outline without replacing it. This locks out every keyboard user, and it is the most common accessibility failure in generated code.
+✅ A `:focus-visible` rule with a visible indicator built on `--color-focus`, at `--focus-ring-width` with `--focus-ring-offset`. Never remove the outline without replacing it. This locks out every keyboard user, and it is the most common accessibility failure in generated code.
 
 ### E-30 Empty states omitted
 ❌ A table that renders an empty `<tbody>` when there is no data

package/rules/02-tokens.md

@@ -119,6 +119,8 @@ Names align to Tailwind v4's theme namespaces. This is free for other frameworks
 | `--tracking-*` | Letter spacing | mode |
 | `--spacing-*` | Spacing values | mode |
 | `--radius-*` | Corner radii | brand scale, mode selection |
+| `--border-width-*` | Stroke widths | brand options, mode selection |
+| `--focus-ring-*` | Focus indicator geometry | brand — an accessibility floor, so not mode-negotiable |
 | `--shadow-*` | Elevation | brand |
 | `--duration-*`, `--ease-*` | Motion | mode |
 | `--size-*` | Control and row heights | mode |

package/templates/COMMAND.md.tmpl

@@ -0,0 +1,74 @@
+The user invoked `{{command_prefix}}{{args_placeholder}}`. Treat
+`{{args_placeholder}}` as the subcommand and its flags.
+
+Available subcommands: {{subcommand_list}}. If it is empty or is not one of
+these, say so, list them, and stop.
+
+Run the matching CLI command with `{{scripts_path}}`, passing the flags through
+unchanged. Then do the work below for that subcommand. Read the command's full
+output — findings are ordered by severity, not position, so `head`, `tail`,
+`grep` and `jq` drop the ones that matter.
+
+## 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.
+
+## check
+
+The CLI decides the rules a machine can decide. **It is half the review**, and
+its own attestation says `judgment=not-run` to make that explicit.
+
+Do the other half yourself:
+
+1. Load `{{rules_path}}/00-anti-patterns.md` and `{{rules_path}}/05-copy.md`,
+   plus the relevant section of `{{rules_path}}/03-patterns.md` for whatever the
+   changed files build.
+2. Apply the judgment rules to the same files the CLI just scanned.
+3. Merge both halves into **one** report keyed by rule id, ordered by severity —
+   not two lists. A reader should not have to know which half found what.
+4. Run the self-check at the end of `{{rules_path}}/00-anti-patterns.md`.
+
+Then emit the attestation with both halves filled in:
+
+```text
+JIG_CHECK: version=<version> mode=<mode> mechanical=<pass|fail|skipped>:<n> judgment=<ran|skipped>
+```
+
+Take `mechanical=` from the CLI's own line. If `check` could not run, that is
+`mechanical=skipped:0` — never `pass`, which would report a clean result for a
+check that inspected nothing. Report `judgment=ran` only if you did step 2.
+
+## install
+
+Report where the skill landed and at which scope. If it warned that a global
+install already exists, do not work around it — that warning is the system
+refusing to leave two contradictory skills for one harness.
+
+## explain
+
+Print the CLI's output as it stands. It is already the rule's full text — do not
+summarise it, and do not paraphrase the correction into your own words: the
+wording is the rule.
+
+If the id is a `P-` or `M-` spec, the output says it is a specification rather
+than a rule, with no ❌/✅ pair and no detector. That is correct, not a gap.
+
+If the id does not exist, the error names every id in that section. Offer the
+nearest one rather than guessing what the user meant.
+
+## update
+
+Report what moved and what was left alone. Files reported as skipped were edited
+locally and are the user's; never re-apply Jig's version over them.
+
+---
+
+Everything in `{{rules_path}}/` is yours to read. Cite rules by id, and cite any
+rule you deliberately break with the reason, in one line.

package/templates/SKILL.md.tmpl

@@ -3,15 +3,22 @@ cite the number when you follow or deliberately break one.
 
 ## Before generating or reviewing any UI
 
+0. Check that `{{config_file}}` exists. If it does not, this project has no
+   token layer: run `init` and stop until it has been run. Do not proceed by
+   writing token definitions of your own — a `:root` block you author, however
+   clearly you label it, is an invented design system wearing this one's names,
+   and it will not be replaced when the real tokens arrive.
 1. Load `{{rules_path}}/00-anti-patterns.md` and `{{rules_path}}/01-modes.md`.
 2. Determine the mode from `{{config_file}}`, or infer it using the procedure in
    `{{rules_path}}/01-modes.md` and state the inference in one line before building.
 3. Load the relevant section of `{{rules_path}}/03-patterns.md` for the component you are building.
 4. Load `{{rules_path}}/05-copy.md` whenever you write a label, button, heading, error or empty state.
 5. Consume tokens by semantic name only. Never write a raw colour or pixel value
-   at a call site.
-6. Run the self-check at the end of `{{rules_path}}/00-anti-patterns.md` before finishing
-   (a future `check` command will automate this).
+   at a call site, and never resolve a name yourself: if a token you need has no
+   value, that is a finding to report, not a number to supply.
+6. Run `check` for the rules the CLI can detect, then run the self-check at the
+   end of `{{rules_path}}/00-anti-patterns.md` for the rules it cannot. Both
+   halves, every time — a clean `check` is not a clean review.
 7. Cite any rule you deliberately break, with the reason, in one line.
 
 Load `{{rules_path}}/04-principles.md` only when two rules conflict.
@@ -20,9 +27,15 @@ Load `{{rules_path}}/04-principles.md` only when two rules conflict.
 
 {{available_commands}}
 
-Commands marked `available` run via the CLI at `{{scripts_path}}`. Commands
-marked `planned` are listed for context only — running one errors out, since
-it is not yet registered.
+Commands marked `available` run via the CLI at `{{scripts_path}}` — the version
+this skill was installed with, so the CLI and these rules always agree.
+
+`update` is the exception: its job is to move that version forward, so run it
+as `{{update_path}} update`. Run pinned, it refreshes to the version already
+installed and reports success for a no-op.
+
+Commands marked `planned` are listed for context only — running one errors out,
+since it is not yet registered.
 
 ## Reading command output
 
@@ -42,12 +55,14 @@ 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> self_check=<ran|skipped>
+JIG_CHECK: version=<version> mode=<mode> mechanical=<pass|fail|skipped>:<n> judgment=<ran|skipped>
 ```
 
-<!-- `mechanical=<pass|fail>:<n>/<total>` and `judgment=<ran|skipped>` fields
-     belong here once the `check` command lands and can actually produce
-     them — do not add them back before that. -->
+`jig check` emits this same line for the half it can do, with
+`judgment=not-run`. Take `mechanical=` from its output rather than counting by
+hand; fill `judgment=` yourself. If `check` could not run at all, that is
+`mechanical=skipped:0` — never `pass`, which would report a clean result for a
+check that never inspected anything.
 
-A skipped self-check must say `skipped` and give the reason. Do not report
-`ran` for a check you did not perform.
+A skipped check must say `skipped` and give the reason. Do not report `ran` for
+a check you did not perform.

package/templates/command-metadata.json

@@ -15,13 +15,13 @@
     "status": "available"
   },
   "check": {
-    "description": "Check changed files or a named target against the rule set. Reports violations by rule id.",
-    "argumentHint": "[target]",
-    "status": "planned"
+    "description": "Check the repo against the mechanical and hybrid rules the CLI can detect. Reports findings by rule id; the judgment rules remain yours to apply.",
+    "argumentHint": "[--all] [--ci] [--json]",
+    "status": "available"
   },
   "explain": {
-    "description": "Print a rule's full text, its correction, and the version it was introduced in.",
+    "description": "Print a rule's full text, its correction, the version it arrived in, and who checks it. Also resolves the P-/M- pattern and mode specs, which no rule index contains.",
     "argumentHint": "<rule-id>",
-    "status": "planned"
+    "status": "available"
   }
 }

package/tokens/brand.default.css

@@ -99,6 +99,23 @@
 
   --color-focus: var(--color-text-strong);
 
+  /* ---- Stroke widths. Options; modes select. ----
+     Every rule requiring a visible border or focus ring — E-28, E-29, P-02's
+     3:1 shape floor — used to end at a call site writing `1px` or `2px` by
+     hand, which H-47 forbids. Two agents building different components hit
+     that independently and reported the same gap: no semantic name existed to
+     consume. These are it. */
+  --border-width-hairline: 1px;   /* control and surface borders */
+  --border-width-strong:   2px;   /* emphasis, selected states  */
+
+  /* Focus ring geometry. NOT mode-negotiable, for the same reason
+     --size-touch-target is not: WCAG 2.4.11 wants a perimeter at least 2px
+     thick, and density is never a reason to go under an accessibility floor.
+     The offset keeps the ring off the control's own border so both stay
+     legible. */
+  --focus-ring-width:  2px;
+  --focus-ring-offset: 2px;
+
   /* ================= TYPE ================= */
   --font-text:    ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif;
   --font-display: var(--font-text);

package/tokens/mode.editorial.css

@@ -59,6 +59,7 @@
   --size-control: 48px;  --size-control-sm: 40px;
   --size-touch-target: 48px;  --size-icon: 20px;
 
+  --border-width-control: var(--border-width-hairline);
   --radius-control: var(--radius-sm);  --radius-surface: var(--radius-md);
   --shadow-surface: var(--shadow-none);
 

package/tokens/mode.operator.css

@@ -59,6 +59,7 @@
   --size-row: 36px;  --size-row-compact: 32px;
   --size-touch-target: 48px;  --size-icon: 16px;
 
+  --border-width-control: var(--border-width-hairline);
   --radius-control: var(--radius-sm);  --radius-surface: var(--radius-sm);
   --shadow-surface: var(--shadow-none);
 

package/tokens/mode.product.css

@@ -56,6 +56,7 @@
   --size-control: 40px;  --size-control-sm: 32px;  --size-row: 48px;
   --size-touch-target: 48px;  --size-icon: 18px;
 
+  --border-width-control: var(--border-width-hairline);
   --radius-control: var(--radius-sm);  --radius-surface: var(--radius-md);
   --shadow-surface: var(--shadow-none);