@erclx/canon 5.61.0 → 5.63.0

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 `craft` rule fires on the files the worker edits and loads `ui-craft` for behavior and `design-taste` for look.
+- The `ui-craft` capture reference 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

@@ -160,46 +160,10 @@ deps = [
 ]
 files = ["**/migrations", "**/schema.prisma", "**/*.sql"]
 
-["copy"]
-deps = ["react", "vue", "svelte", "astro", "next", "solid-js", "preact"]
-files = ["index.html", "*/index.html"]
-
-["a11y"]
-deps = ["react", "vue", "svelte", "astro", "next", "solid-js", "preact"]
-files = ["index.html", "*/index.html"]
-
-["keyboard"]
-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"]
-
-["ux-completeness"]
-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"]
-
-["link-behavior"]
-deps = ["react", "vue", "svelte", "astro", "next", "solid-js", "preact"]
-files = ["index.html", "*/index.html"]
-
-["design-taste"]
+["craft"]
 deps = ["react", "vue", "svelte", "astro", "next", "solid-js", "preact"]
 files = ["canon/DESIGN.md", "index.html", "*/index.html"]
 
-["interface-casing"]
-deps = ["react", "vue", "svelte", "astro", "next", "solid-js", "preact"]
-files = ["index.html", "*/index.html"]
-
-["motion"]
-deps = ["react", "vue", "svelte", "astro", "next", "solid-js", "preact"]
-files = ["index.html", "*/index.html"]
-
 ["design-reference"]
 deps = []
 files = ["canon/design/*/"]

package/governance/ledger/lib/test-scope.md

