jig-ui 0.12.0 → 0.14.0

package/CHANGELOG.md

@@ -1,5 +1,110 @@
 # Changelog
 
+## 0.14.0
+
+What a stranger meets before the page, what the page must not hand them, and a
+project that states its own direction.
+
+### Added
+
+- **`J-120` to `J-127`, search and sharing.** A page a stranger reaches through
+  a search result or a pasted link is judged on what that reader meets first: a
+  title that names this page and not the site, a description that says what the
+  page holds, a canonical URL where more than one address serves the same
+  content, and a share image where a link is meant to be shared. A page that
+  must not be indexed says so in the page, not only in `robots.txt` — an
+  operator surface is the case the rules were written around.
+- **`jig seo`.** A project-level audit the page rules cannot do from one file:
+  a `noindex` route listed in the sitemap, two pages claiming the same title, a
+  site with no sitemap or no `robots.txt`, a sitemap with nothing in it. It
+  reads metadata wherever the framework puts it, and it does not require
+  `DECISIONS.md` — a project without one still gets the audit.
+- **`K-128` to `K-134`, safety at the interface.** This is not a security
+  review, and nothing here should be read as one. It is the set of interface
+  decisions that are also safety decisions: markup built from text a reader
+  supplied, a link opened into a new context, a form that submits across
+  origins, a credential or a token rendered into the page, an error that quotes
+  the system back at the reader. There is no `jig secure` command, because a
+  command implies a guarantee this cannot make.
+- **`L-01` Step 6, how the layout collapses.** A composition is not finished
+  until you have said what happens to it at each width where the content needs
+  it: reduce the count, never the size; order survives; distinction survives;
+  type comes from the fluid scale, not from a breakpoint; content wider than
+  the screen scrolls inside itself rather than pushing the page sideways.
+- **A fourth judged width: 1600.** Three widths never asked what an unbounded
+  layout does with room it was never given. A measure that keeps growing, a
+  row that keeps stretching and a page that turns into a gutter with a line of
+  text in it only show themselves past the desktop width. `jig probe` renders
+  360, 768, 1280 and 1600, and `spec` composes for all four.
+- **The project's own decisions are judged, one verdict each.** `DECISIONS.md`
+  is the file the agent is most likely to read once and then drift from, so
+  `jig verdicts` now carries a `decisions=` arm: every decision in the file is
+  judged against the page, and an unjudged decision is a failure like any other.
+
+### Changed
+
+- **`/jig decide` asks for the north star and the personality.** The north star
+  is the product's, not a page's — what someone can do that they could not
+  before, and what the product gives up to do it. A page's own purpose stays
+  `spec`'s question and inherits its direction from here. Personality is asked
+  through the four things that produce it, each named with the token it
+  becomes: type, colour, corners, language. An owner with no gut feeling is
+  asked what the reader already uses — and pointed away from direct
+  competitors, because a project that borrows from one looks like a
+  second-rate version of it.
+- **Every question in `decide` and `spec` carries an example answer**, in the
+  form that can be checked beside the form that cannot. A question that takes
+  five minutes of thought to parse gets a worse answer than the same question
+  with an example attached.
+- **Adopting Jig in a project that already has CSS.** The README now says
+  plainly what happens: the rules are read before anything is written, the
+  token layer is wired how you choose, and there are four ways in — one page
+  start to finish, a large codebase, only the new pages, and a page you
+  already have. Redesigning an existing page is its own path, and `spec` asks
+  different questions when the page exists.
+
+## 0.13.0
+
+Meaning before presentation, and one fewer step anyone can skip.
+
+### Added
+
+- **`H-119` A generic element where a native one says what the content is.**
+  The rule carries a decision order: what is this content, is there a native
+  element whose meaning is that, does it describe it accurately, does order or
+  relationship matter, can CSS do the presentation, and only then a generic
+  container. It is not a rule against `div` — a `div` is right where nothing
+  more specific is true, and an approximate element is worse than a generic
+  one because it asserts something untrue. Presentation must not be required
+  to understand the content.
+  Its detector decides what the source can: a page with no `<main>`, a row of
+  destinations in a header or footer with no `<nav>`, a generic element named
+  or styled as a heading, and a repeated set on a page with no list or table.
+- **`jig probe --run <page> --save <surface>`.** The CLI renders the page
+  itself, at 360, 768 and 1280, in a headless Chrome, Chromium or Edge it
+  finds for itself — including the browsers Playwright or Puppeteer have
+  already downloaded. No dependency: Chrome's own debugging protocol over the
+  WebSocket client Node has had since 22. The Stop hook runs it before judging
+  a critique, so a review is measured whether or not anyone remembered to.
+- **The probe measures markup order against reading order.** A block the CSS
+  lifts above the one that precedes it in the markup is reported, whatever the
+  verdicts say. Two columns side by side are not an inversion: putting the
+  sidebar after the main content and moving it left is the correct pattern.
+- **The probe reads the rendered text for em dashes.** A string built in code —
+  a description assembled in a framework's frontmatter, a label written by a
+  script — reaches the page having passed no file check.
+
+### Changed
+
+- **`I-118` reads every place a reader sees text.** Every template language the
+  suite knows, and the markdown a framework renders as pages. Repository
+  documents are still exempt, and capitals now mean "document" only beside the
+  lockfile, so `docs/FAQ.md` is a page. Code is not copy: a script's text is
+  read only between real tags.
+- **The scan skips `.claude`, `.codex`, `.cursor`, `.opencode`, `.gemini` and
+  `.github`.** Jig's own vendored rules are not the project's interface.
+- **Probe files are version 3.** Older ones no longer validate.
+
 ## 0.12.0
 
 ### Added

