jig-ui 0.4.0 → 0.6.0

package/templates/COMMAND.md.tmpl

@@ -11,14 +11,42 @@ output — findings are ordered by severity, not position, so `head`, `tail`,
 
 ## 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.
+**Settle the surfaces before you run it.** Mode is the most consequential thing
+`init` writes and the thing it is worst at choosing: with `--yes` it takes
+`'/' → product` without reading the project at all, and `{{rules_path}}/01-modes.md`
+rule 1 then makes that config outrank your own reading of the project from then
+on. A default chosen in a second binds the project indefinitely, and density is
+expensive to reverse.
+
+You are the half that can fix this, because you are talking to someone who knows
+the answer and the CLI is not. So, first:
+
+1. **Ask what the product is**, in their words rather than Jig's — a marketing
+   or content site, a signed-in application, an internal tool people use all
+   day? A project usually has more than one of these, and each is a surface.
+2. **Map each to a mode** using the table in `{{rules_path}}/01-modes.md`:
+   `editorial` for first-visit content, `product` for the signed-in app,
+   `operator` for dense daily tools. State the mapping in one line and let them
+   correct it.
+3. **Write `jig.config.json`** with those surfaces before running anything.
+   `init` reads an existing config and honours it — writing one mode file per
+   declared mode — so this is how a decision reaches the tokens.
+4. **Then run the command.**
+
+Where there is genuinely one surface, say so and move on; the point is that the
+mode was chosen rather than defaulted into.
+
+Afterwards, report what it detected, the brand colour it derived and where that
+came from, and the surfaces it used — the output says whether they came from
+`jig.config.json` or from the default.
+
+If the token layer does not exist yet, this is the command that creates it. **Do
+not author token values yourself.** `init` derives the brand colour, checks it
+against the contrast floor in both light and dark, and records a checksum for
+each file it writes; a file you write by hand is untracked, so `jig update` can
+never refresh it again. `jig check` now reads the token layer back and holds it
+to those floors either way, so a hand-written value will be caught — but caught
+late, and unmaintainable, is worse than derived.
 
 ## check
 
@@ -57,14 +85,32 @@ Print the CLI's output as it stands. It is already the rule's full text — do n
 summarise it, and do not paraphrase the correction into your own words: the
 wording is the rule.
 
+**It takes a word as well as an id.** `explain contrast` searches every title
+and body and lists what matches; one match prints in full. Use it whenever you
+are about to reason about an area of the system rather than a specific finding
+— before reviewing colour, before writing motion — instead of guessing which
+rules apply or reading a whole rule file to find out. `explain <letter> --list`
+prints one section, `explain --list` prints every id.
+
+Reach for this before paraphrasing the rules from memory. A rule you half-recall
+is the failure mode this command exists to prevent.
+
 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.
+A well-formed id that does not exist errors, naming every id in that section —
+offer the nearest one rather than guessing what the user meant. A word that
+matches nothing errors differently, suggesting `--list`; that is a search with
+no hits, not a typo, so widen the word rather than inventing an id.
 
 ## update
 
+**Run this one as `{{update_path}} update`, not at the pinned version.** Every
+other subcommand uses the pin so the CLI and these rules agree; `update` exists
+to move that pin forward, so pinned it refreshes to the version already
+installed and reports success for a no-op — "Updated Jig → <same version>" —
+and nobody ever upgrades.
+
 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.
 

package/templates/command-metadata.json

@@ -20,8 +20,8 @@
     "status": "available"
   },
   "explain": {
-    "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>",
+    "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

@@ -128,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%);
@@ -167,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;
@@ -66,8 +84,32 @@
   --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;
@@ -67,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;
@@ -63,6 +81,10 @@
   --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) {