jig-ui 0.3.0 → 0.4.0

package/README.md

@@ -2,11 +2,37 @@
 
 A design system written to be consumed by coding agents, not read by designers.
 
-Installed as `npx jig-ui` — the bare name was taken on npm.
-
 Framework-agnostic. Tokens are CSS custom properties; rules are stated in CSS
 properties and behaviour, never in one framework's class names.
 
+Installed as `npx jig-ui` — the bare name was taken on npm.
+
+## Two ways to use it
+
+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 104 rules, **7 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,
+  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 7. Running only the agent gets you the 97 with
+no verification. **A clean `jig check` is not a clean review**, and the skill
+says so to every agent that reads it.
+
+## Quick start
+
+```bash
+npx jig-ui@latest install --agent claude   # put the skill where your agent finds it
+npx jig-ui@latest init                     # set this project up
+npx jig-ui@latest check --all              # see where you stand
+```
+
+Then ask your agent to build something. It reads the rules from the install and
+cites them.
+
 ## Install
 
 Paste the line for your agent and let it run the command.
@@ -17,53 +43,261 @@ Paste the line for your agent and let it run the command.
 | Codex | `npx jig-ui@latest install --agent codex` |
 | Cursor | `npx jig-ui@latest install --agent cursor` |
 | opencode | `npx jig-ui@latest install --agent opencode` |
+| Gemini CLI | `npx jig-ui@latest install --agent gemini` |
 | Any other agent | `npx jig-ui@latest install --agent generic` |
 
-Add `--scope global` to install once for every project instead of just this
-one. Where a global install lands depends on the agent:
+Add `--scope global` to install once for every project instead of just this one.
+Every agent supports both scopes.
 
 | Agent | Project scope | Global scope |
 | --- | --- | --- |
 | Claude Code | `.claude/skills/jig/SKILL.md` | `~/.claude/skills/jig/SKILL.md` |
-| Codex | `AGENTS.md` | `~/.codex/AGENTS.md` |
-| Cursor | `.cursor/rules/jig.mdc` | not supported |
+| Codex | `.agents/skills/jig/SKILL.md` | `~/.agents/skills/jig/SKILL.md` |
+| Cursor | `.cursor/skills/jig/SKILL.md` | `~/.cursor/skills/jig/SKILL.md` |
 | opencode | `.opencode/skills/jig/SKILL.md` | `~/.config/opencode/skills/jig/SKILL.md` |
-| Generic | `AGENTS.md` | not supported |
+| Gemini CLI | `.gemini/skills/jig/SKILL.md` | `~/.gemini/skills/jig/SKILL.md` |
+| Generic | `.agents/skills/jig/SKILL.md` | `~/.agents/skills/jig/SKILL.md` |
 
-In both scopes, the rules themselves are vendored to `<root>/.jig/` — the
-project root for a project-scoped install, or your home directory for a
-global one.
+Every agent reads a `skills/jig/SKILL.md`, so adding a new harness is a config
+change rather than a new code path. Codex uses the cross-agent `.agents/`
+directory and additionally gets a short pointer block in `AGENTS.md` — that file
+is read into every session, so it names the skill rather than restating it.
 
-Update later with `npx jig-ui@latest update` — files you have edited are left
-alone.
+Install writes the skill file **and its rules** to one place only — beside the
+skill file itself. Nothing of Jig's is vendored into your repo; your agent reads
+the rules from the install. Installing at project scope when the same agent is
+already installed globally warns rather than creating a second, contradicting
+skill.
 
-Install writes the rules and the design tokens into `.jig/`. Import the tokens
-your surface needs — one brand file, one mode file:
+## Set the project up
 
-```css
-@import ".jig/tokens/brand.default.css";
-@import ".jig/tokens/mode.product.css";
+```bash
+npx jig-ui@latest init
 ```
 
-Copy `brand.default.css` to `brand.<yourproject>.css` and edit that; `jig update`
-will not overwrite a file you have changed.
+`init` is the only command that writes into your repo. It detects your CSS
+system (Tailwind v4, Tailwind v3, plain CSS), derives a brand colour from what
+your project already has — custom properties first, then a Tailwind config, then
+the most frequent literal colour — rather than interviewing you cold, validates
+that colour against the contrast and collision requirements in Jig's own brand
+file, writes the token files, wires the `@import`s into your stylesheet when
+there is one unambiguous place for them, and runs a baseline `check` so you have
+a number to move.
 
-Or let `jig init` do the above for you:
+A single-mode project ends up with four files, all of them yours:
 
 ```
