@erclx/canon 5.62.0 → 5.63.0

package/claude/skills/ui-craft/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: ui-craft
+description: Carries the behavior practice for rendered UI, being accessibility, keyboard and pointer operation, forms, motion, controls, state coverage, interface copy, and the capture a rendered change owes, routed from the kind of change to the references it reads. Use before building or changing a component, a page, a form, or any rendered surface, when judging one in review, or when asked "is this accessible", "what states does this need", "how should this form validate", "what should the button say", or "what do I capture after this change". Do NOT use for how a surface looks, being layout, type, color, and the layer order, which is `design-taste`, or for the design folder and its references, which is `design-record`.
+metadata:
+  family: build
+---
+
+# UI craft
+
+A rendered change that skips this practice ships a control a keyboard cannot reach, a list with no empty state, or an error that names the fault and never the fix, and none of it fails a build. The references below carry the rules. This body routes a change to the ones it reads.
+
+Load this before building rather than after, since a missing state or a trapped focus is cheaper to design in than to retrofit.
+
+## Read by the change
+
+Read every reference on the always row for any rendered change, then each row the change matches.
+
+| The change                                                         | Read                                  |
+| ------------------------------------------------------------------ | ------------------------------------- |
+| Any rendered change                                                | `a11y.md`, `keyboard.md`, `states.md` |
+| A click, press, drag, gesture, or popover dismissal                | `pointer.md`                          |
+| A form, a field, validation, or a sign-in step                     | `forms.md`                            |
+| An animation, transition, autoplay, or carousel                    | `motion.md`                           |
+| A destructive action, an edit cancel, or a hover or disabled state | `controls.md`                         |
+| A rendered string, heading, label, or link                         | `copy.md`                             |
+| A rendered surface has changed and is about to be handed over      | `capture.md`                          |
+
+Each name sits under `${CLAUDE_SKILL_DIR}/references/`. A row's reference is read whole, since its sections name the cases a change reaches without saying so.
+
+## Hold the floor over taste
+
+The references state a floor, and no aesthetic choice trades against it. A contrast ratio, a focus ring, or a state the design leaves out is restored before the look is judged, and `design-taste` decides the look inside that floor.
+
+## Sources
+
+Read `${CLAUDE_SKILL_DIR}/references/adopted.md` only when extending this guidance or arguing against a rule in it. It names the authorities the references draw on and where each bullet's source row sits.
+
+## What this delegates
+
+- How a surface looks, being the layer order, the coherence locks, and the defaults a model reaches for: `design-taste`
+- The accepted designs under the design folder and how a reference lands there: `design-record`
+- The visual checklist a reviewer reads beside the screenshots: `ui-checklist`
+- Reading source for roughness a rule does not state: `ux-audit`
+- Prose on the surface beyond its interface copy: the `write-human` skill

package/{governance/rules/ui → claude/skills/ui-craft/references}/a11y.md

@@ -1,13 +1,3 @@
----
-description: Semantics, text alternatives, contrast, and reflow for rendered UI
-paths:
-  - '**/*.tsx'
-  - '**/*.jsx'
-  - '**/*.astro'
-  - '**/*.html'
-  - '**/*.css'
----
-
 # Accessibility standards
 
 ## Semantics

package/claude/skills/ui-craft/references/adopted.md