package/README.md

@@ -12,13 +12,13 @@ Installed as `npx jig-ui` — the bare name was taken on npm.
 Jig is **a skill your coding agent reads**, and **a CLI you can run yourself**.
 They are two halves of the same thing, and the split is not arbitrary:
 
-- Of the 114 rules, **17 can be decided by a machine** — a hard-coded colour, a
+- Of the 130 rules, **26 can be decided by a machine** — a hard-coded colour, a
   contrast ratio below the floor, a removed focus ring. The CLI decides those.
-- The other **97 are judgment** — whether an empty state says anything useful,
+- The other **104 are judgment** — whether an empty state says anything useful,
   whether a label reads as an instruction, whether motion earns its place. No
   regex settles those. An agent reads the rules and applies them.
 
-Running only the CLI gets you the 17. Running only the agent gets you the 97 with
+Running only the CLI gets you the 26. Running only the agent gets you the 104 with
 no verification. **A clean `jig check` is not a clean review**, and the skill
 says so to every agent that reads it.
 
@@ -117,6 +117,183 @@ jig.config.json             route → mode map
 Nothing you wrote is touched beyond that one import line. Re-running `init`
 never overwrites a config or brand file you have edited.
 
+#### Look before you write anything
+
+**Start with `npx jig-ui@latest check --all`.** It reads your code as it stands
+and writes nothing at all — no files, no config, no import. You see what Jig
+would say about the project before deciding whether to adopt it.
+
+It is a quieter report than people expect, because Jig checks your code against
+its rules, never against its own naming:
+
+- **Your token names are yours.** `--ink-900`, `--paper`, `--space-4`: Jig has no
+  opinion about what you call things, and no rule asks you to rename anything.
+  What it looks for is a reference to a name that nothing in your project
+  declares, which is a bug in any codebase.
+- **Rules that need a fact about your project stay silent until they have one.**
+  Density and type scale follow the mode, and there is no mode until you declare
+  one, so those rules say nothing on a first run.
+- **Hard-coded values are only reported where a token layer exists to bypass.**
+  A project with no tokens is not told off for having none.
+
+On a tidy existing page with its own tokens, a first run typically reports a
+couple of specific things — a lone hex among a hundred `var()` calls, a repeated
+set of cards with no list element — rather than a wall.
+
+#### When you do run `init`
+
+The token layer is a set of custom property declarations. Declarations nothing
+references change no pixel, so adding it does not restyle your site.
+
+- **Different names never collide.** Your tokens and Jig's sit side by side; each
+  is used by whoever asks for it. You can adopt one token at a time, or none.
+- **If a name is the same in both, yours wins.** The import goes above your own
+  rules, and the later declaration is the one that applies.
+- **One line does more than declare a token:** `color-scheme: light dark`, which
+  tells the browser your page supports both, so scrollbars and form controls
+  follow the reader's system setting.
+
+#### You decide how it is wired
+
+`init`'s default is a convenience for a project with one obvious entry point,
+not a requirement. Every part of it is yours to direct, whether you do it or
+tell your agent to:
+
+- **Where the files go.** `brand` in `jig.config.json` sets the token directory.
+  Put it wherever your CSS lives.
+- **Whether Jig wires anything at all.** It adds the import only when there is
+  one unambiguous entry stylesheet. Otherwise it writes the files, prints the
+  line to add, and leaves your CSS alone for you to place.
+- **How it is wired.** The barrel is two `@import`s, brand then mode. Skip it and
+  import the two files yourself, take only the brand file, inline them into your
+  build, or import a different barrel at each route — which is what a project
+  with more than one mode does. `init` names those extra barrels and
+  deliberately does not wire them: which entry point serves `/admin` is your
+  routing, and it cannot see it.
+- **Your edits survive.** Every file `init` writes is checksummed. Change one and
+  `update` leaves it alone and says so, rather than reverting your wiring at the
+  next version.
+- **One constraint that is not a preference.** The tokens are declared on
+  `:root`, so the layer has to reach the document globally. Imported inside a CSS
+  module or a scoped component block, the tokens exist only there. Anywhere
+  global is fine.
+
+#### One page, start to finish
+
+A project with its own tokens, no Jig. Four steps, and the report after each is
+the real output:
+
+```
+$ npx jig-ui@latest check --all
+  ✗ H-47   Hard-coded colour `#fff` past the token layer      src/app.css:6
+  ⚠ H-119  3 sibling article.card elements are a repeated set …
+  1 error, 1 warning · 8 files, 5 with styles
+
+$ npx jig-ui@latest install --agent claude     # the skill your agent reads
+$ npx jig-ui@latest init --yes                 # writes the token layer, touches no CSS
+```
+
+`init` here found no single entry stylesheet, so it wrote the files and printed
+the import rather than editing anything. Adding that line yourself, and changing
+one value:
+
+```css
+@import "./jig/theme.css";   /* the line init printed */
+@import "./tokens.css";      /* your tokens, unchanged */
+
+.button { background: var(--accent); color: var(--color-on-brand); }
+```
+
+```
+$ npx jig-ui@latest check --all
+  ⚠ H-119  3 sibling article.card elements are a repeated set …
+  0 errors, 1 warning
+```
+
+The error is gone, `--ink-900` and `--paper` and the rest are exactly as they
+were, and the one warning is the judgment call left for you: whether those cards
+are a list. That is the whole loop. Repeat it wherever it is worth repeating.
+
+#### A large codebase
+
+The first `check --all` on a big repo is a long list, and the list is not a
+to-do. Read it in this order:
+
+1. **`check --all --ci` first.** Mechanical bucket, errors only, exit code you
+   can put in CI. It is the short list, and every line on it is decidable.
+2. **Then warnings, by rule rather than by file.** The report groups by rule id,
+   and a rule firing forty times is one decision made once, not forty.
+3. **Then one page at a time.** `check` defaults to the files you changed, so
+   once the first two passes are done it goes quiet and stays that way for
+   everything except what you touch.
+
+Nothing obliges you to reach zero. A `check` that is quiet on today's diff is
+worth more than one that was quiet on the whole repo six months ago.
+
+#### Only the new pages
+
+Adopting Jig everywhere is not the price of using it anywhere. The rules apply
+to what you point them at:
+
+- **New work follows the loop** — decide, spec, mockup, make, critique — and the
+  Stop hook holds it to that, if you asked for the hook.
+- **Old pages sit where they are.** They are not rewritten, and the default
+  `check` says nothing about a file nobody has touched.
+- **`jig.config.json` can exempt paths** you have no intention of revisiting, and
+  the report names every exemption on every run, so an exemption list cannot grow
+  quietly.
+- **The token layer works the same way.** A page adopts a token when someone
+  edits it to use one; no page changes on its own.
+
+#### A page you already have
+
+The loop assumes a page being built. For one that exists, the order changes
+slightly and the commands do not:
+
+1. **`/jig decide`** first, as always: the rules are the system's, the
+   decisions are yours, and a review with no decisions to check against is half a
+   review.
+2. **`/jig spec <page>`**, written from the page as built. Your agent
+   reads what is there and describes it — regions, hierarchy, navigation at each
+   size — and you confirm or correct it. It is a description, not a redesign.
+3. **`/jig critique`** then has what it needs: the rules, the spec it
+   just confirmed, and your decisions. It renders the page, measures it, and
+   reports.
+4. **`/jig make`** fixes what the critique found, and `critique` runs
+   again until it is clean or you accept what is left.
+
+Skipping step 2 and asking for a critique on its own leaves the review with
+nothing to check the page against except the rules, which is the weakest half of
+what Jig knows about your project.
+
+#### Redesigning a page you already have
+
+The opposite job, and the loop runs in its ordinary order. The difference is what
+the old page counts as: **content and constraints, not a target.**
+
+1. **Measure the page as it is, first.** `jig probe --run <page> --save <slug>`
+   records what it does today at each width — whether it scrolls sideways, whether
+   the menu opens, what order it reads in. Keep it. It is the only way to say
+   afterwards whether the redesign improved anything or merely changed it.
+2. **`/jig decide`**, if the project has not.
+3. **`/jig spec <page>`** as normal, designing forward. Take the **content** from
+   the old page — its copy, its real data, the questions its FAQ answers — and
+   decide the structure from the rules, not from what the markup happens to do
+   now. Anything that genuinely must survive is a constraint, so say so in the
+   spec: a URL that is linked from elsewhere, a field order the back end depends
+   on, legal wording somebody signed off. Everything else is open.
+4. **`/jig mockup`**, low fidelity, reviewed before code. This is where a
+   redesign is cheap to argue about.
+5. **`/jig make`** builds it, and **`/jig critique`** checks it against the spec,
+   the mockup and your decisions.
+
+The trap worth naming: carrying the old structure across because it is there. A
+page redesigned from its own markup ends up the same page with new colours. The
+old page is the brief's content; the rules and the spec decide its shape.
+
+Adopting Jig is additive. The pressure to move values into tokens arrives when
+you start using them, not on the day you install.
+
 ### A brand-new site
 
 There is no CSS to read, so there is nothing to derive from and nowhere obvious
@@ -180,6 +357,7 @@ overwrites a config or brand file you have edited.
 | `init [--yes]` | Sets the project up: CSS system, brand colour, token files, `jig.config.json`, wired imports, baseline check. The only command that writes into your repo. |
 | `check [--all] [--ci] [--json]` | Runs the rules a machine can decide. Reports findings by rule id. |
 | `update` | Refreshes an install to a newer version, leaving alone any file you have edited. |
+| `seo [--json]` | Audits what a search engine and a link preview read, across the whole project: a route whose metadata says `noindex` sitting in the sitemap, two pages claiming one title, indexable pages with no sitemap, a sitemap that lists nothing. Needs no config, no decisions and no spec. |
 | `verdicts <surface>` | Verifies a critique's verdict files and computes its counts: every rule in each pass judged once, no id that does not exist, no rule in the wrong arm, and no verdict the render probe contradicts. |
 | `probe` | Prints the render probe — one expression the critique runs in a browser at each width. It operates the menu, measures sideways scroll, and reads whether the styles and tokens applied. |
 | `gate` | Run by the Stop hook `install` adds for Claude Code, not by hand. Blocks an agent from finishing while `check` fails on the files it changed, or the step it just ran left its work unfinished. |
@@ -211,11 +389,12 @@ on the result — the CLI reports, the agent applies the judgment half.
 | Slash command | Equivalent |
 | --- | --- |
 | `/jig init` | `jig init` — then states the mode it chose and what it wired |
-| `/jig check` | `jig check` — then applies the 97 judgment rules and reports both halves |
+| `/jig check` | `jig check` — then applies the 104 judgment rules and reports both halves |
 | `/jig explain C-19` | `jig explain C-19` — prints the rule as-is, without paraphrasing it |
 | `/jig explain contrast` | `jig explain contrast` — every rule matching a word, when you do not have an id |
 | `/jig install --agent cursor` | `jig install --agent cursor` |
 | `/jig update` | `jig update` |
+| `/jig seo` | `jig seo` — then reports what a stranger meets before the page, and what one file cannot see |
 | `/jig decide` | No CLI. Once per project: interviews you and writes the project-wide decisions, with a reason for each |
 | `/jig spec invoice page` | No CLI. What exactly is being built — a page, feature or functionality — at its smallest useful version, at every screen size |
 | `/jig mockup` | No CLI. Low-fidelity design of that spec, reviewed before code — in HTML, Figma or Google Stitch, whichever you choose |
@@ -249,6 +428,30 @@ convention for *skills*, not a harness with a command system of its own, so
 there is no file to write and nothing that would read one. Ask in plain language
 instead; the skill still loads.
 
+## What a search engine reads
+
+A page's title, description and preview text are copy, and they drift because a
+copy pass reads pages and nobody reads `<head>`. Jig treats them as copy: the
+spec decides whether a page is indexable and what it claims, `make` writes the
+metadata in the same change as the headline, and `check` holds the budgets.
+
+**Which pages are meant to be found is decided by mode, not by taste.**
+`editorial` is first-visit content, so it is indexable and needs its own title
+and description. `product` and `operator` are what somebody reaches after signing
+in, so they must carry `noindex` — an admin screen in a search result is an
+invitation, and a sign-in page in one invites credential stuffing. A spec
+overrides the default per page, with a reason: a CV shared by link, a
+confirmation page, a page written for one recipient.
+
+`robots.txt` is not that mechanism. It is public and advisory, and naming a path
+in it tells strangers where to look; a path is safe to name only when something
+else protects it.
+
+`jig seo` covers what one file cannot: a route that says `noindex` and sits in
+the sitemap anyway, two pages claiming one title, a site whose pages nothing
+points at. It writes nothing and needs nothing, so it is safe to run on the first
+day, or on somebody else's codebase.
+
 ## Using it with a coding agent
 
 `install` puts a skill file where your agent looks, and the rules beside it. From
@@ -351,6 +554,19 @@ guessed at.
 Anything the suite still cannot read is named in the report, so a narrow pass
 never reads as a broad one.
 
+## What Jig does not check
+
+**Security.** There is a small section of rules about what an interface does to
+itself — a new-tab link handing over the window it left, user content written
+into the page as markup, a password field fighting the manager, a third-party
+frame with nothing narrowing it, a secret printed on screen, an error naming the
+stack. That is the interface's own surface, and it is all Jig can see.
+
+It knows nothing about sessions, rate limits, CORS origins, secrets, headers,
+dependencies or your hosting's assumptions. A clean `jig check` says nothing
+about any of them, and should never be quoted as if it did. Use something built
+for that, and keep its findings where you keep this one's.
+
 ## Upgrading
 
 ```bash
@@ -371,7 +587,7 @@ treatment.
 
 | File | Contents |
 | --- | --- |
-| `rules/00-anti-patterns.md` | 96 universal rules with corrections |
+| `rules/00-anti-patterns.md` | 112 universal rules with corrections |
 | `rules/01-modes.md` | `editorial` / `product` / `operator` profiles |
 | `rules/02-tokens.md` | Token contract, naming, consumption |
 | `rules/03-patterns.md` | Component anatomy and behaviour |