jig-ui 0.16.1 → 0.17.0

package/examples/README.md

@@ -0,0 +1,44 @@
+# Examples
+
+One file per rule, `<ID>.html`, showing what the rule forbids and what it asks for
+instead. A rule describes a failure in words; a reader recognises it by sight, and
+most of these failures are things people have seen a hundred times without a name
+for them. The example is the picture beside the name.
+
+## Shape
+
+```html
+<!-- A-58 · Decorative styling that implies meaning -->
+<figure data-example="dont">
+  …the failure, as small as it can be and still be recognised…
+</figure>
+<figure data-example="do">
+  …the same content, done the way the rule asks…
+</figure>
+```
+
+- **Exactly one `dont` and one `do`.** The `do` shows the same content, not a
+  different, easier one. A fix that changes the content proves nothing.
+- **Self-contained.** Styles are `style` attributes on the elements. No `<style>`,
+  `<script>`, `<link>`, event handler, or external URL. A consumer renders a figure
+  in a sandboxed frame or an inert box, and it has to look the same in both.
+- **Small.** A figure is drawn for a box about 320 by 180 pixels. It exaggerates
+  just enough to be recognised, and no more.
+- **Raw values are fine here.** An example has to show violet, a glow, a 44px
+  radius. It is a specimen of the failure, not a component, so the token rule
+  that governs a real page does not apply inside it.
+- **The `do` follows every rule**, not only its own. A fix that commits a
+  different failure teaches the second one.
+
+## Not for everything visible
+
+Some rules are about code, metadata or behaviour and have no look. Their example
+shows what a person meets because of it: the search result a missing description
+produces, the tab a link hands over, the field a password manager cannot fill.
+Where even that is impossible, the figure shows the code, set as code.
+
+## Checked
+
+`packages/cli/test/examples.test.ts` fails when a rule has no example, when a file
+has other than one `dont` and one `do`, or when a figure carries anything that
+would not render the same in a sandbox.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "jig-ui",
-  "version": "0.16.1",
-  "description": "A design system for coding agents. 130 numbered UI rules, brand x mode design tokens, and an installer for Claude Code, Codex, Cursor and opencode.",
+  "version": "0.17.0",
+  "description": "A design system for coding agents. 143 numbered UI rules, brand x mode design tokens, and an installer for Claude Code, Codex, Cursor and opencode.",
   "license": "Apache-2.0",
   "type": "module",
   "bin": {
@@ -10,6 +10,7 @@
   "files": [
     "dist",
     "rules",
+    "examples",
     "tokens",
     "templates",
     "references",

package/rules/00-anti-patterns.md

@@ -39,6 +39,7 @@ These are the strongest defaults in a model's training data and the fastest way
 ✅ Opaque `--color-bg-raised` with a `--color-stroke-weak` edge. Use translucency only over media, and only when legibility is verified against the worst frame.
 Both styles make sufficient contrast and clear hierarchy structurally difficult — neumorphism in particular defines every element with shadow alone, which fails at 3:1 almost by construction. Trend styles also age badly: the more of them a product carries, the more precisely it is dated. Minimal styling that foregrounds content lasts longer.
 Experiment freely — but not where it costs legibility or excludes people.
+**Everywhere is its own failure.** A frosted panel over a video is a layering decision; frosted cards, a frosted nav, frosted buttons and glowing glass borders on a flat page are decoration applied to everything, and they solve no layering problem at all.
 
 ### A-58 Decorative styling that implies meaning
 ❌ List items in assorted colours chosen for variety; a decorative icon beside a heading that looks pressable; a heading coloured and underlined though it is not a link
@@ -66,6 +67,7 @@ Where several already apply — a table's rows are aligned, alike, and close —
 ### A-06 The three-column feature grid reflex
 ❌ Icon-in-rounded-square + heading + two lines, three across, for any set of three things
 ✅ Let the content pick the layout. Three items of unequal weight are a list, not a grid.
+**The same reflex at any count.** Six or nine cards, each an icon, a title and a line, identical in size and shape, give every point the same weight whether it deserves it or not, and make the titles the only thing a reader can tell apart, so they skim all of them and remember none. When one point matters most, make it bigger, put it first, or give it the space the others do not get. Group related ones; drop the ones that are filler.
 
 ### A-07 Oversized radius everywhere
 ❌ One radius applied to cards, buttons, inputs and badges alike, regardless of element size
@@ -84,6 +86,61 @@ In `operator`, `--radius-surface` also selects `sm`, so cards, buttons and input
 ❌ Lorem ipsum, "Acme Inc", `https://example.com`, stock avatars left in
 ✅ Real content, or clearly marked `TODO:` that fails a build check. Placeholder text that survives to review costs a reviewer more than it saved you.
 
+### A-135 A kicker above every heading
+❌ A small uppercase, letter-spaced line over each section heading: "FEATURES" over "What you get", "HOW IT WORKS" over "Three steps to launch"
+✅ One heading that says it. If the kicker repeats the heading, delete it; if it adds something, work those words into the heading or the line under it.
+A kicker is one more line to read before the one that matters, and on every section it stops marking anything. It survives from print, where a section label helped a reader flip to a page. On a screen the heading is already the label.
+
+### A-136 An eyebrow chip over the headline
+❌ A rounded pill above the hero headline: "✦ Introducing v2", "New: AI-powered", with a border or tint that makes it look pressable
+✅ Put the news in the headline or the line under it. If the chip links somewhere, make it a link that reads as one.
+A pill is the shape of a control and of a filter, so people try to press it. When it does nothing, the page has taught them its shapes lie; when it does something, the most important action on the page is dressed as a label.
+
+### A-137 Cream and beige by reflex
+❌ A warm off-white page (`#f5f0e8`, `#faf7f2`), beige cards and a brown-grey text colour, chosen because the brief said "warm", "editorial" or nothing at all
+✅ The brand file's neutrals, or a decision recorded in `DECISIONS.md`. Cream is a fine answer to a question someone asked; it is a default when nobody did.
+Cream replaced violet (`A-01`) as the colour a model reaches for when asked to look tasteful. The failure is the same one: a palette nobody chose, which makes unrelated products look alike and dates every page that carries it.
+
+### A-138 An italic serif display headline
+❌ An oversized headline set in an italic serif, often with one word picked out: "Beautifully *crafted*", "Work, *reimagined*"
+✅ Type chosen for this product's voice (`DECISIONS.md`), set upright unless the italic means something. Emphasis comes from the words.
+It is the shortcut to an editorial look, and it has been taken so often that it now reads as the absence of a type decision rather than the presence of one.
+
+### A-139 A side-tab accent border
+❌ A thick coloured stripe down one side of an ordinary card, list item or panel
+✅ No stripe. Where the stripe would mean something, a status, a warning, the current item, say it with a label or an icon and text, and keep the stripe only as a second signal.
+A coloured edge on one side is the shape of an alert. Put on a card with nothing to announce, it makes the card look like a warning, and a page of them makes a real warning impossible to see.
+
+### A-140 A thick coloured border on a rounded element
+❌ A 2px or wider coloured outline around a card or button with a large radius
+✅ A hairline in `--color-stroke-weak`, or no border and a surface step. If the element must stand out, change its surface, not its outline.
+A heavy outline on a curve becomes the most visible shape in the element, and the eye traces it instead of reading what is inside.
+
+### A-141 Cards inside cards
+❌ A card holding a panel holding a card, each with its own border, padding and background
+✅ One container at most, and the groups inside it made with space, type and a divider (`A-67`).
+Every layer adds padding and an edge around the same content, and takes width from it. Three layers deep, the content has the least room on the page and the chrome has the most.
+
+### A-142 The soft rounded card
+❌ A 1px hairline and a wide soft shadow on the same card, a large radius, a pale tint: the card that holds every section of a generated page
+✅ Choose one edge: a hairline, or a surface step (`A-08`). Keep the radius to the element's size (`A-07`).
+An edge and a shadow both draw the same boundary, so the card has two outlines. Repeated down the page, the cards stop grouping anything and become the page's texture.
+
+### A-143 A decorative grid or stripe background
+❌ Faint grid lines, dot grids or repeating diagonal stripes filling the space behind content
+✅ A plain surface. Keep grids for what is measured or placed on them: a canvas, a map, a chart.
+A grid says "this is a workspace". Behind a paragraph it is noise at the one contrast level that makes text harder to read without being visible enough to mean anything.
+
+### A-144 Dark mode with glowing accents
+❌ Coloured glows on borders, buttons and headings of a dark page: `box-shadow: 0 0 24px #22d3ee`, neon outlines, a halo behind the hero
+✅ Dark mode from the token ramp (`C-21`, `C-66`), with the brand colour spent where it means something (`I-56`).
+Glow is contrast added without meaning. On a dark page everything that glows competes to be first, and the one element that needs attention looks like all the rest.
+
+### A-146 Numbered section labels
+❌ "01", "02", "03" in small type beside section headings that are not a sequence
+✅ Number only a real order: steps to follow, a ranking, a procedure. Anything else keeps its heading and no number.
+A number promises an order. A reader told there are three steps looks for what comes after the third, and a page that numbers its sections only because they are sections has promised something it does not deliver.
+
 ---
 
 ## B. Typography
@@ -503,6 +560,11 @@ Where people must *browse* to decide, split the list into two dependent fields
 iOS Safari zooms the whole page when a field whose text is below 16px takes focus, and it does not zoom back out when the field loses it. The reader is left with a form wider than the screen, scrolling sideways to find the next field (`D-115`).
 Setting `maximum-scale=1` on the viewport to stop it is not the fix. That disables pinch zoom for everyone, which is an accessibility failure in its own right.
 
+### F-147 Asking for more than the task needs
+❌ A sign-up that asks for a phone number, company size, job title and "how did you hear about us" before the person can try anything
+✅ Ask for what this step needs to work. Every other field is optional and says so, or it moves to the moment it becomes useful.
+Each field is a question someone has to answer and a reason to leave. The ones the product does not need yet are also the ones people fill with nonsense, so the data they were meant to collect is worse than none.
+
 ## G. Motion
 
 ### G-42 Entrance animation on everything
@@ -517,6 +579,11 @@ Setting `maximum-scale=1` on the viewport to stop it is not the fix. That disabl
 
 **A consequence worth stating: motion is never the sole signal, for the same reason colour is not (`C-20`).** Honouring the reduced-motion path removes the animation, so any state that was communicated by movement alone is communicated to that user by nothing at all. A field that only shakes on a bad password has no error state under reduced motion. Pair the motion with text, an icon, or a colour change that survives without it.
 
+### G-145 A pulsing status dot
+❌ A green dot that pulses or pings beside "All systems operational", "Live", "Online"
+✅ A still dot and the word. Motion is for a state that is changing now: a sync in progress, a recording under way.
+A pulse says "look here, something is happening". On a status that has not changed in a week it is a false alarm on a loop, and it trains people to ignore the one indicator whose job is to be noticed when it matters (`G-43` applies too: under reduced motion it must still read).
+
 ### G-44 Durations too long
 ❌ 500ms+ on UI feedback
 ✅ 100–200ms for state change, up to 300ms for larger transitions. If it can be perceived as waiting, it is too slow.

package/rules/01-modes.md

@@ -190,7 +190,7 @@ Attempting to vary these by mode is a category error:
 - **Accessibility floors.** Contrast, focus indication, target size, semantic markup. Identical in all three. `operator` being dense does not license a 24px tap target or a 3:1 body contrast.
 - **Brand identity.** Palette, typeface, logo, voice.
 - **State completeness.** Every mode renders loading, empty, error and disabled.
-- **The anti-pattern file.** All 112 rules in it apply everywhere.
+- **The anti-pattern file.** All 125 rules in it apply everywhere.
 
 ---
 

package/rules/05-copy.md

@@ -54,6 +54,7 @@ Someone who reads only the heading still gets the point. Someone who needs the d
 ✅ "Beautiful waterfront location", "Fast check-in experience", "Free secure parking"
 A heading must carry its own meaning. People scan headings and skip the supporting text, and screen reader users routinely pull up a list of every heading on a page to navigate — a list of one-word labels tells them nothing.
 Break long passages into groups with a descriptive heading each, rather than one unbroken block.
+**The same holds for a page's headline.** "Build the future of work", "Your all-in-one platform", "Where ideas come to life" could sit above any product, which means they say nothing about this one. A headline names what the product does and for whom: "Search your logs by asking in plain English". If it would still be true after swapping in a competitor's name, rewrite it.
 
 ### I-82 Uneven text length across parallel elements
 ❌ Three feature columns of two, four and three lines
@@ -112,6 +113,7 @@ Users assume different words mean different things, because in a well-built inte
 Screen reader users pull up a list of every link on a page; a list of "learn more" is useless. Sighted users scanning have to read the surrounding text to work out where each one goes. Three identical links also imply one destination.
 "Click here" is worse still: it explains a mechanism people already understand, and it is wrong for anyone on touch, keyboard or voice.
 Often the cleanest fix is to drop the link and make the **heading** the link.
+**Buttons too.** "Get started", "Learn more", "Try it free" on every call to action say that something happens, not what. Name the outcome: "Create a workspace", "Search your first log file", "Book a 20-minute demo". A button whose label would fit any product is a button the reader has to decode.
 
 ### I-57 Actions and text centred by default
 ❌ Centred buttons and centred body text as a general habit

package/rules.index.json

@@ -912,5 +912,106 @@
     "severity": "note",
     "since": "0.14.0",
     "pass": "code"
+  },
+  {
+    "id": "A-135",
+    "bucket": "hybrid",
+    "severity": "warning",
+    "since": "0.17.0",
+    "detector": "heading-kicker",
+    "pass": "code"
+  },
+  {
+    "id": "A-136",
+    "bucket": "hybrid",
+    "severity": "warning",
+    "since": "0.17.0",
+    "detector": "eyebrow-chip",
+    "pass": "code"
+  },
+  {
+    "id": "A-137",
+    "bucket": "hybrid",
+    "severity": "warning",
+    "since": "0.17.0",
+    "detector": "cream-palette",
+    "pass": "code"
+  },
+  {
+    "id": "A-138",
+    "bucket": "hybrid",
+    "severity": "warning",
+    "since": "0.17.0",
+    "detector": "italic-serif-display",
+    "pass": "code"
+  },
+  {
+    "id": "A-139",
+    "bucket": "hybrid",
+    "severity": "warning",
+    "since": "0.17.0",
+    "detector": "side-tab-border",
+    "pass": "code"
+  },
+  {
+    "id": "A-140",
+    "bucket": "hybrid",
+    "severity": "warning",
+    "since": "0.17.0",
+    "detector": "rounded-accent-border",
+    "pass": "code"
+  },
+  {
+    "id": "A-141",
+    "bucket": "judgment",
+    "severity": "warning",
+    "since": "0.17.0",
+    "pass": "screen"
+  },
+  {
+    "id": "A-142",
+    "bucket": "judgment",
+    "severity": "warning",
+    "since": "0.17.0",
+    "pass": "screen"
+  },
+  {
+    "id": "A-143",
+    "bucket": "hybrid",
+    "severity": "warning",
+    "since": "0.17.0",
+    "detector": "decorative-grid-background",
+    "pass": "code"
+  },
+  {
+    "id": "A-144",
+    "bucket": "hybrid",
+    "severity": "warning",
+    "since": "0.17.0",
+    "detector": "glow-accent",
+    "pass": "code"
+  },
+  {
+    "id": "G-145",
+    "bucket": "hybrid",
+    "severity": "warning",
+    "since": "0.17.0",
+    "detector": "pulsing-dot",
+    "pass": "code"
+  },
+  {
+    "id": "A-146",
+    "bucket": "hybrid",
+    "severity": "warning",
+    "since": "0.17.0",
+    "detector": "numbered-section-labels",
+    "pass": "code"
+  },
+  {
+    "id": "F-147",
+    "bucket": "judgment",
+    "severity": "warning",
+    "since": "0.17.0",
+    "pass": "screen"
   }
 ]