@@ -0,0 +1,27 @@
+---
+title: Adopted and declined
+description: The authorities the ui-craft references draw on, and where the per-bullet source rows for each reference sit
+---
+
+# Adopted and declined
+
+Every bullet in a reference has its own source row in a ledger outside the plugin, so this record names the authorities once and points at the rows. A reader arguing against one bullet opens its ledger, and a session extending a reference adds the row there in the same change.
+
+## Authorities
+
+Each field below names the source its references cite, and a house choice covers a threshold or a scope no source states.
+
+- **Web accessibility.** The W3C's [WCAG 2.2](https://www.w3.org/TR/WCAG22/) and the [ARIA Authoring Practices Guide](https://www.w3.org/WAI/ARIA/apg/) back the accessibility, keyboard, pointer, and motion references.
+- **CSS behavior.** [MDN](https://developer.mozilla.org/en-US/docs/Web/CSS) and the CSS specifications back the focus ring, `color-scheme`, and overflow bullets.
+- **Native targets.** Apple's and Android's platform guidelines back the native touch target figures in `pointer.md`.
+- **Forms and copy.** The [GOV.UK Design System](https://design-system.service.gov.uk/) and its style guide back `forms.md` and the copy and casing sections of `copy.md`.
+- **Usability research.** The [Nielsen Norman Group](https://www.nngroup.com/articles/) backs most of `states.md`, part of `controls.md`, and the link sections of `copy.md`.
+- **Capture.** `capture.md` is a house procedure, with its reflow width taken from the WCAG reflow criterion `a11y.md` cites.
+
+## Where the rows sit
+
+The rows sit in the toolkit's own repository rather than the plugin, one ledger per reference and one table row per bullet under the H2 the bullet sits under. The toolkit's skill audit fails a reference whose bullets and rows disagree in count under any heading, and a target never carries the rows.
+
+## Declined
+
+Each ledger carries its own `## Declined` list, recording the bullets cut or reworded when the source rules were last rewritten. The move into this skill changed no bullet's wording, so it declined nothing.

package/{governance/rules/ui/surface-capture.md → claude/skills/ui-craft/references/capture.md}

@@ -1,13 +1,3 @@
----
-description: Require a capture against a running preview after a rendered surface changes
-paths:
-  - '**/routes/**/*.{tsx,jsx,vue,svelte,astro}'
-  - '**/pages/**/*.{tsx,jsx,vue,svelte,astro}'
-  - '**/app/**/page.{tsx,jsx}'
-  - '**/components/**/*.{tsx,jsx,vue,svelte,astro}'
-  - '**/*.html'
----
-
 # Surface capture standards
 
 ## What a surface is

package/{governance/rules/ui/ux-controls.md → claude/skills/ui-craft/references/controls.md}

@@ -1,13 +1,3 @@
----
-description: Destructive actions, edit cancel, and element states for interactive controls
-paths:
-  - '**/*.tsx'
-  - '**/*.jsx'
-  - '**/*.astro'
-  - '**/*.html'
-  - '**/*.css'
----
-
 # UX controls standards
 
 ## Destructive actions
@@ -21,5 +11,8 @@ paths:
 - Never flash an intermediate state, such as a light frame before a dark theme or a layout jump before data arrives. Reserve the space or settle it first.
 - Say why a control is disabled, in text beside it or a tooltip, and keep it focusable through `aria-disabled` when the reason matters.
 - Declare `color-scheme` on `:root` to match each theme, so scrollbars and form controls follow the theme instead of staying light.
+
+## Hover and focus effects
+
 - Keep content shown on hover or focus dismissible without moving the pointer, hoverable, and visible until the trigger leaves or the person dismisses it (WCAG 1.4.13).
 - Change no context, such as navigating, submitting, or moving focus, when a control gains focus or changes value, unless the person was told first (WCAG 3.2.1, 3.2.2).

package/claude/skills/ui-craft/references/copy.md

@@ -0,0 +1,45 @@
+# UI copy standards
+
+## Punctuation
+
+- Write no em dash (`—`) or semicolon in rendered copy. Use a comma or a period, or restructure the sentence.
+- Add no trailing punctuation to a button label or a short action string.
+
+## Button copy
+
+- Label a button with the verb of the action it performs, such as `Save` or `Delete`, never with filler such as `Click to delete`.
+
+## Error messages
+
+- Tell the person how to fix the error, such as `Enter an email address` over `Email is invalid`.
+- Keep an error message to one short sentence in plain language, with no technical jargon or error codes.
+
+## Placeholder text
+
+- Never use placeholder text as a label, a hint, or an example. Put a format example such as `name@example.com` in hint text under the label.
+
+## Sentence case
+
+- Use sentence case for rendered headings, labels, nav items, tab titles, and dialog titles, since title case on every heading reads as a template default.
+- Keep the original casing of a proper noun or product name, such as `GitHub`, `macOS`, or `TypeScript`.
+
+## Uppercase labels
+
+- Keep small uppercase labels above headings to `ceil(sections / 3)`, the first screen counting as one. Delete the extra labels, since position already names a section.
+
+## Where it applies
+
+- Apply the same casing to interface copy kept outside the globs, such as a locale file, which this rule never fires on.
+
+## Overriding
+
+- Depart from sentence case only where the case needs it, such as an acronym, a brand mark, or a set-in-caps identity the design chose on purpose.
+
+## Default target
+
+- Open a link in the same tab. Reserve `target="_blank"` for a page the person must consult while finishing a task in the current one.
+- Never add `target="_blank"` as a default for every external link.
+
+## mailto: links
+
+- Open a `mailto:` link in the same tab. It hands off to the mail client rather than replacing the page, so a new tab leaves an empty tab behind.

package/{governance/rules/ui → claude/skills/ui-craft/references}/forms.md

@@ -1,12 +1,3 @@
----
-description: Form validation timing, submission, error placement, and derived state for rendered forms
-paths:
-  - '**/*.tsx'
-  - '**/*.jsx'
-  - '**/*.astro'
-  - '**/*.html'
----
-
 # Form standards
 
 ## Validation timing

package/{governance/rules/ui → claude/skills/ui-craft/references}/keyboard.md

@@ -1,13 +1,3 @@
----
-description: Focus styles, keyboard operation, composite widgets, and focus management for rendered UI
-paths:
-  - '**/*.tsx'
-  - '**/*.jsx'
-  - '**/*.astro'
-  - '**/*.html'
-  - '**/*.css'
----
-
 # Keyboard and focus standards
 
 ## Focus styles

package/{governance/rules/ui → claude/skills/ui-craft/references}/motion.md

@@ -1,13 +1,3 @@
----
-description: Moving content controls and the reduced-motion preference for rendered UI
-paths:
-  - '**/*.tsx'
-  - '**/*.jsx'
-  - '**/*.astro'
-  - '**/*.html'
-  - '**/*.css'
----
-
 # Motion standards
 
 ## Moving content

package/{governance/rules/ui → claude/skills/ui-craft/references}/pointer.md

@@ -1,13 +1,3 @@
----
-description: Pointer actions, gestures, outside-press dismissal, and target size for rendered UI
-paths:
-  - '**/*.tsx'
-  - '**/*.jsx'
-  - '**/*.astro'
-  - '**/*.html'
-  - '**/*.css'
----
-
 # Pointer standards
 
 ## Pointer actions

package/{governance/rules/ui/ux-completeness.md → claude/skills/ui-craft/references/states.md}

@@ -1,13 +1,3 @@
----
-description: UX completeness checklist for interactive components and views
-paths:
-  - '**/*.tsx'
-  - '**/*.jsx'
-  - '**/*.astro'
-  - '**/*.html'
-  - '**/*.css'
----
-
 # UX completeness standards
 
 ## Feedback

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. Take what consistent interaction means from the `ui` rules in `.claude/rules/`, and skip that when the project installed none.
+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-craft` skill's references.
 
 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/claude/skills/write-human/references/adopted.md

@@ -5,7 +5,10 @@ description: Which external writing patterns this skill adopted, which it declin
 
 # Source material
 
-Two external writing skills were read as source material for this one. The first catalogs 31 patterns of machine-sounding prose. The second layers document mode, sentence construction, information density, and ambiguity prevention.
+Two external writing skills were read as source material for this one.
+
+- **[humanizer](https://github.com/blader/humanizer)** catalogs 31 patterns of machine-sounding prose
+- **An unidentified second skill** layers document mode, sentence construction, information density, and ambiguity prevention. No record of the read named it, so it carries no link.
 
 Neither was imported wholesale, and one measurement settles why. Read this before adding a rule from outside this corpus, and extend the position below rather than deriving a second one.
 

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

@@ -62,11 +62,11 @@ After a rename the new name shows as `missing` when the stamp records a stack, a
 
 ## Tooling
 
-- `canon tooling diff <stack> [target]` is the read-only comparison, exiting 1 on any difference
+- `canon tooling diff <stack> [target]` is the read-only comparison, exiting 1 on any difference, and it reads a dependency on a later major than the stack pins as `ahead`, which counts as no change
 - A `--json` refusal answers `{ ok: false, reason, message }`, so branch on the record
 - `withheld` entries are `{ rel, stack, present }`, hold every `.github/` file below the git root, and count toward no exit
 - `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.
+- `canon tooling sync <stack> [target]` writes only under `--write`. `--check` reports and exits 0, and a headless run with neither flag exits 1. It never installs over an `ahead` dependency.
 
 ### Drift cause and the write hold
 

package/docs/target/migrations.md

@@ -187,12 +187,12 @@ A web project's `e2e/screenshot.ts` is a config. It now loads `CASES` from a see
 - 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 rules a split left behind, once
+## Fold the ui rules onto one pointer, once
 
-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.
+Eleven ui rules moved unchanged into the `ui-craft` skill, being `a11y`, `keyboard`, `pointer`, `forms`, `motion`, `ux-controls`, `ux-completeness`, `surface-capture`, `copy`, `interface-casing`, and `link-behavior`. Update the plugin, then sync, which folds each one you hold and `design-taste.md` onto one `craft.md` pointer without local edits.
 
 ```bash
-canon gov install --add pointer,ux-controls --yes .
+canon gov sync .
 ```
 
 ## Group a long paths section in `CLAUDE.md`, once

package/docs/target/sync.md

@@ -45,6 +45,7 @@ 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 holds an edited config and copies each seed once
+- Tooling dependencies: a dependency on a later major than the stack pins reads as `ahead`, and sync leaves it
 - 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.
@@ -59,13 +60,13 @@ A project can also opt out of one golden file without leaving the stack. Each ve
 
 ```bash
 canon tooling decline .github/workflows/readme-screenshot.yml --reason "no screenshots here"
-canon tooling customize e2e/home.spec.ts
+canon tooling customize e2e/screenshot.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
+- A seed cannot be customized, since sync never overwrites one, and the starter `e2e/home.spec.ts` is 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.

package/docs/workflow/skill-map.md

@@ -45,6 +45,7 @@ Groups run in the order a project meets them. Every name `canon claude skills li
 | `canon:search-craft`          | Before searching outside the project               |
 | `canon:systematic-debugging`  | A test fails or a bug surfaces                     |
 | `canon:design-taste`          | Drafting or judging an interface                   |
+| `canon:ui-craft`              | Building or judging a component's behavior         |
 | `canon:ui-checklist`          | After a UI change, to list what to check           |
 
 ## Check the work before it leaves the branch

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

@@ -19,8 +19,8 @@ Canon runs a UI feature through one loop. A plan cites the design, a worker buil
 
 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.
 
-- 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.
+- 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.
 
 ## Self-check

package/governance/detect.toml

@@ -160,54 +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"]
-
-["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"]
-
-["ux-completeness"]
-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"]
-
-["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,9 +1,9 @@
 ---
-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.
 

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.
 

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

@@ -1,9 +1,9 @@
 ---
-title: UX controls rule ledger
-description: Sources for governance/rules/ui/ux-controls.md, one row per bullet
+title: UX controls reference ledger
+description: Sources for claude/skills/ui-craft/references/controls.md, one row per bullet
 ---
 
-# UX controls rule ledger
+# 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`.
 
@@ -16,11 +16,16 @@ The field is interaction design, and the authorities are the Nielsen Norman Grou
 
 ## 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                 |
 | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
-| 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           |
 | 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 |
-| 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           |

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/{ui → skills/ui-craft}/keyboard.md

@@ -1,9 +1,9 @@
 ---
-title: Keyboard rule ledger
-description: Sources for governance/rules/ui/keyboard.md, one row per bullet
+title: Keyboard reference ledger
+description: Sources for claude/skills/ui-craft/references/keyboard.md, one row per bullet
 ---
 
-# Keyboard rule ledger
+# 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`.