jig-ui 0.3.0 → 0.5.0

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.",
-    "argumentHint": "<rule-id>",
-    "status": "planned"
+    "description": "Explain a rule, or find the rules you cannot name. Given an id, prints the rule's full text, its correction, the version it arrived in and who checks it — including the P-/M- pattern and mode specs, which no rule index contains. Given a word instead, searches every title and body and lists what matches. `--list` prints every id, or one section's.",
+    "argumentHint": "<rule-id | search term> [--list]",
+    "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);
@@ -111,16 +128,33 @@
   --radius-lg:   32px;   /* large surfaces, hero media          */
   --radius-full: 9999px;
 
-  /* ================= ELEVATION — two shadows =================
+  /* ================= ELEVATION — two shadows, plus none =================
      Shadow colour is derived from the text colour, not pure black, so it sits in
-     the palette. Light from above: y-offset positive, blur grows with elevation. */
+     the palette. Light from above: y-offset positive, blur grows with elevation.
+     `--shadow-none` is the explicit absence a mode selects when its elevation is
+     stroke-led; every mode currently does, via `--shadow-surface`. */
   --shadow-none:    none;
   --shadow-raised:  0 1px 2px rgb(0 0 0 / 6%), 0 2px 4px -2px rgb(0 0 0 / 8%);
   --shadow-overlay: 0 4px 16px -4px rgb(0 0 0 / 14%), 0 1px 3px rgb(0 0 0 / 8%);
 }
 
+/* Dark mode has THREE states, and this file needs two blocks to serve them.
+   The media query below covers "the OS says dark", guarded by
+   :not([data-theme="light"]) so an explicit light choice still wins. It does
+   NOT cover "the OS says light and the user chose dark" — a selector inside a
+   media query cannot match when the query is false, so before this second
+   block existed, setting data-theme="dark" on a light-mode system produced no
+   dark tokens at all. The preview's own dark toggle did nothing there, which is
+   why this went unnoticed: dark mode was only ever seen by people whose OS was
+   already in it.
+
+   The two bodies are identical and MUST stay so; check-tokens rule 10 fails the
+   build if they diverge. CSS gives no way to share them — a selector list cannot
+   straddle a media-query boundary — so the duplication is required and the guard
+   is the answer to it. */
 @media (prefers-color-scheme: dark) {
   :root:not([data-theme="light"]) {
+
     /* Three solid levels. In dark, DEPTH COMES FROM BACKGROUND, NOT SHADOW —
        shadows are nearly invisible on a dark surface. Never pure black. */
     --color-bg-base:    hsl(var(--brand-h) 6% 10%);
@@ -150,3 +184,34 @@
     --shadow-overlay: 0 8px 24px -8px rgb(0 0 0 / 60%);
   }
 }
+
+:root[data-theme="dark"] {
+
+    /* Three solid levels. In dark, DEPTH COMES FROM BACKGROUND, NOT SHADOW —
+       shadows are nearly invisible on a dark surface. Never pure black. */
+    --color-bg-base:    hsl(var(--brand-h) 6% 10%);
+    --color-bg-raised:  hsl(var(--brand-h) 6% 15%);
+    --color-bg-overlay: hsl(var(--brand-h) 6% 20%);
+
+    /* Foregrounds become opacities of white. Higher than the light-mode values,
+       because dark interfaces lose detail faster. */
+    --color-text-strong:   rgb(255 255 255 / 100%);
+    --color-text-weak:     rgb(255 255 255 / 78%);
+    --color-stroke-strong: rgb(255 255 255 / 60%);
+    --color-stroke-weak:   rgb(255 255 255 / 12%);
+    --color-fill:          rgb(255 255 255 / 6%);
+
+    --brand-l: 88%;      /* lighten and desaturate the brand for dark surfaces */
+    --color-on-brand: hsl(var(--brand-h) 6% 10%);
+
+    /* System colours lighten and desaturate in dark mode. Only the h/s/l and
+       fill-alpha vars need overriding here — the four hsl() declarations
+       above pick the new values up automatically. */
+    --error-h:   0;   --error-s:   60%; --error-l:   72%; --error-fill-a:   8%;
+    --warning-h: 42;  --warning-s: 70%; --warning-l:  70%; --warning-fill-a: 8%;
+    --success-h: 162; --success-s: 45%; --success-l: 66%; --success-fill-a: 8%;
+    --info-h:    220; --info-s:    55%; --info-l:    74%; --info-fill-a:    8%;
+
+    --shadow-raised:  none;
+    --shadow-overlay: 0 8px 24px -8px rgb(0 0 0 / 60%);
+}