@@ -25,7 +25,7 @@ The field is browser test automation, and the authority is the Playwright docume
 | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
 | A script, not the suite      | House choice: a suite run answers a question about the page only through assertions written for another question, and costs the whole run                                                                   | 2026-10-18 |
 | No `fullyParallel`           | [Parallelism](https://playwright.dev/docs/test-parallel): by default "Tests in a single file are run in order, in the same worker process", and parallel tests "cannot share any state or global variables" | 2026-10-18 |
-| Pointer to `surface-capture` | House choice: a pointer to the rule that owns capture scope, claiming no practice of its own                                                                                                                | 2026-10-18 |
+| Pointer to `ui-craft`        | House choice: a pointer to the skill that owns capture scope, claiming no practice of its own                                                                                                               | 2026-10-18 |
 | Pointer to `e2e-reliability` | House choice: a pointer to the rule that owns waits and guards, claiming no practice of its own                                                                                                             | 2026-10-18 |
 
 ## Declined

package/governance/ledger/{ui → skills/ui-craft}/a11y.md

@@ -1,20 +1,21 @@
 ---
-title: Accessibility rule ledger
-description: Sources for governance/rules/ui/a11y.md, one row per bullet
+title: Accessibility reference ledger
+description: Sources for claude/skills/ui-craft/references/a11y.md, one row per bullet
 ---
 
-# Accessibility rule ledger
+# Accessibility reference ledger
 
 The field is web accessibility, and the authority is the W3C, through WCAG 2.2 and its Understanding documents, the WAI tutorials, and the ARIA notes. The keyboard and focus half of the old rule moved to `keyboard.md`, whose ledger records those bullets.
 
 ## 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/surface-capture.md → skills/ui-craft/capture.md}

@@ -1,9 +1,9 @@
 ---
-title: Surface capture rule ledger
-description: Sources for governance/rules/ui/surface-capture.md, one row per bullet
+title: Surface capture reference ledger
+description: Sources for claude/skills/ui-craft/references/capture.md, one row per bullet
 ---
 
-# Surface capture rule ledger
+# Surface capture reference ledger
 
 The rule states canon's own evidence procedure for a rendered change, so most rows are house choices naming the bug the bullet prevents. The 320 floor rests on WCAG 2.2, and each explanation the old rule carried moved into a row here.
 
@@ -16,21 +16,21 @@ The rule states canon's own evidence procedure for a rendered change, so most ro
 
 ## When to capture
 
-| Bullet                  | Source                                                                                                                                                           | Read       |
-| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
-| Preview, not dev server | House choice: a dev server injects overlays and skips the production build's transforms, so its frame differs from what ships                                    | 2026-10-18 |
-| Every theme, and again  | House choice: a defect in the dark theme passes a light-only capture, and a repair inside a shared stylesheet can cancel a rule written earlier in the same file | 2026-10-18 |
+| Bullet                                   | Source                                                                                                                                                                                                                                                                                                                           | Read       |
+| ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Preview, not dev server                  | House choice: a dev server injects overlays and skips the production build's transforms, so its frame differs from what ships                                                                                                                                                                                                    | 2026-10-18 |
+| Every theme, and again                   | House choice: a defect in the dark theme passes a light-only capture, and a repair inside a shared stylesheet can cancel a rule written earlier in the same file                                                                                                                                                                 | 2026-10-18 |
+| Read the capture before the pull request | House choice: a defect visible in the worker's own capture, such as a 20px target under the 24px bullet in `pointer.md`, reached review because nobody read the frame against the checklist first, and each review round re-runs both reviews. The skill ships with the plugin, so the bullet carries a report-if-missing clause | 2026-10-23 |
 
 ## What a capture covers
 
-| Bullet                      | Source                                                                                                                                                                                                                                        | Read                 |
-| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
-| Full page                   | House choice: a component captured alone shows none of the spacing, overflow, or stacking its page imposes on it                                                                                                                              | 2026-10-18           |
-| 320 plus breakpoints        | [Understanding Reflow](https://www.w3.org/WAI/WCAG22/Understanding/reflow.html): the criterion tests "a width equivalent to 320 CSS pixels". A 320 frame proves a frame was taken there, never that the page reflows, which `a11y.md` states. | 2026-10-18, WCAG 2.2 |
-| Chrome at both clamps       | House choice: a sidebar widened to its clamp leaves the content under the floor at a window width the criterion passes, and a frame where the chrome turned into an overlay shows none of the width it takes                                  | 2026-10-18           |
-| State case at one width     | House choice: a case driving a menu open tests the state, and repeating it at every layout width multiplies the evidence with no layout to compare                                                                                            | 2026-10-18           |
-| Drive unreachable states    | House choice: an initial render reports nothing about a menu that opens, an answer that is chosen, or a rail that tracks scrolling                                                                                                            | 2026-10-18           |
-| Case lives with the surface | House choice: a surface with no case ships uncaptured, and a case left after its surface goes fails every later capture run                                                                                                                   | 2026-10-18           |
+| Bullet                          | Source                                                                                                                                                                                                                                                                       | Read                 |
+| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
+| Full page                       | House choice: a component captured alone shows none of the spacing, overflow, or stacking its page imposes on it                                                                                                                                                             | 2026-10-18           |
+| 320 plus breakpoints            | [Understanding Reflow](https://www.w3.org/WAI/WCAG22/Understanding/reflow.html): the criterion tests "a width equivalent to 320 CSS pixels". A 320 frame proves a frame was taken there, never that the page reflows, which `a11y.md` states.                                | 2026-10-18, WCAG 2.2 |
+| Chrome at both clamps           | House choice: a sidebar widened to its clamp leaves the content under the floor at a window width the criterion passes, and a frame where the chrome turned into an overlay shows none of the width it takes                                                                 | 2026-10-18           |
+| State case at one width, driven | House choice: a case driving a menu open tests the state, and repeating it at every layout width multiplies the evidence with no layout to compare, and an initial render reports nothing about a menu that opens, an answer that is chosen, or a rail that tracks scrolling | 2026-10-18           |
+| Case lives with the surface     | House choice: a surface with no case ships uncaptured, and a case left after its surface goes fails every later capture run                                                                                                                                                  | 2026-10-18           |
 
 ## Sharing a capture
 

package/governance/ledger/skills/ui-craft/controls.md

@@ -0,0 +1,31 @@
+---
+title: UX controls reference ledger
+description: Sources for claude/skills/ui-craft/references/controls.md, one row per bullet
+---
+
+# UX controls reference ledger
+
+The field is interaction design, and the authorities are the Nielsen Norman Group, WCAG 2.2, Primer, Cloudscape, MDN, and web.dev. These bullets were split from `ux-completeness.md`.
+
+## Destructive actions
+
+| Bullet                                          | Source                                                                                                                                                                                                                                                                                                                                             | Read       |
+| ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Confirm unless undoable                         | [Confirmation dialogs](https://www.nngroup.com/articles/confirmation-dialog/): "consider a confirmation dialog before actions that cannot be undone", and "do try your best to offer undo"                                                                                                                                                         | 2026-10-18 |
+| Cancelled edit restores, never discards unasked | [Primer, Edit pattern](https://primer.style/product/scenario-patterns/edit): "Put the content back to the value it had before the edit when someone cancels", and "Confirm before discarding an edit someone has put work into". The anti-pattern is to "Discard a half-written edit because someone pressed Escape or clicked outside the editor" | 2026-10-23 |
+
+## Element states
+
+| Bullet                        | Source                                                                                                                                                                                                                                                                                             | Read       |
+| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Distinct interaction states   | [Visibility of system status](https://www.nngroup.com/articles/visibility-system-status/): "Did the system actually catch that button press", and an element with no pressed or hover response leaves the person unable to tell                                                                    | 2026-10-18 |
+| Say why a control is disabled | [Cloudscape, Disabled and read-only states](https://cloudscape.design/patterns/general/disabled-and-read-only-states/): "Use disabled reasons where adequate context is not provided through disabled button or label text", and `aria-disabled="true"` is used "so that it will remain focusable" | 2026-10-23 |
+| Declare `color-scheme`        | [MDN, color-scheme](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/color-scheme): the user agent adapts "The default colors of scrollbars and other interaction UI" and "The default colors of form controls", and the page opts in by declaring it on the `:root` element  | 2026-10-23 |
+| No intermediate flash         | [Cumulative Layout Shift](https://web.dev/articles/cls): "Unexpected layout shifts can disrupt the user experience", caused by content "dynamically added to the page before existing content"                                                                                                     | 2026-10-18 |
+
+## Hover and focus effects
+
+| Bullet                                 | Source                                                                                                                                                                                                                                                                                                                                                                                      | Read                 |
+| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
+| Hover and focus content                | [Understanding Content on Hover or Focus](https://www.w3.org/WAI/WCAG22/Understanding/content-on-hover-or-focus.html): additional content is "Dismissible" without moving hover or focus, "Hoverable" so the pointer can move over it, and "Persistent" until "the hover or focus trigger is removed, the user dismisses it, or its information is no longer valid"                         | 2026-10-23, WCAG 2.2 |
+| No change of context on focus or input | [Understanding On Focus](https://www.w3.org/WAI/WCAG22/Understanding/on-focus.html): "When any user interface component receives focus, it does not initiate a change of context". [Understanding On Input](https://www.w3.org/WAI/WCAG22/Understanding/on-input.html): changing a setting does not cause one "unless the user has been advised of the behavior before using the component" | 2026-10-23, WCAG 2.2 |

package/governance/ledger/skills/ui-craft/copy.md

@@ -0,0 +1,102 @@
+---
+title: UI copy reference ledger
+description: Sources for claude/skills/ui-craft/references/copy.md, one row per bullet
+---
+
+# UI copy reference ledger
+
+The reference joins three rules, and its sections keep their order, so each source below covers a run of them.
+
+Content design governs the first four sections, where the authority for researched interface copy is the GOV.UK Design System and its style guide.
+
+The four casing sections rest on the GOV.UK style guide, which sets sentence case for every heading and title, and canon set the label count and the scope bullets itself. The two link sections are interaction design, sourced from the Nielsen Norman Group's research on new windows and tabs.
+
+## Punctuation
+
+| Bullet                        | Source                                                                                                                                                                  | Read       |
+| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| No em dash or semicolon       | House choice: both read as generated copy in an interface, and a comma, a period, or a split sentence carries the same meaning in a shorter line                        | 2026-10-18 |
+| No trailing label punctuation | [Button](https://design-system.service.gov.uk/components/button/): every example label, such as "Start now", "Sign in", and "Continue", carries no trailing punctuation | 2026-10-18 |
+
+## Button copy
+
+| Bullet            | Source                                                                                                                                     | Read       |
+| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ---------- |
+| The action's verb | [Button](https://design-system.service.gov.uk/components/button/): "Write button text in sentence case, describing the action it performs" | 2026-10-18 |
+
+## Error messages
+
+| Bullet            | Source                                                                                                                                                                                                                                            | Read       |
+| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Say how to fix it | [Error message](https://design-system.service.gov.uk/components/error-message/): "Describe what has happened and tell them how to fix it", and "'Enter your first name' is clearer, more direct and natural than 'First name must have an entry'" | 2026-10-18 |
+| Short and plain   | [Error message](https://design-system.service.gov.uk/components/error-message/): "The message must be in plain English, use positive language and get to the point", with no "technical jargon like 'form post error'"                            | 2026-10-18 |
+
+## Placeholder text
+
+| Bullet                         | Source                                                                                                                                                                                                                                           | Read       |
+| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------- |
+| No placeholder, a hint instead | [Text input](https://design-system.service.gov.uk/components/text-input/): "Do not use placeholder text in place of a label, or for hints or examples", since "it vanishes when the user starts typing" and "not all screen readers read it out" | 2026-10-18 |
+
+## Sentence case
+
+| Bullet                   | Source                                                                                                                                                      | Read       |
+| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Sentence case            | [A to Z of GOV.UK style](https://www.gov.uk/guidance/style-guide/a-to-z-of-gov-uk-style): "Always use sentence case, even in page titles and service names" | 2026-10-18 |
+| Proper nouns keep casing | [A to Z of GOV.UK style](https://www.gov.uk/guidance/style-guide/a-to-z-of-gov-uk-style): "The exceptions to this are proper nouns"                         | 2026-10-18 |
+
+## Uppercase labels
+
+| Bullet      | Source                                                                                                                                                       | Read       |
+| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------- |
+| Label count | House choice: an uppercase eyebrow over every section is the template tell `design-taste` reaches past, and the count makes the cap checkable against a page | 2026-10-18 |
+
+## Where it applies
+
+| Bullet                 | Source                                                                                                           | Read       |
+| ---------------------- | ---------------------------------------------------------------------------------------------------------------- | ---------- |
+| Copy outside the globs | House choice: a locale file holds the same rendered strings, so title case there ships with no rule firing on it | 2026-10-18 |
+
+## Overriding
+
+| Bullet              | Source                                                                                                                                        | Read       |
+| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Depart where needed | House choice: an acronym or brand mark lowered to sentence case misnames it, the same reason GOV.UK keeps "proper nouns" as its one exception | 2026-10-18 |
+
+## Default target
+
+| Bullet                      | Source                                                                                                                                                                                                                                                                                           | Read       |
+| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------- |
+| Same tab, new tab by task   | [Opening links in new browser windows and tabs](https://www.nngroup.com/articles/new-browser-windows-and-tabs/): "There is generally one good reason to open a page in a new window, and that is that the user will need to refer to that content in order to complete a task in another window" | 2026-10-18 |
+| No blanket external new tab | [Opening links in new browser windows and tabs](https://www.nngroup.com/articles/new-browser-windows-and-tabs/): "New windows or tabs prevent the use of the Back button" and "can cause disorientation"                                                                                         | 2026-10-18 |
+
+## mailto: links
+
+| Bullet             | Source                                                                                                                                       | Read       |
+| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| `mailto:` same tab | House choice: the link opens the mail client and leaves the page in place, so `target="_blank"` only adds an empty tab the person must close | 2026-10-18 |
+
+## Declined
+
+Every bullet the rewrite removed or reshaped, grouped by why.
+
+### Contradicted by the source
+
+- Replaced "show format examples over instructions in placeholder text" with the hint text bullet, since GOV.UK says not to use a placeholder "for hints or examples".
+- Cut "reserve instructions for labels or helper text", which the new placeholder bullet now carries.
+
+### Merged or reworded
+
+- Merged the imperative verb and padded phrasing bullets. The `Save` over `Save changes` example went, since GOV.UK adds words "to better describe the action".
+- Merged "keep messages short and actionable" and "one sentence maximum" into the plain language bullet.
+- Reworded the error example to `Enter an email address`, the instruction form GOV.UK prefers over a description.
+- Folded "treat title case on every heading as a template tell" into the sentence case bullet as its reason.
+- Shortened the uppercase label bullet under 200 characters, keeping the `ceil(sections / 3)` count and the delete remedy.
+- Reworded the scope bullet from a statement of what the rule covers to the directive a session can act on.
+
+### Cut without a check
+
+- Cut "treat the count as a judgment, since a glob cannot check it", which tells a session nothing it can verify against a line.
+
+### Rewritten to what the source says
+
+- Reworded the new tab exception from "a destination that would discard in-progress work" to a page the person must consult while finishing a task, the one reason NN/g names.

package/governance/ledger/{ui → skills/ui-craft}/forms.md

@@ -1,9 +1,9 @@
 ---
-title: Forms rule ledger
-description: Sources for governance/rules/ui/forms.md, one row per bullet
+title: Forms reference ledger
+description: Sources for claude/skills/ui-craft/references/forms.md, one row per bullet
 ---
 
-# Forms rule ledger
+# Forms reference ledger
 
 The field is form design inside interaction design, and the authority for researched form patterns is the GOV.UK Design System, with WCAG 2.2 for the two authentication criteria. NN/g was read beside it and disagrees on validation timing, recorded under `## Declined`.
 

package/governance/ledger/skills/ui-craft/keyboard.md

@@ -0,0 +1,67 @@
+---
+title: Keyboard reference ledger
+description: Sources for claude/skills/ui-craft/references/keyboard.md, one row per bullet
+---
+
+# Keyboard reference ledger
+
+The field is web accessibility, and the authorities are the W3C, through WCAG 2.2 and the ARIA Authoring Practices Guide, MDN for CSS behavior, and the platform guidelines from Apple and Android for native targets. Every bullet here was split from `a11y.md`.
+
+## 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 |
+| 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 |
+| 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 |
+| 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
+
+| Bullet                       | Source                                                                                                                                                                                                                                 | Read                 |
+| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
+| 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 |
+
+## 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.
+
+### Rewritten to what the source says
+
+- Replaced "do not introduce non-standard key bindings" with the character key bullet. No reviewer can check "non-standard", and the criterion names the binding that breaks.
+- Narrowed "move focus into any overlay, popover, or dialog on open" to a dialog. The APG moves focus into a modal dialog, and a non-modal popover such as a tooltip leaves focus on its trigger.
+
+### Cut without a source or a bug class
+
+- Cut "never move focus on hover", a convention Claude already follows that no cited page takes a side on.
+
+### Merged or reworded
+
+- Merged "arrow keys navigate within composite widgets" into the roving `tabindex` bullet, which names the arrow keys.
+- Merged "Escape cancels in-progress edits" into the Escape bullet, and took in the inline confirmation case from the `ux-completeness.md` rewrite so the Escape behavior has one copy.
+- Reworded the combobox bullet to the pattern's own keys, dropping "typing filters", which the APG leaves to each autocomplete behavior.

package/governance/ledger/{ui → skills/ui-craft}/motion.md

@@ -1,9 +1,9 @@
 ---
-title: Motion rule ledger
-description: Sources for governance/rules/ui/motion.md, one row per bullet
+title: Motion reference ledger
+description: Sources for claude/skills/ui-craft/references/motion.md, one row per bullet
 ---
 
-# Motion rule ledger
+# Motion reference ledger
 
 The field is web accessibility, and the authorities are the W3C, through WCAG 2.2 and the ARIA Authoring Practices Guide, and MDN for the media feature.
 

package/governance/ledger/skills/ui-craft/pointer.md

@@ -0,0 +1,24 @@
+---
+title: Pointer reference ledger
+description: Sources for claude/skills/ui-craft/references/pointer.md, one row per bullet
+---
+
+# Pointer reference 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           |