@erclx/canon 5.61.0 → 5.62.0

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## [5.62.0](https://github.com/erclx/canon/compare/v5.61.0...v5.62.0) (2026-10-24)
+
+
+### Features
+
+* **governance:** cover more WCAG criteria in the ui rules ([#2677](https://github.com/erclx/canon/issues/2677)) ([25b6190](https://github.com/erclx/canon/commit/25b619039aa3656e239385713f796c5e34810485))
+* **governance:** name the partner of a split rule on sync ([#2681](https://github.com/erclx/canon/issues/2681)) ([1d6703e](https://github.com/erclx/canon/commit/1d6703e74deb7968b0121b5e3148e474ed836c89))
+* **tooling:** let a project decline or customize one golden file ([#2675](https://github.com/erclx/canon/issues/2675)) ([41c5ec0](https://github.com/erclx/canon/commit/41c5ec042a8d50b968e853a175f45eac5a59703c))
+
 ## [5.61.0](https://github.com/erclx/canon/compare/v5.60.0...v5.61.0) (2026-10-24)
 
 

package/README.md

@@ -104,7 +104,7 @@ Working with an agent rather than reading this yourself? It loads `CLAUDE.md` at
 - [Operating model](docs/workflow/operating-model.md): orchestrator, planner, and worker roles for building across parallel sessions
 - [Skill map](docs/workflow/skill-map.md): plugin skills grouped by the moment a project meets them
 - [Skill map on request](docs/workflow/skill-map-on-request.md): plugin skills that serve a request rather than a moment
-- [Visual design workflow](docs/workflow/visual-design-workflow.md): tiered guide for design authoring
+- [Visual design workflow](docs/workflow/visual-design-workflow.md): how canon plans, builds, and reviews a UI
 - [Target projects](docs/target/projects.md): scaffold, add a domain later, sync upstream drift
 - [Agents](docs/agents/index.md): CLI flags, exit codes, and JSON output shapes
 - [Docs index](docs/index.md): every reference doc in this repo

package/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "canon",
   "description": "Runs your agent's work and keeps its code good, on one setup for every repo.",
-  "version": "5.61.0",
+  "version": "5.62.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/claude/skills/canon-cli/SKILL.md

@@ -83,7 +83,8 @@ Read the doc each line names before running one of these. `canon docs install-an
 
 - `canon sync` runs every installed domain's sync, so it carries each risk below.
 - `canon gov sync` replaces a rule you edited and deletes a rule the toolkit retired, edited or not.
-- `canon tooling sync --write` replaces every golden config a stack ships. Seeds are copy-once. Nothing writes without the flag. See `canon docs sync`.
+- `canon tooling sync --write` replaces a golden config canon changed and holds one you edited until `--replace <path>` names it. Nothing writes without the flag. See `canon docs sync`.
+- `canon tooling inject` replaces every golden config a stack ships, skipping only a declined or customized path.
 
 ### Migrate and indexes
 

package/claude/skills/design-identity/references/card-route.md

@@ -21,11 +21,11 @@ Check for a `card.config.mjs` with a `card-src/pages/og-card.astro` beside it. W
 
 ```plaintext
 No card route installed, so the card shipped as a PNG this run.
-`canon tooling sync astro . --write` installs the route, and it replaces every other
-golden config in the astro stack, so run it when you mean to sync the stack.
+`canon tooling sync astro . --write` installs the route, and it writes the astro
+stack's new and stale configs, so run it when you mean to sync the stack.
 ```
 
-Never run that sync to obtain the route, since it copies the whole stack over the project's own framework, lint, typescript, and test configs. Never hand-write the scaffold either, since a copy written here drifts from the one the stack maintains.
+Never run that sync to obtain the route, since it writes the stack's configs beside the project's own framework, lint, typescript, and test configs, holding only the ones the project edited. Never hand-write the scaffold either, since a copy written here drifts from the one the stack maintains.
 
 ## Writing and capturing the route
 

package/claude/skills/target-update/SKILL.md

@@ -68,6 +68,8 @@ Target update: `<path>`, canon `<installed>` to `<running>`.
 
 **Drift:** <each non-empty cause from sync --check, with its count and paths>
 
+**Tooling holds:** <each tooling config the write would hold, being a drifted entry whose `cause` is `edited` or `unattributed`, then each `dispositions` entry, declined ones by path and customized ones marked when `moved` is true, or omitted when none>
+
 **Where it lands:** <the linked worktree this run is already in, or the worktree `.claude/worktrees/<name>/` it will enter, or the branch it will create in place when the operator declines a worktree>
 
 **Calls for you:** <each judgment call below this run meets, with the default this skill takes>
@@ -122,7 +124,13 @@ The record tree is untracked, so a `record-tree` rewrite has no undo. Run `canon
 
 ## Step 5: sync
 
-Run `canon sync .`, then `canon tooling sync <stack> . --write` when the tooling diff named files to change. Treat each drift cause the way the preview stated:
+Run `canon sync .`, then `canon tooling sync <stack> . --write` when the tooling diff named files to change. The write holds every config the preview listed under tooling holds.
+
+- Add `--replace <path>` only for a held path the operator named in the reply, never for the whole list the write prints
+- Offer `canon tooling customize <path>` for a held path the operator wants kept, and `canon tooling lift <path>` for a moved customized one they want to take
+- Leave a declined path alone, since no write reaches it
+
+Treat each governance drift cause the way the preview stated:
 
 | Cause                       | This skill                                                                                       |
 | --------------------------- | ------------------------------------------------------------------------------------------------ |

package/claude/skills/ux-audit/SKILL.md

@@ -36,7 +36,7 @@ For each surface, look for:
 3. **Inconsistencies**: spacing, tone of voice, interaction patterns, icon use, keyboard affordances
 4. **Roughness in daily use**: friction, redundant steps, unclear affordances, ambiguous labels
 
-Use `canon/DESIGN.md` as ground truth for intent where it exists. Observations only, no implementation suggestions or fixes.
+Use `canon/DESIGN.md` as ground truth for intent where it exists. Observations only, no implementation suggestions or fixes. Take what consistent interaction means from the `ui` rules in `.claude/rules/`, and skip that when the project installed none.
 
 Where Step 1 found a committed capture for this surface, judge composed output (spacing, overlap, contrast, wrapping) against it rather than inferring layout from markup. Where none exists, judge from source and say so in that surface's findings, since a source read cannot see what only a render shows.
 

package/docs/agents/install-and-sync.md

@@ -32,7 +32,7 @@ A flat installed-rule layout makes `gov sync` report "No governance surfaces fou
 - A retired `.claude/GOV.md` is removed
 - A binary older than the stamp holds every rule it has no source for and asks for an upgrade
 
-After a rename the new name shows as `missing` when the stamp records a stack, and `gov install <stack>` adds it.
+After a rename the new name shows as `missing` when the stamp records a stack, and `gov install <stack>` adds it. A partner `governance/splits.toml` names shows as `missing` when the tree holds the split rule and lacks the partner, and `gov install --add <partner>` adds it.
 
 `canon gov regen [--root <path>]` runs against the toolkit root alone. It rewrites `.claude/rules/canon/` and `.claude/rules/internal/` from `internal/`, and exits 1 when the record names something that does not resolve.
 
@@ -68,6 +68,40 @@ After a rename the new name shows as `missing` when the stamp records a stack, a
 - `present` marks a copy an earlier sync left, which is reported and never deleted
 - `canon tooling sync <stack> [target]` writes only under `--write`. `--check` reports and exits 0, and a headless run with neither flag exits 1.
 
+### Drift cause and the write hold
+
+A `drifted` entry in `configs` carries a `cause`, read against the golden hash the last write recorded for that path.
+
+- `stale`: the target still hashes to the record, so canon moved and the project did not. `--write` replaces it.
+- `edited`: the target no longer hashes to the record. `--write` holds it.
+- `unattributed`: no hash is recorded, as on every target synced before hashes existed. `--write` holds it.
+
+A config no stack in the recorded chain ships is a first install and is never held, so a fresh scaffold takes every golden config of a stack new to it, even after `canon init` recorded `base`.
+
+A held path stays drifted, so the next headless run still exits 1. Pass `--replace <path>` once per path to take the golden copy, as the command the write prints does. A `--replace` naming no config the chain writes refuses with `unknown-replace`.
+
+### Dispositions
+
+`decline <path> [target] [--reason <text>]`, `customize <path> [target]`, and `lift <path> [target]` set or clear one path's disposition, each with `--json`. The path is relative to the target and resolves against the recorded chain, never a stack argument.
+
+- A success answers `{ ok: true, action, path, entry? }`, where `entry` is the recorded `{ disposition, base?, reason? }` and is absent after a lift
+- A declined or customized path leaves `configs`, `seeds`, and `withheld` for `dispositions`, as `{ rel, stack, kind, disposition, present, moved? }`
+- `moved` is set on a customized config alone, and counts toward the exit once the golden copy no longer matches `base`
+- Sync and inject never write a path in `dispositions`, and nothing deletes one the project still holds
+
+A refusal answers `{ ok: false, reason, message }` with exit 1:
+
+| `reason`                | Meaning                                                   |
+| ----------------------- | --------------------------------------------------------- |
+| `no-chain`              | No tooling chain is recorded, so run `tooling sync` first |
+| `bad-path`              | The path leaves the target                                |
+| `not-golden`            | No stack in the recorded chain ships the path             |
+| `already-held`          | The path is already declined or customized, so lift it    |
+| `seed-not-customizable` | The path is a seed, which sync never overwrites           |
+| `missing-file`          | `customize` named a config the target does not hold       |
+| `not-held`              | `lift` named a path with no disposition                   |
+| `toolkit-root`          | The target is the toolkit checkout, the source of truth   |
+
 `canon tooling inject` and `prune-gitignore` apply one stack with no scan or prompt, and the latter prints the number removed on stdout. Use `sync` unless scripting provisioning, and pass `--nested` inside an open frame.
 
 ## Whole-project sync
@@ -78,16 +112,16 @@ After a rename the new name shows as `missing` when the stamp records a stack, a
 
 `canon sync --check` writes nothing and needs no clean tree. `--json` emits the record, `--exit-code` fails CI.
 
-| State        | Meaning                                                            |
-| ------------ | ------------------------------------------------------------------ |
-| `stale`      | Still matches what the toolkit installed                           |
-| `customized` | The project edited it                                              |
-| `stranded`   | Sits at a path the toolkit no longer installs to                   |
-| `orphaned`   | The project authored it                                            |
-| `drifted`    | No stamp covers it                                                 |
-| `missing`    | Governance only. The recorded stack lists it and the tree lacks it |
-| `retired`    | Governance only. The toolkit no longer ships it                    |
-| `renamed`    | Governance only. The toolkit ships it under a new name             |
+| State        | Meaning                                                                 |
+| ------------ | ----------------------------------------------------------------------- |
+| `stale`      | Still matches what the toolkit installed                                |
+| `customized` | The project edited it                                                   |
+| `stranded`   | Sits at a path the toolkit no longer installs to                        |
+| `orphaned`   | The project authored it                                                 |
+| `drifted`    | No stamp covers it                                                      |
+| `missing`    | Governance only. The recorded stack lists it, or a split rule leaves it |
+| `retired`    | Governance only. The toolkit no longer ships it                         |
+| `renamed`    | Governance only. The toolkit ships it under a new name                  |
 
 `retired` and `renamed` count toward `--exit-code`. `orphaned` and `missing` do not.
 

package/docs/index.md

@@ -9,4 +9,4 @@ One-line reference for each doc in this folder.
 
 - [Agents](agents/index.md): CLI catalog and invocation rules for agents, split by command domain. Start with overview.
 - [Target](target/index.md): Scaffold, sync, and migrate a toolkit-managed project, with worked setups for three project shapes.
-- [Workflow](workflow/index.md): How a person and their agents run a feature, from the design tier through the parallel-session loop to the shell that launches them.
+- [Workflow](workflow/index.md): How a person and their agents run a feature, from the design loop through the parallel-session loop to the shell that launches them.

package/docs/target/migrations.md

@@ -75,7 +75,7 @@ The `memory` record kind left `canon records`, so `canon records validate memory
 - `canon repo metadata`, `canon autoship`, and the `120-bash` rule are gone, and `canon gov sync` removes the rule <!-- canon-keep-retired -->
 - `memory-capture`, the `603-memory` rule, and the `memory` standard are gone, so send a lesson to the context entry that owns the fact <!-- canon-keep-retired -->
 
-Two held files run, `.husky/post-merge` and `.claude/hooks/pr-create-log.sh`, and a stale copy calls a missing binary or names a removed skill. Resync what the toolkit owns before sweeping what the project wrote, and run the second line once per stack.
+Two held files run, `.husky/post-merge` and `.claude/hooks/pr-create-log.sh`, and a stale copy calls a missing binary or names a removed skill. Resync what the toolkit owns before sweeping what the project wrote, and run the second line once per stack, naming a held hook with `--replace`.
 
 ```bash
 canon gov sync
@@ -181,20 +181,18 @@ The verb adds `Bash(canon pr merge:*)` and `Bash(gh pr merge:*)` so a session ca
 
 ## Move the capture cases out of the harness, once
 
-A web project's `e2e/screenshot.ts` is a config, so sync overwrites it. It now loads `CASES` from a seeded `e2e/capture/cases.ts` that sync copies once and never overwrites. Cases edited in the old harness leave the working tree on the first sync and stay in git history.
+A web project's `e2e/screenshot.ts` is a config. It now loads `CASES` from a seeded `e2e/capture/cases.ts` that sync copies once and never overwrites. A harness you edited is held on `--write`, so the new one lands only once you pass `--replace e2e/screenshot.ts`.
 
-- Copy your cases from the old `e2e/screenshot.ts` into `e2e/capture/cases.ts` before the next sync.
+- Copy your cases from the old `e2e/screenshot.ts` into `e2e/capture/cases.ts`, then sync with `--replace e2e/screenshot.ts`.
 - Evidence now defaults to `e2e/evidence/`. Set `export const EVIDENCE_ROOT = 'evidence'` in `e2e/capture/cases.ts` to keep a committed baseline at the old path.
 - A run from a folder with no `e2e/capture/cases.ts` exits 1 and names the file.
 
-## Add the keyboard rule beside a held a11y rule, once
+## Add the rules a split left behind, once
 
-The `a11y` rule split in two. Focus styles, Escape and shortcuts, composite widgets, focus management, and pointer target size moved to a new `keyboard` rule. `canon gov sync` refreshes only the rules a project holds, so it rewrites `a11y.md` without those bullets and never adds `keyboard.md`.
-
-A project holding `.claude/rules/canon/ui/a11y.md` adds the new rule alone:
+The splits created `pointer` and `ux-controls`, and sync refreshes only held rules. `canon gov sync` now names the missing partner of `keyboard.md` and `ux-completeness.md` on every run and adds nothing itself. `a11y.md` gained two bullets and lost none, so it needs no partner.
 
 ```bash
-canon gov install --add keyboard --yes .
+canon gov install --add pointer,ux-controls --yes .
 ```
 
 ## Group a long paths section in `CLAUDE.md`, once

package/docs/target/sync.md

@@ -44,13 +44,32 @@ Add `--json` for a machine-readable report and `--exit-code` to fail CI when a t
 
 - Seed docs such as `CLAUDE.md` and `canon/REQUIREMENTS.md`: merge by hand, keeping the project's customizations
 - Installed governance rules: `canon gov sync <path>`, which adds no new rules and reports coverage afterward
-- Tooling configs and seeds: read differences with `canon tooling diff <stack> <path>`, then `canon tooling sync <stack> <path> --write`, which overwrites golden configs and copies each seed once
+- Tooling configs and seeds: read differences with `canon tooling diff <stack> <path>`, then `canon tooling sync <stack> <path> --write`, which holds an edited config and copies each seed once
 - Index regeneration: `canon indexes regen`
 
 After `canon gov sync` applies, it lists each rule it copied with its globs and how many project files match. A `ui/` rule adds a pointer to `/canon:ux-audit`. `--json` writes `{ "coverage": [{ "rule", "paths", "files", "ui" }] }` to stdout, empty when nothing was copied, with `files` null outside git. The report never changes the exit code.
 
 Try a scenario from [sandbox](../../canon/context/development/sandbox.md) before syncing a real project.
 
+### Held, declined, and customized golden files
+
+`--write` replaces a golden config only when canon changed it and the project did not. A config the project edited, or one no earlier write recorded, is held and listed with a `--replace` command that takes the golden copy. A config from a stack the target never synced is a first install and is never held.
+
+A project can also opt out of one golden file without leaving the stack. Each verb below takes the path relative to the target, as `canon tooling diff` lists it.
+
+```bash
+canon tooling decline .github/workflows/readme-screenshot.yml --reason "no screenshots here"
+canon tooling customize e2e/home.spec.ts
+canon tooling lift .github/workflows/readme-screenshot.yml
+```
+
+- `decline` keeps sync and inject from writing the file again, and leaves a copy the project still holds in place
+- `customize` keeps the project's copy of a config through every write, and `diff` exits 1 once the stack ships a newer golden copy
+- A seed cannot be customized, since sync never overwrites one
+- `lift` hands the file back, so the next sync writes it
+
+These verbs are the only writers of the record in `canon/config/config.json`, so never edit it there by hand.
+
 ## Running sync from an agent session
 
 `canon sync .` applies every domain sync, then offers a commit and pull request that needs a terminal. With no terminal on stdin the syncs apply, the git step is refused, and the command exits 0. Commit yourself. Sync refuses a dirty working tree, and `canon sync --check .` does not.

package/docs/workflow/ai-workflow.md

@@ -66,7 +66,7 @@ An independent session invokes `canon:review-pr` once the pull request is open,
 
 ### UI-heavy project
 
-Pick a design tier before the first feature session. See [visual design workflow](visual-design-workflow.md).
+A UI feature runs the same plan, build, and review loop at any size. See [visual design workflow](visual-design-workflow.md).
 
 ## Skills
 

package/docs/workflow/index.md

@@ -1,11 +1,11 @@
 ---
 title: Workflow
-subtitle: How a person and their agents run a feature, from the design tier through the parallel-session loop to the shell that launches them.
+subtitle: How a person and their agents run a feature, from the design loop through the parallel-session loop to the shell that launches them.
 ---
 
 # Workflow
 
-How a person and their agents run a feature, from the design tier through the parallel-session loop to the shell that launches them.
+How a person and their agents run a feature, from the design loop through the parallel-session loop to the shell that launches them.
 
 ## Agent surface
 
@@ -17,5 +17,5 @@ How a person and their agents run a feature, from the design tier through the pa
 - [Parallel features](parallel-features.md): Run independent features in parallel worktrees, with the records and board every session shares
 - [Skill map on request](skill-map-on-request.md): When to reach for the plugin skills that serve a request rather than a moment in a project's life
 - [Skill map](skill-map.md): When to reach for each plugin skill, grouped by the moment a project meets it
-- [Visual design workflow](visual-design-workflow.md): Tiered guide for design authoring with Claude Code
+- [Visual design workflow](visual-design-workflow.md): How canon plans, builds, and reviews a UI, from the design reference a plan cites to the browser pass that holds a pull request open
 - [Zshrc aliases for Claude Code](zshrc-aliases.md): Shell aliases that shorten common Claude Code invocations

package/docs/workflow/visual-design-workflow.md

@@ -1,57 +1,83 @@
 ---
 title: Visual design workflow
-description: Tiered guide for design authoring with Claude Code
+description: How canon plans, builds, and reviews a UI, from the design reference a plan cites to the browser pass that holds a pull request open
 category: Workflow
 ---
 
 # Visual design workflow
 
-Three tiers run from prose-only design docs to a graphical source of truth, and tiers stack. [Claude Design](../../wiki/claude/design.md) is the ceiling tool for tiers 1 and 2.
+Canon runs a UI feature through one loop. A plan cites the design, a worker builds against it and captures what it painted, and two independent reviews check the result. A project with no graphical design tool runs all of it, since the design lives in prose and in tracked frames.
 
-## Tier 0: prose only
+## Plan
 
-The default. `canon/DESIGN.md` holds visual intent as one Overview paragraph, at most three one-line rules a section, and a table naming each color and shape role, with a lead naming the stylesheet. Claude Code alone suffices, and [`test-craft`](../../claude/skills/test-craft/SKILL.md) says which layer a Playwright journey belongs at.
+`canon:plan-feature` reads `canon/DESIGN.md` and `canon/design/index.md` before it places a UI change. It loads `canon:design-taste`, which decides the layer order a surface is designed in, the coherence locks that keep it consistent, and the defaults a model reaches for that the surface should reach past.
 
-- The seed is `tooling/claude/seeds/canon/DESIGN.md`, and its column headers stay verbatim
+- The plan carries a `## Design references` section naming the accepted design for each surface it changes, or `None identified.` when there is none.
+- A design becomes a reference through `canon:design-record`, which lands an accepted pick in `canon/design/` and carries its values into `canon/DESIGN.md`.
 
-These skills cover the tier:
+## Build
 
-- `canon:ui-checklist`, `canon:ux-audit`, and `canon:ux-measure` review and measure a UI
-- `canon:pick-by-eye` drafts candidates as frames on a [Frameboard](https://www.npmjs.com/package/frameboard) board and takes your pick
-- `canon:design-record` lands a pick in `canon/design/` and carries its values into `canon/DESIGN.md`
-- `canon:design-identity` drafts a logo mark and social card
+The worker opens each cited reference, light and dark, before its first edit to that surface. It takes sizes, spacing, and colors from the frame HTML rather than the image, and reports a reference that does not resolve instead of building without it.
 
-Pick tier 0 when the UI is not the core product, decisions fit in sentences, and stakeholders review code.
+- The ui rules fire as a family on the files the worker edits, and `governance/rules/ui/` holds the set.
+- The `surface-capture` rule has the worker capture the full page in every theme the surface ships, against a preview server and never a dev server.
+- It sets the widths too, being 320 plus each breakpoint in `canon/DESIGN.md` for a layout case, and one width for a state case.
 
-## Tier 1: visual companion
+## Self-check
 
-Prose stays the source of truth, with a visual render as a feedback surface. Human edits to these derived artifacts are review annotations.
+Before the pull request opens, the worker runs two checks.
 
-- Excalidraw canvas server plus the community [`yctimlin/mcp_excalidraw`](https://github.com/yctimlin/mcp_excalidraw) MCP, where the agent draws, reads back, and revises
-- Playwright MCP ([`microsoft/playwright-mcp`](https://github.com/microsoft/playwright-mcp)) for browser checks off the accessibility tree
-- Chrome DevTools MCP ([`ChromeDevTools/chrome-devtools-mcp`](https://github.com/ChromeDevTools/chrome-devtools-mcp)) for traces, network, DOM, and CSS
-- Claude Design for codebase extraction or a polished handoff bundle
-- A frontend design skill: [pbakaus/impeccable](https://github.com/pbakaus/impeccable), [nextlevelbuilder/ui-ux-pro-max-skill](https://github.com/nextlevelbuilder/ui-ux-pro-max-skill), or Anthropic's `frontend-design`
+- `canon:ui-checklist` writes the boxes a reviewer reads beside the captures. Each box is one observable behavior, and a box that needs eyes carries a `(taste)` mark.
+- `canon:pr-evidence` posts the captures and the checklist on the pull request as one comment, which the reviews read.
 
-Impeccable keeps its own root `DESIGN.md` and `PRODUCT.md`, separate from `canon/DESIGN.md`. Use Excalidraw for agent-driven layout iteration, and Claude Design for one extraction pass or the final handoff. Most projects pick one.
+`canon drive <url> <run>` covers states a first render cannot reach. A run file walks a page through named interactions and measures each state, with three probes:
 
-Pick tier 1 when stakeholders want layouts before code and one contributor owns design and implementation.
+- `focus` reads where keyboard focus lands and whether it shows
+- `details` reads disclosure state
+- `axe` runs the accessibility engine
 
-## Tier 2: visual as source of truth
+Run `canon drive --help` for the step kinds and the run file shape.
 
-Design happens in a graphical tool, and implementation follows it. `canon/DESIGN.md` becomes generated, with a top note naming the upstream Claude Design project ID or Figma file URL.
+## Review
 
-- Figma desktop with the official [Figma Dev Mode MCP](https://www.figma.com/blog/introducing-claude-code-to-figma/) for teams with a designer already on Figma. It syncs both ways and captures a running UI into editable frames.
-- Claude Design with its Claude Code handoff bundle for teams without Figma. The handoff is one-way.
-- The Playwright and Chrome DevTools MCPs from tier 1
+Two reviews run beside each other and finish on their own clocks.
 
-Pick tier 2 when the UI is the product, a designer owns it, and design changes more often than code.
+- `canon:review-pr` reads the code and the stills in the evidence comment, and posts under `## Review`.
+- `canon:review-ui` never reads the diff. It drives each checklist box in the running app through the pinned `@playwright/cli` and posts under `## UI review`.
+- Every box gets one verdict, being pass, fail, needs eyes, or not driven.
 
-## Decision guide
+After the boxes, `review-ui` sweeps every route they reached:
 
-Count yes answers to four questions. Zero or one is tier 0, two or three is tier 1, and four is tier 2.
+- console errors on each route
+- sideways overflow at each width a box named
+- the `focus`, `details`, and `axe` probes through `canon drive`
 
-- Is the UI the product rather than a thin interface over a backend?
-- Do non-engineers review visual proposals before code exists?
-- Is there a dedicated designer, or will there be one?
-- Does design iterate independently of code?
+## What holds a review open
+
+A UI review stays open while the branch owes a fix. Three things owe one:
+
+- a failed box
+- a sweep finding, being a console error, an overflow, or an axe violation of a gated class
+- a box the page kept the pass from driving
+
+Two kinds of result report without holding the review open.
+
+- A taste box needs eyes, so the pass captures both themes and leaves the call to you.
+- Every other probe result, and every axe `incomplete`, is a reading to confirm, since each probe carries a known class of false finding.
+
+At the time of writing, the gated axe classes are contrast, target size, accessible names, labels, alt text, document title and language, valid ARIA, and nested interactive controls. A rule leaves the list on its first false finding, so `canon drive --help` and the `review-ui` skill carry the current one.
+
+A close posts as `## UI review closed`. The reviewers lift the draft mark on their close, and you merge.
+
+## Design authoring
+
+Most projects author design in the loop above and need nothing more. Start with `canon:pick-by-eye`, which drafts candidates as frames on a [Frameboard](https://www.npmjs.com/package/frameboard) board and takes your pick, then record the pick with `canon:design-record`. `canon:design-identity` drafts a logo mark and social card the same way.
+
+A graphical tool earns its place when design is the product, a designer owns it, and it changes more often than code. Then the tool is the source of truth, and `canon/DESIGN.md` carries a top note naming the upstream project.
+
+- Figma with the official [Figma Dev Mode MCP](https://www.figma.com/blog/introducing-claude-code-to-figma/), for a team already on Figma. It syncs both ways and captures a running UI into editable frames.
+- [Claude Design](../../wiki/claude/design.md) with its Claude Code handoff bundle, for a team without Figma. The handoff is one-way.
+
+The loop above runs unchanged on either, with the tool's export standing in for the pick.
+
+For the skills by moment, see the [skill map](skill-map.md).

package/governance/detect.toml

@@ -172,6 +172,10 @@ files = ["index.html", "*/index.html"]
 deps = ["react", "vue", "svelte", "astro", "next", "solid-js", "preact"]
 files = ["index.html", "*/index.html"]
 
+["pointer"]
+deps = ["react", "vue", "svelte", "astro", "next", "solid-js", "preact"]
+files = ["index.html", "*/index.html"]
+
 ["forms"]
 deps = ["react", "vue", "svelte", "astro", "next", "solid-js", "preact"]
 files = ["index.html", "*/index.html"]
@@ -180,6 +184,10 @@ files = ["index.html", "*/index.html"]
 deps = ["react", "vue", "svelte", "astro", "next", "solid-js", "preact"]
 files = ["index.html", "*/index.html"]
 
+["ux-controls"]
+deps = ["react", "vue", "svelte", "astro", "next", "solid-js", "preact"]
+files = ["index.html", "*/index.html"]
+
 ["surface-capture"]
 deps = ["react", "vue", "svelte", "astro", "next", "solid-js", "preact"]
 files = ["index.html", "*/index.html"]

package/governance/ledger/ui/a11y.md

@@ -9,12 +9,13 @@ The field is web accessibility, and the authority is the W3C, through WCAG 2.2 a
 
 ## Semantics
 
-| Bullet                                    | Source                                                                                                                                                                                                                                             | Read                 |
-| ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
-| Native `<button>` or `<a>` over a `<div>` | [Using ARIA, first rule](https://www.w3.org/TR/using-aria/): "If you can use a native HTML element or attribute with the semantics and behavior you require already built in", use it "instead of re-purposing an element and adding an ARIA role" | 2026-10-18           |
-| Attribute spelling per syntax             | [React common components](https://react.dev/reference/react-dom/components/common): the DOM prop is `tabIndex`, "A number. Overrides the default Tab button behavior", where HTML spells it `tabindex`                                             | 2026-10-18, React 19 |
-| Role and synchronized state               | [Understanding Name, Role, Value](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html): "the name and role can be programmatically determined" and "notification of changes to these items is available to user agents"               | 2026-10-18, WCAG 2.2 |
-| Name for a control with no visible text   | [Understanding Name, Role, Value](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html): every user interface component's "name and role can be programmatically determined"                                                           | 2026-10-18, WCAG 2.2 |
+| Bullet                                    | Source                                                                                                                                                                                                                                                                                    | Read                 |
+| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
+| Native `<button>` or `<a>` over a `<div>` | [Using ARIA, first rule](https://www.w3.org/TR/using-aria/): "If you can use a native HTML element or attribute with the semantics and behavior you require already built in", use it "instead of re-purposing an element and adding an ARIA role"                                        | 2026-10-18           |
+| Attribute spelling per syntax             | [React common components](https://react.dev/reference/react-dom/components/common): the DOM prop is `tabIndex`, "A number. Overrides the default Tab button behavior", where HTML spells it `tabindex`                                                                                    | 2026-10-18, React 19 |
+| Role and synchronized state               | [Understanding Name, Role, Value](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html): "the name and role can be programmatically determined" and "notification of changes to these items is available to user agents"                                                      | 2026-10-18, WCAG 2.2 |
+| Name for a control with no visible text   | [Understanding Name, Role, Value](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html): every user interface component's "name and role can be programmatically determined"                                                                                                  | 2026-10-18, WCAG 2.2 |
+| Name contains the visible label           | [Understanding Label in Name](https://www.w3.org/WAI/WCAG22/Understanding/label-in-name.html): "the name contains the text that is presented visually", and the start position is "A best practice". "People who operate with voice interaction use the visible labels in their commands" | 2026-10-23, WCAG 2.2 |
 
 ## Text alternatives
 
@@ -28,6 +29,7 @@ The field is web accessibility, and the authority is the W3C, through WCAG 2.2 a
 | Bullet                          | Source                                                                                                                                                                                                                                             | Read                 |
 | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
 | 3:1 for boundaries and graphics | [Understanding Non-text Contrast](https://www.w3.org/WAI/WCAG22/Understanding/non-text-contrast.html): "Ensure meaningful visual cues achieve 3:1 against the background"                                                                          | 2026-10-18, WCAG 2.2 |
+| 4.5:1 for text                  | [Understanding Contrast (Minimum)](https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html): "The visual presentation of text and images of text has a contrast ratio of at least 4.5:1", with "Large-scale text" at 3:1                 | 2026-10-23, WCAG 2.2 |
 | Color never the only carrier    | [Understanding Use of Color](https://www.w3.org/WAI/WCAG22/Understanding/use-of-color.html): "Color is not used as the only visual means of conveying information, indicating an action, prompting a response, or distinguishing a visual element" | 2026-10-18, WCAG 2.2 |
 
 ## Reflow

package/governance/ledger/ui/keyboard.md

@@ -9,26 +9,28 @@ The field is web accessibility, and the authorities are the W3C, through WCAG 2.
 
 ## Focus styles
 
-| Bullet                                   | Source                                                                                                                                                                                                                                    | Read                 |
-| ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
-| One project focus ring                   | House choice: per-component focus styles drift apart, and `canon inventory` reports the ring by computed style, so a one-off treatment shows as its own row                                                                               | 2026-10-18           |
-| No outline removal without a replacement | [outline](https://developer.mozilla.org/en-US/docs/Web/CSS/outline): "Assigning outline a value of 0 or none will remove the browser's default focus style. If an element can be interacted with it must have a visible focus indicator." | 2026-10-18           |
-| 3:1 ring in every theme                  | [Understanding Non-text Contrast](https://www.w3.org/WAI/WCAG22/Understanding/non-text-contrast.html): visual information needed to identify a state needs "a contrast ratio of at least 3:1 against adjacent color(s)"                   | 2026-10-18, WCAG 2.2 |
+| Bullet                                   | Source                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Read                 |
+| ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
+| One project focus ring                   | House choice: per-component focus styles drift apart, and `canon inventory` reports the ring by computed style, so a one-off treatment shows as its own row                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | 2026-10-18           |
+| No outline removal without a replacement | [outline](https://developer.mozilla.org/en-US/docs/Web/CSS/outline): "Assigning outline a value of 0 or none will remove the browser's default focus style. If an element can be interacted with it must have a visible focus indicator."                                                                                                                                                                                                                                                                                                                                                                                                                      | 2026-10-18           |
+| 3:1 ring in every theme                  | [Understanding Non-text Contrast](https://www.w3.org/WAI/WCAG22/Understanding/non-text-contrast.html): visual information needed to identify a state needs "a contrast ratio of at least 3:1 against adjacent color(s)"                                                                                                                                                                                                                                                                                                                                                                                                                                        | 2026-10-18, WCAG 2.2 |
+| Ring kept whole                          | [CSS UI 4](https://www.w3.org/TR/css-ui-4/): "By default, the outline is drawn starting just outside the border edge", and negative `outline-offset` values "must cause the outline to shrink into the border box". [MDN overflow](https://developer.mozilla.org/en-US/docs/Web/CSS/overflow): with `hidden`, "Overflow content is clipped at the element's padding box". [Understanding Focus Appearance](https://www.w3.org/WAI/WCAG22/Understanding/focus-appearance.html), Level AAA, asks for an indicator "at least as large as the area of a 2 CSS pixel thick perimeter". A partial clip passes AA, so the bullet rests on the project's own ring rule | 2026-10-23           |
 
 ## Keyboard operation
 
-| Bullet                         | Source                                                                                                                                                                                                                               | Read                 |
-| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------- |
-| Escape closes                  | [Dialog (modal) pattern](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/): "Escape : Closes the dialog", and the [combobox pattern](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/) gives Escape the same job for a popup | 2026-10-18, APG      |
-| No bare character shortcut     | [Understanding Character Key Shortcuts](https://www.w3.org/WAI/WCAG22/Understanding/character-key-shortcuts.html): a character-only shortcut needs a way to "Turn off", to "Remap", or to be "Active only on focus"                  | 2026-10-18, WCAG 2.2 |
-| Drag has a single-pointer path | [Understanding Dragging Movements](https://www.w3.org/WAI/WCAG22/Understanding/dragging-movements.html): "For any action that involves dragging, provide a simple pointer alternative"                                               | 2026-10-18, WCAG 2.2 |
+| Bullet                     | Source                                                                                                                                                                                                                                                                        | Read                 |
+| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
+| Escape closes              | [Dialog (modal) pattern](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/): "Escape : Closes the dialog", and the [combobox pattern](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/) gives Escape the same job for a popup                                          | 2026-10-18, APG      |
+| No bare character shortcut | [Understanding Character Key Shortcuts](https://www.w3.org/WAI/WCAG22/Understanding/character-key-shortcuts.html): a character-only shortcut needs a way to "Turn off", to "Remap", or to be "Active only on focus"                                                           | 2026-10-18, WCAG 2.2 |
+| No keyboard trap           | [Understanding No Keyboard Trap](https://www.w3.org/WAI/WCAG22/Understanding/no-keyboard-trap.html): "If keyboard focus can be moved to a component of the page using a keyboard interface, then focus can be moved away from that component using only a keyboard interface" | 2026-10-23, WCAG 2.2 |
 
 ## Composite widgets
 
-| Bullet                       | Source                                                                                                                                                                                                                                                             | Read            |
-| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------- |
-| One item in the tab sequence | [Developing a keyboard interface](https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/): "the tab sequence should include only one focusable element of a composite UI component", managed by "a roving tabindex" or "the aria-activedescendant property" | 2026-10-18, APG |
-| Combobox keys                | [Combobox pattern](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/): "Down Arrow : If the popup is available, moves focus into the popup", Enter accepts the focused option, and "Escape : Dismisses the popup if it is visible"                                | 2026-10-18, APG |
+| Bullet                                  | Source                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | Read            |
+| --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------- |
+| One item in the tab sequence            | [Developing a keyboard interface](https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/): "the tab sequence should include only one focusable element of a composite UI component", managed by "a roving tabindex" or "the aria-activedescendant property"                                                                                                                                                                                                         | 2026-10-18, APG |
+| Combobox keys                           | [Combobox pattern](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/): "Down Arrow : If the popup is available, moves focus into the popup", Enter accepts the focused option, and "Escape : Dismisses the popup if it is visible"                                                                                                                                                                                                                                        | 2026-10-18, APG |
+| Spinbutton keys and the pattern pointer | [Spinbutton pattern](https://www.w3.org/WAI/ARIA/apg/patterns/spinbutton/): Up Arrow "Increases the value", Down Arrow decreases it, Home and End set the limits where they exist, and Page Up is optional, "by a larger step than Up Arrow". The pointer to other patterns rests on the [APG patterns index](https://www.w3.org/WAI/ARIA/apg/patterns/), "How to build accessibility semantics into web patterns and widgets", and a bullet per pattern is declined below | 2026-10-23, APG |
 
 ## Focus management
 
@@ -37,17 +39,14 @@ The field is web accessibility, and the authorities are the W3C, through WCAG 2.
 | Focus into a dialog and back | [Dialog (modal) pattern](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/): "When a dialog opens, focus moves to an element inside the dialog", and "When a dialog closes, focus returns to the element that invoked the dialog" | 2026-10-18, APG      |
 | Focus never covered          | [Understanding Focus Not Obscured (Minimum)](https://www.w3.org/WAI/WCAG22/Understanding/focus-not-obscured-minimum.html): "the component is not entirely hidden due to author-created content"                                        | 2026-10-18, WCAG 2.2 |
 
-## Pointer targets
-
-| Bullet              | Source                                                                                                                                                                                                                                                                                                                              | Read                 |
-| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
-| 24 by 24 on the web | [Understanding Target Size (Minimum)](https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum.html): "at least 24 by 24 CSS pixels", except where "a 24 CSS pixel diameter circle is centered on the bounding box of each" and "the circles do not intersect"                                                               | 2026-10-18, WCAG 2.2 |
-| Native figures      | [Apple accessibility guidelines](https://developer.apple.com/design/human-interface-guidelines/accessibility): a default "44x44 pt" control size on iOS and iPadOS, and [Android accessibility](https://developer.android.com/guide/topics/ui/accessibility/apps): "a focusable area, or touch target size , of at least 48dpx48dp" | 2026-10-18           |
-
 ## Declined
 
 Every bullet the split removed or reshaped, grouped by why.
 
+### Left to axe or to a person
+
+- Declined a bullet per APG pattern. One pointer to the pattern page costs a line, and a bullet per pattern costs context on every component edit.
+
 ### Browser defaults
 
 - Cut the Tab, Enter, and Space bullets of the old keyboard model. A native element does each by default, and `a11y.md` already sends a session to the native element.

package/governance/ledger/ui/pointer.md

@@ -0,0 +1,24 @@
+---
+title: Pointer rule ledger
+description: Sources for governance/rules/ui/pointer.md, one row per bullet
+---
+
+# Pointer rule ledger
+
+The field is web accessibility, and the authorities are the W3C, through WCAG 2.2 and the ARIA Authoring Practices Guide, MDN for popover behavior, and the platform guidelines from Apple and Android for native targets. These bullets were split from `keyboard.md`.
+
+## Pointer actions
+
+| Bullet                                | Source                                                                                                                                                                                                                                                                                                                                                     | Read                 |
+| ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
+| Drag has a single-pointer path        | [Understanding Dragging Movements](https://www.w3.org/WAI/WCAG22/Understanding/dragging-movements.html): "For any action that involves dragging, provide a simple pointer alternative"                                                                                                                                                                     | 2026-10-18, WCAG 2.2 |
+| Outside press and focus leave dismiss | [Using the Popover API](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API/Using): you can hide the popover "by clicking outside it", and [the APG disclosure navigation example](https://www.w3.org/WAI/ARIA/apg/patterns/disclosure/examples/disclosure-navigation/): "Moving focus out of the navigation region also closes an open dropdown" | 2026-10-23           |
+| Pointer action on release             | [Understanding Pointer Cancellation](https://www.w3.org/WAI/WCAG22/Understanding/pointer-cancellation.html): one of "No Down-Event", "Abort or Undo", or "Up Reversal" holds for single-pointer functionality                                                                                                                                              | 2026-10-23, WCAG 2.2 |
+| Gestures have a single-pointer path   | [Understanding Pointer Gestures](https://www.w3.org/WAI/WCAG22/Understanding/pointer-gestures.html): "All functionality that uses multipoint or path-based gestures for operation can be operated with a single pointer without a path-based gesture"                                                                                                      | 2026-10-23, WCAG 2.2 |
+
+## Pointer targets
+
+| Bullet              | Source                                                                                                                                                                                                                                                                                                                              | Read                 |
+| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
+| 24 by 24 on the web | [Understanding Target Size (Minimum)](https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum.html): "at least 24 by 24 CSS pixels", except where "a 24 CSS pixel diameter circle is centered on the bounding box of each" and "the circles do not intersect"                                                               | 2026-10-18, WCAG 2.2 |
+| Native figures      | [Apple accessibility guidelines](https://developer.apple.com/design/human-interface-guidelines/accessibility): a default "44x44 pt" control size on iOS and iPadOS, and [Android accessibility](https://developer.android.com/guide/topics/ui/accessibility/apps): "a focusable area, or touch target size , of at least 48dpx48dp" | 2026-10-18           |