package/tokens/mode.editorial.css

@@ -28,9 +28,27 @@
   --text-body:    16px;  --leading-body:    1.5;    /* UI text: labels, controls */
   --text-prose:   18px;  --leading-prose:   1.6;    /* LONG-FORM text. Never below 18. */
   --text-lead:    20px;  --leading-lead:    1.5;
+
+  /* H1 and H2 are FLUID: they interpolate with viewport width instead of
+     switching at a breakpoint, which is why this system defines no breakpoint
+     token. Each clamp is the line through (360px viewport, min) and (1024px,
+     max); outside that range it saturates at the bounds.
+
+     The `rem` term is not decoration. `clamp(32px, 8vw, 48px)` would ignore a
+     reader who has set a larger default font size — page zoom scales `vw`, a
+     font-size preference does not — which fails WCAG 1.4.4. Keeping every term
+     in `rem` plus `vw` means the whole curve moves with the user's setting.
+
+     Only headings. Body and prose stay fixed: readability is absolute, set by
+     the eye and viewing distance, while heading size is relative — it exists to
+     contrast with body, and that contrast can compress on a narrow screen. A
+     fluid `--text-prose` would also breach the 18px floor (B-75, T20).
+
+     The minimums land on rungs the ladder already has rather than on new
+     values. Line heights are unitless, so they follow the size for free. */
   --text-h3:      24px;  --leading-h3:      1.333;
-  --text-h2:      32px;  --leading-h2:      1.25;
-  --text-h1:      48px;  --leading-h1:      1.1;
+  --text-h2:      clamp(1.5rem, 1.229rem + 1.205vw, 2rem);  --leading-h2: 1.25;   /* 24 → 32 */
+  --text-h1:      clamp(2rem, 1.458rem + 2.41vw, 3rem);     --leading-h1: 1.1;    /* 32 → 48 */
 
   /* Two weights only. More adds noise and is hard to apply consistently. */
   --font-weight-regular: 400;
@@ -59,14 +77,39 @@
   --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);
 
   --duration-fast: 150ms;  --duration-base: 250ms;  --duration-slow: 300ms;
   --ease-out: cubic-bezier(0.16, 1, 0.3, 1);
   --ease-in-out: cubic-bezier(0.65, 0, 0.35, 1);
+
+  /* Ambient motion (P-13). Decorative looping movement, editorial only —
+     `product` and `operator` define none of these, deliberately.
+
+     THE THREE VALUES ARE NOT A LADDER, THEY ARE A CHORD. Ambient motion is
+     layered: several small movements running at once. If their periods share a
+     factor they re-align, and the whole composition pulses in unison — the one
+     thing ambient motion must never do. So the periods are mutually prime in
+     tenths of a second (30, 47, 71), which puts the first full re-alignment of
+     all three past two hours. Round numbers like 3/4/6s would re-align every
+     twelve seconds. That is why these look arbitrary; they are not.
+
+     Pick a different one per layer. Which is which carries no meaning beyond
+     speed — unlike the interaction durations above, there is no "this is the
+     one for a state change". */
+  --duration-ambient-fast: 3s;
+  --duration-ambient-base: 4.7s;
+  --duration-ambient-slow: 7.1s;
 }
 
 @media (prefers-reduced-motion: reduce) {
+  /* The ambient periods are deliberately NOT collapsed to 1ms here. These drive
+     infinite loops, so 1ms would spin them at a thousand cycles a second rather
+     than stop them — the opposite of what was asked for. P-13 requires the whole
+     ambient declaration to sit inside `prefers-reduced-motion: no-preference`,
+     so under a reduce preference the animation never starts and there is nothing
+     to shorten. Absence, not speed. */
   :root { --duration-fast: 1ms; --duration-base: 1ms; --duration-slow: 1ms; }
 }

package/tokens/mode.operator.css