-npx jig-ui@latest init
+jig.config.json             route → mode map
+.jig/
+  state.json                bookkeeping — version, modes in use, checksums
+  tokens/
+    brand.<project>.css     your identity, edit freely
+    <mode>.css              a copy of Jig's mode file, refreshed by `update`
 ```
 
-It detects your CSS system (Tailwind v4, Tailwind v3, plain CSS), derives a
-brand colour from what your project already has (custom properties first,
-then a Tailwind config, then the most frequent literal colour) instead of
-asking cold, validates that colour against the contrast and collision
-requirements stated in `brand.default.css` itself, writes
-`.jig/tokens/brand.<project>.css` and `jig.config.json`, wires the `@import`
-into your stylesheet when there is one unambiguous place to put it, and runs
-a baseline `check` so you have a number to move. Add `--yes` to accept every
-derived default non-interactively (the mode CI and agents run in). Re-running
-`init` never overwrites a `jig.config.json` or brand file you have edited.
+The mode file is the one thing genuinely copied: a stylesheet `@import` is an
+edge in a build graph and has to resolve locally, on every machine that builds.
+
+**Commit `.jig/`.** It holds the token files your stylesheet imports, so a
+gitignored `.jig/` means the design system does not exist for anyone who did not
+run `init` themselves — their build breaks on a missing import, and CI's `jig
+check` sees no token layer at all. `init` warns if it finds `.jig/` ignored.
+
+Add `--yes` to accept every derived default non-interactively — the mode CI and
+agents run in. It states the mode it chose and where to change it, because
+`jig.config.json` outranks an agent's own inference. Re-running `init` never
+overwrites a config or brand file you have edited.
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `install --agent <name> [--scope project\|global]` | Puts the skill and its rules where your agent will find them. Writes nothing else into your repo. |
+| `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. |
+| `explain <rule-id>` | Prints a rule in full — what it forbids, what to do instead, the version it arrived in, and who checks it. Also resolves the `P-` pattern and `M-` mode specs, which no rule index contains. |
+
+Flags worth knowing:
+
+| Flag | Effect |
+| --- | --- |
+| `check --all` | Scan the whole repo instead of just changed files. Use on a first run. |
+| `check --ci` | Mechanical bucket only — deterministic, and exits non-zero on any error. |
+| `check --json` | Machine-readable findings, for tooling or for reading every finding when the terminal output elides repeats. |
+| `init --yes` | Non-interactive; accept every derived default. |
+| `install --scope global` | Install once for every project. |
+
+**Run `update` unpinned:** `npx jig-ui@latest update`. The skill pins every other
+command to the version that wrote it, so the CLI and the rules always agree;
+`update` is the one command whose job is to move that pin, so pinning it would
+mean it could never move.
+
+### As slash commands
+
+Every command is also a slash command in your agent, installed alongside the
+skill. `/jig check --all` does what `npx jig-ui check --all` does, and then acts
+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 explain C-19` | `jig explain C-19` — prints the rule as-is, without paraphrasing it |
+| `/jig install --agent cursor` | `jig install --agent cursor` |
+| `/jig update` | `jig update` |
+
+Where each lands:
+
+| Agent | Slash command file | Scope |
+| --- | --- | --- |
+| Claude Code | `.claude/commands/jig.md` | project or global |
+| Cursor | `.cursor/commands/jig.md` | project or global |
+| opencode | `.opencode/command/jig.md` | project or global |
+| Gemini CLI | `.gemini/commands/jig.toml` | project or global |
+| Codex | `~/.codex/prompts/jig.md` | **global only** |
+| Generic | — | none |
+
+Two exceptions, both deliberate.
+
+**Codex** takes its command globally only: OpenAI documents custom prompts as
+loading from `~/.codex/prompts` with no project-scoped equivalent, so a project
+install writes no prompt file. Its skill works either way — and OpenAI
+deprecates custom prompts in favour of skills for exactly that reason, since a
+skill can be shared through your repository while a prompt stays on one machine.
+
+**Generic** gets no slash command at all. `.agents/skills/` is a cross-agent
+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.
+
+## Using it with a coding agent
+
+`install` puts a skill file where your agent looks, and the rules beside it. From
+then on the agent loads the anti-patterns and the mode profile before building
+any UI, takes the mode from `jig.config.json`, loads the pattern section for
+whatever it is building, consumes tokens by name, and cites any rule it
+deliberately breaks.
+
+### Slash commands
+
+`install` also writes a `/jig` command, so the CLI is reachable without leaving
+your session:
+
+```
+/jig init          /jig check --all          /jig update
+```
+
+It runs the CLI and then does the part the CLI cannot — for `/jig check` that
+means applying the 97 judgment rules to the same files and merging both halves
+into one report keyed by rule id.
+
+| Harness | Command file |
+| --- | --- |
+| Claude Code | `.claude/commands/jig.md` |
+| Cursor | `.cursor/commands/jig.md` |
+| opencode | `.opencode/command/jig.md` |
+| Gemini CLI | `.gemini/commands/jig.toml` |
+| Codex | — run the CLI directly; see below |
+| Generic | — no harness to register with |
+
+Codex's custom prompts are not written: `codex exec` does not expand them, so a
+command file could sit there and never fire. Codex users run
+`npx jig-ui@latest check` directly — the skill in `AGENTS.md` is unaffected.
+
+**You still prompt normally.** Ask for a settings page, a data table, an empty
+state — whatever you were going to ask for. What you no longer have to say is
+*how*: "use the design tokens", "handle the loading state", "don't invent a
+colour". That part is the skill's job, and what you get back names its own
+decisions — *"P-02 forbids a column of primaries where an action repeats down a
+list"* rather than "I made the button secondary."
+
+Whether the agent picks the skill up on its own depends on the harness. Most
+surface a skill by matching your request against its description, so a request
+that plainly involves UI usually loads it. If it does not, say so once —
+"follow the jig skill" — and it will.
+
+Every finished piece of UI work ends with an attestation line:
+
+```text
+JIG_CHECK: version=<version> mode=<mode> mechanical=<pass|fail|skipped>:<n> judgment=<ran|skipped>
+```
+
+`jig check` emits the same line for the half it can do, with `judgment=not-run`.
+If an agent reports `judgment=ran`, it ran the self-check at the end of
+`rules/00-anti-patterns.md`; if it says `skipped`, it must say why.
+
+## Using it from the command line
+
+No agent required. `check` is a linter with a design system behind it.
+
+```bash
+npx jig-ui@latest check --all      # everything
+npx jig-ui@latest check            # just what changed
+npx jig-ui@latest check --ci       # for CI: deterministic, non-zero on error
+npx jig-ui@latest check --json     # for tooling
+```
+
+In CI:
+
+```yaml
+- run: npx jig-ui@latest check --ci
+```
+
+`--ci` restricts to the mechanical bucket, so the result depends only on your
+code — nothing model-dependent, no network. As a pre-commit hook, plain `check`
+looks at changed files only.
+
+What you will not get from the CLI alone is the other 97 rules. `check` says so
+rather than letting a narrow pass read as a broad one.
+
+## What `check` covers
+
+It reads CSS wherever it lives:
+
+| Where | Example |
+| --- | --- |
+| Stylesheets | `.css`, `.scss`, `.less` |
+| `<style>` blocks | HTML, Astro, Vue, Svelte, PHP, ERB, Twig, Handlebars, MDX, ASP/ASP.NET, Razor, JSP, Phoenix, EJS, Nunjucks, Liquid, Jinja, Velocity, FreeMarker |
+| Indented style blocks | Pug (`style.`), Haml (`:css`), Slim (`css:`) |
+| Style attributes | `style="color: #777"`, `style={{ color: '#777' }}` |
+| CSS-in-JS | `styled.button\`…\``, `styled(Link)\`…\``, `css\`…\``, `createGlobalStyle`, `keyframes` |
+| Tailwind arbitrary values | `className="bg-[#6D28D9] p-[13px]"` |
+| Tailwind palette pairs | `className="bg-white text-gray-400"` |
+
+Host files are reduced to their style regions before the detectors run, with
+character positions preserved, so a finding's line points at the real line in
+your `.vue` or `.tsx` file. Application code outside a style region is never read
+as CSS.
+
+The seven mechanical rules: hard-coded values past the token layer (`H-47`),
+contrast below the floor (`C-19`), removed focus rings (`E-29`), gradient text
+(`A-02`), backdrop blur (`A-04`), pure black and white (`C-18`), and the
+violet-band hue check (`A-01`, which asks rather than fails).
+
+Two deliberate limits. A bare `p-4` is **not** a finding — it resolves through a
+scale, which is what a scale is for, and the scale is your project's decision.
+And a colour outside the framework's default palette is not resolved rather than
+guessed at.
+
+Anything the suite still cannot read is named in the report, so a narrow pass
+never reads as a broad one.
+
+## Upgrading
+
+```bash
+npx jig-ui@latest update
+```
+
+Files you have edited are left alone. Upgrading from a pre-0.4.0 install that
+vendored rules into your project's `.jig/`? `init` and `check` detect the
+leftover files, report them, and — with your consent, and never for a file you
+have edited — offer to remove just the install artifacts, keeping your tokens
+and config untouched.
+
+Cursor's skill moved from `.cursor/rules/jig.mdc` to
+`.cursor/skills/jig/SKILL.md`; `init` finds the old file and offers the same
+treatment.
 
 ## Files
 
@@ -78,6 +312,9 @@ derived default non-interactively (the mode CI and agents run in). Re-running
 | `.jig/tokens/brand.*.css` | Identity. One per project. | Imported by the app |
 | `.jig/tokens/mode.*.css` | Density, scale, rhythm, motion | One per surface |
 
+`rules/*` and `rules.index.json` live beside your installed skill file, not
+in the project — see above.
+
 `00` and `01` are the always-loaded core and are sized to stay cheap in context. `03` is the largest file and should be loaded per-pattern rather than wholesale.
 
 ## Per-project declaration