package/templates/COMMAND.md.tmpl

@@ -965,9 +965,13 @@ every rule.
 probe in the browser and save what it returns beside the verdicts:
 
 ```
-# If a browser is on this machine, one command renders and records all three:
+# If a browser is on this machine, one command renders and records every width:
 {{scripts_path}} probe --run <page> --save <surface>
 
+# A built site that links its styles from the site root (/assets/site.css) must be
+# served, or nothing loads. Name the build directory and the CLI serves it:
+{{scripts_path}} probe --run dist/pricing/index.html --serve dist --save <surface>
+
 # Otherwise, at each width: open the page in whatever browser you have, evaluate
 # what `{{scripts_path}} probe` prints, and pipe exactly what it returned into:
 {{scripts_path}} probe --save <surface>
@@ -976,7 +980,8 @@ probe in the browser and save what it returns beside the verdicts:
 `--run` drives a headless Chrome, Chromium or Edge it finds for itself — a
 project with Playwright or Puppeteer already has one — and needs nothing
 installed. The Stop hook runs it too, before it judges a review, so a render is
-not a step anyone can forget.
+not a step anyone can forget. Do not copy the build and rewrite its links to make
+a file load: `--serve` shows the page a browser actually gets.
 
 **The CLI writes the probe file, you do not.** `--save` reads the probe's output,
 stamps it with the page's checksum, and stores it. That is what makes the file a
@@ -1182,7 +1187,9 @@ Not a command to run. In Claude Code, `install` adds a Stop hook that runs
 `check` error or warning, or a critique's verdict files fail `verdicts`, it refuses
 to let you stop and hands you the failures as the reason. **Fix what it names.** Do
 not edit verdict files to satisfy it, and do not report the work as done while it is
-blocking.
+blocking. It also refuses when a critique's verdict files changed after `critique`
+wrote them, in a session that did not run `critique`: a fix is judged by the next
+review, never by the builder editing the last one.
 
 A warning you are sure is right as it stands, because the detector guessed and the
 guess is wrong here, is waived on its own line or the line above, in the file's