@@ -27,8 +27,19 @@
      Line heights UNITLESS. FLOOR: 1.5 holds even here. */
   --text-caption: 12px;  --leading-caption: 1.5;
   --text-body:    14px;  --leading-body:    1.5;
-  --text-prose:   16px;  --leading-prose:   1.6;    /* LONG-FORM text only */
+  /* 18px, not 16px, and not negotiable by density. `B-75` names 18px as the
+     floor for sustained reading, and the reference agrees — "make long body
+     text at least 18px". This token sat at 16px, which made our own rule false
+     in the one mode most likely to be read for long stretches by someone who
+     has been at it all day. Sustained readability is an accessibility floor
+     like `--size-touch-target`, not a density dial. Long prose is rare in an
+     operator surface; when it appears, it is legible. */
+  --text-prose:   18px;  --leading-prose:   1.6;    /* LONG-FORM text only */
   --text-lead:    16px;  --leading-lead:    1.5;
+  /* No fluid headings here, unlike editorial and product. This mode's largest
+     heading is 22px, which already fits ~28 characters per line on a 360px
+     screen — fluid sizing would have nothing to do. The mechanism is absent
+     because the problem is, not by oversight. */
   --text-h3:      16px;  --leading-h3:      1.5;
   --text-h2:      18px;  --leading-h2:      1.4;
   --text-h1:      22px;  --leading-h1:      1.333;
@@ -59,6 +70,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);
 
@@ -66,6 +78,10 @@
   --ease-out: cubic-bezier(0.2, 0, 0, 1);
   --ease-in-out: cubic-bezier(0.4, 0, 0.2, 1);
 
+  /* No ambient duration tokens here, deliberately. Ambient motion is
+     editorial only (P-13) — a surface someone works in all day must not
+     have anything moving on it that they did not cause. */
+
   --font-numeric: var(--font-numeric-features);
 }
 

package/tokens/mode.product.css

@@ -27,9 +27,27 @@
   --text-body:    16px;  --leading-body:    1.5;
   --text-prose:   18px;  --leading-prose:   1.6;    /* LONG-FORM text only */
   --text-lead:    20px;  --leading-lead:    1.5;
+
+  /* H1 and H2 are FLUID: they interpolate with viewport width instead of
+     switching at a breakpoint, which is why this system defines no breakpoint
+     token. Each clamp is the line through (360px viewport, min) and (1024px,
+     max); outside that range it saturates at the bounds.
+
+     The `rem` term is not decoration. `clamp(32px, 8vw, 48px)` would ignore a
+     reader who has set a larger default font size — page zoom scales `vw`, a
+     font-size preference does not — which fails WCAG 1.4.4. Keeping every term
+     in `rem` plus `vw` means the whole curve moves with the user's setting.
+
+     Only headings. Body and prose stay fixed: readability is absolute, set by
+     the eye and viewing distance, while heading size is relative — it exists to
+     contrast with body, and that contrast can compress on a narrow screen. A
+     fluid `--text-prose` would also breach the 18px floor (B-75, T20).
+
+     The minimums land on rungs the ladder already has rather than on new
+     values. Line heights are unitless, so they follow the size for free. */
   --text-h3:      20px;  --leading-h3:      1.4;
-  --text-h2:      24px;  --leading-h2:      1.333;
-  --text-h1:      32px;  --leading-h1:      1.25;
+  --text-h2:      clamp(1.25rem, 1.114rem + 0.602vw, 1.5rem);  --leading-h2: 1.333;  /* 20 → 24 */
+  --text-h1:      clamp(1.5rem, 1.229rem + 1.205vw, 2rem);     --leading-h1: 1.25;   /* 24 → 32 */
 
   --font-weight-regular: 400;
   --font-weight-bold:    600;
@@ -56,12 +74,17 @@
   --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);
 
   --duration-fast: 100ms;  --duration-base: 150ms;  --duration-slow: 200ms;
   --ease-out: cubic-bezier(0.16, 1, 0.3, 1);
   --ease-in-out: cubic-bezier(0.65, 0, 0.35, 1);
+
+  /* No ambient duration tokens here, deliberately. Ambient motion is
+     editorial only (P-13) — a surface someone works in all day must not
+     have anything moving on it that they did not cause. */
 }
 
 @media (prefers-reduced-motion: reduce) {