jig-ui 0.24.0 → 0.26.0

package/examples/J-164.html

@@ -0,0 +1,7 @@
+<!-- J-164 · An indexable page a link preview cannot read -->
+<figure data-example="dont">
+  <div style="font-family:system-ui,-apple-system,'Segoe UI',sans-serif;font-size:13px;line-height:1.45;color:#1f1f1f;background:#f5f5f4;padding:16px;min-height:176px;box-sizing:border-box;"><div style="font-size:12px;color:#57534e;margin-bottom:6px">Sam, in a team chat:</div><div style="background:#fff;border:1px solid #d6d3d1;border-radius:8px;padding:10px;"><div style="color:#1a0dab;font-size:13px">tidewell.io/pricing</div><div style="border-left:3px solid #d6d3d1;margin-top:8px;padding-left:8px;font-size:12px;color:#4d5156">Tidewell<br>Home · Product · Docs · Pricing · Sign in</div></div><div style="font-size:11px;color:#5c5c5c;margin-top:8px">No preview tags: the card is the site's name and its navigation.</div></div>
+</figure>
+<figure data-example="do">
+  <div style="font-family:system-ui,-apple-system,'Segoe UI',sans-serif;font-size:13px;line-height:1.45;color:#1f1f1f;background:#f5f5f4;padding:16px;min-height:176px;box-sizing:border-box;"><div style="font-size:12px;color:#57534e;margin-bottom:6px">Sam, in a team chat:</div><div style="background:#fff;border:1px solid #d6d3d1;border-radius:8px;padding:10px;"><div style="color:#1a0dab;font-size:13px">tidewell.io/pricing</div><div style="border-left:3px solid #3f6212;margin-top:8px;padding-left:8px;font-size:12px;color:#1f1f1f"><b>Pricing · Tidewell</b><br><span style="color:#4d5156">Three plans, billed monthly or yearly. Cancel any time.</span></div></div><div style="font-size:11px;color:#5c5c5c;margin-top:8px">og:title and og:description: the card says what the page is.</div></div>
+</figure>

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "jig-ui",
-  "version": "0.24.0",
-  "description": "A design system for coding agents. 159 numbered UI rules, brand x mode design tokens, and an installer for Claude Code, Codex, Cursor and opencode.",
+  "version": "0.26.0",
+  "description": "A design system for coding agents. 160 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": {

package/rules/00-anti-patterns.md

@@ -365,7 +365,7 @@ Without `viewport-fit=cover`, the browser keeps the page inside the safe area on
 
 ### D-115 The page scrolls sideways on a phone
 ❌ At phone width the whole page is wider than the screen — a data table, a long URL, an image, a `width: 100vw` element or a fixed-width block pushes it out, and the reader can drag the page left and right
-✅ At every width, nothing makes the page wider than the screen. Content that is genuinely wider — a data table, a code block — scrolls inside its own container with a visible edge (`E-62`), and the page itself never does. `editorial` goes further and allows no scrolling regions on mobile at all (`M-01`).
+✅ At every width, nothing makes the page wider than the screen. Content that is genuinely wider — a data table, a code block — scrolls inside its own container with a visible edge (`E-62`), and the page itself never does. `editorial` goes further and allows no scrolling regions on mobile at all (`M-01`): there a code block wraps its long lines and a wide table stacks its rows (`L-01`, step 6).
 Judge it on a render, not in the source: at 360px, `document.documentElement.scrollWidth` must not be greater than `document.documentElement.clientWidth`. The usual causes are each one line to fix — `overflow-wrap: anywhere` on text the author does not control, `max-width: 100%` on media, `width: 100%` instead of `100vw` (which includes the scrollbar), and a wrapper with `overflow-x: auto` around anything tabular.
 A page that scrolls sideways is not merely untidy. The reader's vertical swipes drift, the page slides half off the screen, and every line of text needs re-centring before it can be read.
 
@@ -376,6 +376,7 @@ Agents render the happy path. This section exists because that is the single mos
 ### E-28 Missing states
 ❌ A component with only a default appearance
 ✅ Every interactive element defines: `hover`, `focus-visible`, `active`, `disabled`. Every data view defines: loading, empty, error, and partial/truncated.
+A browser makes an `<iframe>` a tab stop whether or not anything in it can be used. One that only shows something, with nothing inside to operate or scroll, is taken out of the tab order (`tabindex="-1"`) rather than given states it has no use for; a keyboard reader otherwise meets a stop with nothing to see. One the reader uses (a player, a map, a form) keeps its stop and shows focus.
 
 ### E-29 Focus removed without replacement
 ❌ `outline: none` with nothing in its place
@@ -411,7 +412,7 @@ Where disabling is genuinely right, put a message beside it or a tooltip on it e
 ❌ A toolbar of icon-only buttons whose meaning depends on recognising the glyph
 ✅ A visible text label beside the icon, or the icon plus label on the primary path.
 This is **not** the same problem as `E-34`. An `aria-label` serves a screen reader and does nothing for a sighted user with low computer literacy, or anyone meeting an unfamiliar glyph. Both are required.
-Icon-only is acceptable for a small set of near-universal glyphs (close, search, menu) and in `operator`, where repetition builds recognition — and even there, on first-run surfaces the label stays.
+Icon-only is acceptable for a small set of near-universal glyphs and in `operator`, where repetition builds recognition — and even there, on first-run surfaces the label stays. Close, search and menu are examples, not the whole list: the test is whether most readers would name the glyph the same way without the label. A sun and moon for the theme, or a service's own widely known mark linking to it, usually pass; a funnel, a sparkle or a lightning bolt does not. An icon-only control still carries its name in text a screen reader reads (`E-34`).
 
 ### E-52 Unconventional controls
 ❌ A bespoke form field, checkbox or select that looks and behaves unlike every other one the user has met
@@ -713,6 +714,11 @@ A second copy of the positioning is a second thing to keep in step by hand, whic
 ✅ Concatenate the static routes unconditionally, and let a failed read yield the stale list rather than an empty one. When a list is genuinely empty, prove it before shipping.
 An empty sitemap is not a missing sitemap. It is a positive claim, and the crawler believes it.
 
+### J-164 An indexable page a link preview cannot read
+❌ A link pasted into a message or a post that shows a bare address, or the site's name over a line of its navigation
+✅ Every indexable page states its own preview: `og:title` and `og:description`, beside its `<title>` and meta description, and `og:type` for what it is (`article` for a post). An image and `og:url` take the page's full address: add them once the site has one, never as a relative path.
+The card is met before the page, often by someone who never opens it. Without these tags each service builds the card from whatever it finds, and they find different things. A preview is copy, like the title and description: the change that rewrites the page rewrites its card (`J-120`), and a value the page already holds is read, not typed again (`J-126`).
+
 ---
 
 ## K. Safety at the interface

package/rules/01-modes.md

@@ -85,7 +85,7 @@ Resolved values: `02-tokens.md` — the option sets for type, spacing, radius an
 - One hero maximum, at the top. A second full-viewport section is a second hero.
 - Every page states its subject above the fold in text, not only in an image.
 - Prose blocks are measure-capped even when the container is wide.
-- No horizontal scrolling regions on mobile. Reflow instead.
+- No horizontal scrolling regions on mobile. Reflow instead: a code block wraps its long lines, keeping its line breaks and indents, and a table too wide for the screen stacks its rows, each cell with its column's name (`L-01`, step 6).
 - JavaScript: **none by default.** A content page ships no script unless a feature on it needs some: a theme toggle, a search box, a filter. That is a default, not an absolute zero. Each script names, in a comment, the feature and the decision or rule that asks for it, and a review judges whether the feature needs it and whether it is as small as the feature allows, not whether it exists. What the budget forbids is script no feature asks for: a framework runtime to render static text, a library for one effect, tracking bundled into the page. **Behaviour a rule requires is not a feature and is not counted**: a few lines whose only job is something a rule asks for and the browser does not give, such as `Escape` closing a `<details>` menu, or a tap outside closing a menu in a fixed header (`P-14`), are allowed in every mode, under 1 KB, with the rule named in a comment. Nothing else rides along in them.
 
 ---
@@ -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 128 rules in it apply everywhere.
+- **The anti-pattern file.** All 129 rules in it apply everywhere.
 
 ---
 

package/rules/02-tokens.md

@@ -262,6 +262,16 @@ It is an accessibility floor, so it is excluded from the table above — there i
 nothing per-mode about it to resolve. The same is true of `--focus-ring-width`
 and `--focus-ring-offset`, which live in the brand file for that reason.
 
+**Inside a table row, the row is the target, and every row is one height.** A
+dense row is shorter than the floor (`operator`'s 36px), and a control that
+sets its own `min-height` to the floor stretches the rows that hold it and not
+the rest: in a run, an invoices table whose "Mark paid" rows stood 48px tall
+among 36px ones. So a control in a row takes the row's height and never its
+own. For a mouse, a dense row is above WCAG 2.2's 24px minimum; for a finger it
+is not, so under `@media (pointer: coarse)` the mode files raise `--size-row`
+(and `--size-row-compact`) to `--size-touch-target`, and every row grows
+together.
+
 **Layout sizes.** Three tokens size a page's frame, where the others size what
 is inside it. A real site found none of them and made up its own three:
 

package/rules/03-patterns.md

@@ -285,6 +285,7 @@ Primarily an `operator` pattern; the rules apply wherever a table appears.
 **Rules**
 - Row identity is stable across refresh, sort and filter. A row that moves under a click causes the wrong record to be acted on — the most damaging bug this pattern has.
 - Numeric columns are right-aligned and use tabular figures (`--font-numeric`). Text columns are start-aligned. Never centre either.
+- A cell stays a table cell. To line up what is inside it (a name and a tag, an icon and a label), put `display: flex` on a wrapper inside the cell, never on the `<td>` or `<th>` itself: a cell given its own display stops taking its row's height, so its text and its border drift from the rest of the row. A table stacked on a phone, the whole table set to `block`, is the exception (`L-01`, step 6). The render probe reports a cell that has left its table.
 - Column headers state units. "Weight" is ambiguous; "Weight (kg)" is not.
 - Truncation is resolvable by click or expand, never by hover alone (`E-31`, `01-modes.md`).
 - Sort state is visible in the header and reflected in the URL, so a view can be shared.
@@ -564,10 +565,27 @@ everything else follows from.
    fluid: they track the viewport between a floor and a ceiling with no media
    query at all. A hand-written ladder of sizes per breakpoint reintroduces the
    jumps the scale exists to remove, and goes stale the moment the scale changes.
-5. **Content that is genuinely wider scrolls inside itself.** A code block, a
-   wide table, a long identifier: its own container scrolls with a visible edge
-   (`E-62`), keeps its type size, and the page never scrolls sideways (`D-115`).
-   `editorial` allows no scrolling region on mobile at all (`M-01`).
+5. **Content that is genuinely wider scrolls inside itself, except in
+   `editorial` on a phone.** A code block, a wide table, a long identifier: its
+   own container scrolls with a visible edge (`E-62`), keeps its type size, and
+   the page never scrolls sideways (`D-115`). `editorial` allows no scrolling
+   region on mobile (`M-01`), so there each one reflows instead:
+   - **A code block** keeps its line breaks and indents and wraps a long line
+     (`white-space: pre-wrap`, `overflow-wrap: anywhere`). What is copied is
+     the source as written, not the wrapped lines.
+   - **A table too wide to fit** stacks its rows: each row a block, led by the
+     cell that names the row (a person, an invoice, a rule) as the block's own
+     heading, with no label in front of it. The other cells follow beneath it,
+     and a cell carries its column's name only where its value does not say
+     what it is: a bare "Yes", a number, a date. An email address, a role, a
+     status badge or a price says what it is, so it gets no "Email:", "Role:"
+     or "Status:". The row's actions sit together at the block's end, side by
+     side where they fit, with no "Actions" label. It stays a `<table>` with
+     its header row, so a screen reader still reads it as one. Where it fits,
+     it stays a table: the switch is the width at which its columns stop
+     fitting.
+   - **A long identifier** (a URL, a hash, a file path) breaks where it must
+     (`overflow-wrap: anywhere`).
 6. **Each transition happens where the content needs it.** The width at which
    three columns stop fitting is a property of the columns, not of a device. Set
    it from the content, and expect the numbers to differ per component.

package/rules/05-copy.md

@@ -90,7 +90,7 @@ Whichever you choose, be consistent across sibling elements — a list where thr
 Interface text is read in fragments, at a glance, in a space someone else's content has to fit too. An em dash is a pause the reader has to interpret: it stands in for a comma, a colon, a bracket or a full stop, and which one it is only becomes clear after reading past it. The punctuation that says exactly one thing is faster.
 It is also the clearest tell of machine-written copy. Generated text reaches for the em dash far more often than a person does, and readers have learned to notice. Copy that reads as generated is copy the reader trusts less, whatever it says.
 This is about interface strings: labels, buttons, headings, errors, empty states, help text, and the prose a page ships. Markdown counts where a framework renders it as a page, which is most of them (`src/content`, `content/`, MDX routes). A repository document does not: `README.md`, `CHANGELOG.md`, `AGENTS.md` and their kin are written for whoever works on the code, and so are your commit messages and this file.
-A verbatim quotation keeps its own punctuation. Text a page quotes from another source (a document, a spec, a person), marked as a quotation with `<blockquote>` or `<q>`, is that source's words, and changing them to satisfy this rule would misquote it. The page's own copy around the quotation, and any heading or label it gives it, is still held to the rule.
+A verbatim quotation keeps its own punctuation. Text a page quotes from another source (a document, a spec, a person), marked as a quotation with `<blockquote>` or `<q>`, is that source's words, and so is a program's own output or code shown as it is, in `<pre>`, `<code>`, `<samp>` or `<kbd>`. Changing either to satisfy this rule would misquote it. The page's own copy around the quotation, and any heading or label it gives it, is still held to the rule.
 The en dash keeps its one job: ranges, where it is read as "to" (`2–10 seats`, `Mon–Fri`). That is not a pause, and it is not affected.
 
 ### I-87 Inconsistent vocabulary

package/rules.index.json

@@ -864,6 +864,13 @@
     "since": "0.14.0",
     "pass": "code"
   },
+  {
+    "id": "J-164",
+    "bucket": "mechanical",
+    "severity": "warning",
+    "since": "0.25.0",
+    "detector": "metadata"
+  },
   {
     "id": "K-128",
     "bucket": "mechanical",

package/templates/COMMAND.md.tmpl

@@ -322,10 +322,12 @@ Write the answer as `critique: each` or `critique: at-ship`.
 
 ### 2. Run `L-01`
 
-Read `L-01 · Layout method` in `{{rules_path}}/03-patterns.md` and run its five
+Read `L-01 · Layout method` in `{{rules_path}}/03-patterns.md` and run its six
 steps against the answers. The spec's structural half **is** that output — group,
-order by importance, space from the inside out, align to a grid, and state the
-hierarchy plainly enough that the squint question can be answered against it.
+order by importance, space from the inside out, align to a grid, state the
+hierarchy plainly enough that the squint question can be answered against it,
+and decide how it collapses. Step 6 is where the phone composition comes from,
+including what this mode does with a code block or table wider than the screen.
 
 ### 3. Write it down — one composition per screen size
 
@@ -483,7 +485,7 @@ to the spec, never the spec to the decisions.
 - **"The design system decides" is not a value.** When the user defers — "you decide",
   "whatever Jig says", "leave it to the system" — that is an instruction to look the
   answer up, not a phrase to copy into the spec. Search in this order: the `P-`
-  pattern for the component (`{{command_prefix}}explain <component>`), `L-01`'s five
+  pattern for the component (`{{command_prefix}}explain <component>`), `L-01`'s six
   steps, then the rules. Write the composition that lookup gives — "stacked, Pro
   first", "Menu button, links in a vertical list" — and cite the id it came from.
   Three of six specs in a live run wrote "arrangement decided by design system" into
@@ -599,6 +601,34 @@ its size's frame of the drawing at `mockup_at:`. Otherwise a spec can go through
 several confirmed rounds after its drawing was approved and still say `approved`
 over a drawing of none of them.
 
+### Before you stop: what the gate holds a spec to
+
+With the Stop hook, each of these keeps the session open until it is fixed. Get
+them right as you write, not after the gate names them:
+
+- **A spec writes under `.jig/` only.** A change to `DECISIONS.md`, a stylesheet or
+  a page is for `{{command_prefix}}decide`, `make` or `tweak`: record in the spec
+  what the owner said, and hand the change on.
+- **The front matter holds Jig's fields and nothing else.** Anything more goes in
+  the prose below it.
+- **Quotation marks within a few words after "owner", or after "the user said",
+  mark the owner's words.** What is inside them must be what the owner said: in
+  this conversation, in `DECISIONS.md`, or already in the spec. To name a
+  decision, a heading or a file near the word "owner", leave the quotation marks
+  off.
+- **`<name>.checked.json` is of the spec as it stands.** Its `spec` value matches
+  `{{scripts_path}} checksum <name>`, so an edit after the check means a second
+  check, of what changed.
+- **Each fact has one `source`:** a path from the project root, `path:line`, or a
+  URL, and nothing else. The file exists and the line is in it. Two places are two
+  facts; what you found at the source goes in `note`.
+- **`holds` is `true`, `false` or `"unchecked"`, with a `note` for anything but
+  `true`.** A fact found false is fixed in the spec before the owner is asked.
+- **`confirmed: true` only on the owner's yes, in this session, to the sheet you
+  showed them.** Words in the request that started the session came before the
+  sheet existed, and are not a reply to it, even when they say the owner
+  confirms. Show the sheet and stop.
+
 ## mockup
 
 **Low-fidelity design.** Draw the confirmed spec in grayscale, at every size it
@@ -849,6 +879,22 @@ confirmed again.
 With the Stop hook, the gate reads the quotation after `approved` or `skipped` and
 holds it to what the owner said in this session.
 
+### Before you stop: what the gate holds a mockup to
+
+- **A mockup writes under `.jig/` only:** the drawing in `.jig/mockups/`, and the
+  spec's `mockup:` and `mockup_at:` lines.
+- **The drawing shows what the spec lists**, at every size, and either side of each
+  switch the page crosses. The gate checks this before you put it to the owner.
+- **`mockup:` stays `pending` until the owner answers.** Then it is `approved` or
+  `skipped`, followed by their words in quotation marks: the reply that approves
+  this drawing, or says to skip it. Words that only say they looked at it, or
+  that are about something else, are not their word on the drawing. Ask them
+  whether they approve it for `make`, and quote the answer.
+- **`mockup_at:` names the approved drawing**, a file under `.jig/mockups/` that
+  exists, or a link.
+- **An approved drawing does not change.** Changing it after approval sets
+  `mockup: pending` and puts it to the owner again.
+
 Then stop. The next step is `{{command_prefix}}make`.
 
 ## make
@@ -1242,9 +1288,13 @@ The probe opens the phone menu, presses Escape, measures sideways scroll, and re
 whether the styles and tokens actually applied. `verdicts` refuses `rendered: true`
 without a probe at each width, and refuses an `ok` the probe contradicts — a `P-14`
 "ok" on a menu that did not open, a `D-115` "ok" on a page that scrolls sideways. It
-also fails a page that renders in the browser's default font, or shows `${` to
-readers, whatever the verdicts say. Never write a probe file yourself: when it
-disagrees with you, it is the review that is wrong.
+also names what the page fails whatever the verdicts say: it renders in the
+browser's default font, shows `${` or an em dash to readers, or serves a missing
+or overlong title or description. Those are findings on the page, listed under
+`!` and counted as `measured=` on the `JIG_VERDICTS` line. Put each in the report;
+make or tweak fixes them, and the critique leaves the page as it is.
+Never write a probe file yourself: when it disagrees with you, it is the review
+that is wrong.
 Then run:
 
 ```
@@ -1540,6 +1590,21 @@ judges it, and leave the verdicts alone. The page then owes a critique, and
 `{{command_prefix}}ship` will not pass until one has judged it. Never defer it
 on your own account: the gate refuses a deferral nobody gave.
 
+### Before you stop: what the gate holds a tweak to
+
+- **The spec is confirmed, and its mockup approved or skipped.** A page that has
+  neither goes through `mockup` and `make`.
+- **The page's regions and its approved drawing stay as they were.** A change to
+  what the page holds goes through `spec` and `mockup`.
+- **`tweak.json` holds `at`, `change`, `ids` and, when the owner said so,
+  `deferred`, and no other field.**
+- **`change` is the owner's words for the change, exactly as they gave them in
+  this session.** Nothing goes before or after them, not even a label such as
+  "the owner's words:". What you made of them goes in the spec's Tweak entry.
+- **`ids` names at least one rule or decision**, and each is re-judged by a reader
+  that did not make the change, unless `deferred` quotes the owner telling you to
+  leave it for later (or is `true` where the page's critique waits for ship).
+
 ### Finish
 
 Report what changed, in the owner's words; the decision and spec lines you

package/templates/SKILL.md.tmpl

@@ -49,7 +49,7 @@ cite the number when you follow or deliberately break one.
    says is lost to every check. If it keeps recurring, tell the owner, since
    Jig may be missing a field.
    **Building a screen rather than a single component?** Read `L-01 · Layout
-   method` in `{{rules_path}}/03-patterns.md` and run its five steps before
+   method` in `{{rules_path}}/03-patterns.md` and run its six steps before
    writing any markup. It is a procedure, not a component, so step 4 never
    selects it and nothing else will. (`explain L-01` prints it too, but the
    file is the source — do not skip the step if the command is unavailable.)

package/tokens/brand.default.css

@@ -117,9 +117,13 @@
   --focus-ring-offset: 2px;
 
   /* ================= TYPE ================= */
-  --font-text:    ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif;
+  /* Each platform's own interface face, named one by one: San Francisco,
+     Segoe UI, Roboto, then Noto Sans and Helvetica/Arial for the rest.
+     `system-ui` is left out on purpose: on Linux it resolves to the desktop's
+     own font, often DejaVu Sans, before any face below it is tried. */
+  --font-text:    -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Noto Sans", "Helvetica Neue", Arial, sans-serif;
   --font-display: var(--font-text);
-  --font-mono:    ui-monospace, "SF Mono", "Cascadia Code", monospace;
+  --font-mono:    ui-monospace, "SF Mono", Menlo, Consolas, "Cascadia Code", "Liberation Mono", monospace;
   --font-numeric-features: "tnum" 1, "lnum" 1;
 
   /* ================= RADIUS — four, by element size ================= */

package/tokens/mode.operator.css

@@ -102,3 +102,12 @@
 @media (prefers-reduced-motion: reduce) {
   :root { --duration-fast: 1ms; --duration-base: 1ms; --duration-slow: 1ms; }
 }
+
+/* On a touch screen a table row is a finger's target. A dense row (36px, 32px
+   compact) is above WCAG 2.2's 24px minimum for a mouse, and below the 48px a
+   finger needs, so under a coarse pointer every row rises to the floor. A
+   control inside a row never sets its own height to reach it: every row in a
+   table is one height, and here the tokens make that height the right one. */
+@media (pointer: coarse) {
+  :root { --size-row: var(--size-touch-target); --size-row-compact: var(--size-touch-target); }
+}

package/tokens/mode.product.css

@@ -105,3 +105,10 @@
 @media (prefers-reduced-motion: reduce) {
   :root { --duration-fast: 1ms; --duration-base: 1ms; --duration-slow: 1ms; }
 }
+
+/* On a touch screen a table row is a finger's target: a compact row (40px)
+   rises to the 48px floor under a coarse pointer, as `operator`'s rows do. A
+   control inside a row never sets its own height to reach it. */
+@media (pointer: coarse) {
+  :root { --size-row-compact: var(--size-touch-target); }
+}