@erclx/canon 5.44.0 → 5.45.0

package/governance/ledger/tooling/code-comments.md

@@ -0,0 +1,48 @@
+---
+title: Code comments rule ledger
+description: Sources for governance/rules/tooling/code-comments.md, one row per bullet
+---
+
+# Code comments rule ledger
+
+The field is software engineering practice for source comments, which has no spec. The authorities are the published style guides of large codebases, here Google's guides for Python, C++, TypeScript, JavaScript, and shell, read as practice from one large codebase rather than as a settlement of the field.
+
+## When a comment should exist
+
+| Bullet                                   | Source                                                                                                                                                                                                                                             | Read       |
+| ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Only a fact the code cannot carry        | [Google Python Style Guide](https://google.github.io/styleguide/pyguide.html): "The final place to have comments is in tricky parts of the code. If you're going to have to explain it at the next code review, you should comment it now."        | 2026-10-18 |
+| Do not restate the line                  | [Google Python Style Guide](https://google.github.io/styleguide/pyguide.html): "never describe the code. Assume the person reading the code knows Python (though not what you're trying to do) better than you do."                                | 2026-10-18 |
+| No comment on a self-describing function | [Google TypeScript Style Guide](https://google.github.io/styleguide/tsguide.html): "Method, parameter, and return descriptions may be omitted if they are obvious from the rest of the method's JSDoc or from the method name and type signature." | 2026-10-18 |
+| No comment moved to hit a density figure | House choice: a comment added to reach a figure restates the line beside it, and one deleted to reach it drops a contract the code cannot carry. No style guide states a density target to depart from.                                            | 2026-10-18 |
+
+## What a comment may claim
+
+| Bullet                                  | Source                                                                                                                                                                                                                                                                                                                        | Read       |
+| --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| True as written, updated in the change  | House choice: a comment describing behavior the code does not have, whether planned or since changed, reads as authoritative and misleads the next reader. Updating it in the same change puts both sides in front of one reviewer.                                                                                           | 2026-10-18 |
+| Contract, not steps                     | [Google Python Style Guide](https://google.github.io/styleguide/pyguide.html): "The docstring should describe the function's calling syntax and its semantics, but generally not its implementation details, unless those details are relevant to how the function is to be used."                                            | 2026-10-18 |
+| No person, ticket, or date in its place | House choice: a comment that only points at a person, a ticket, or a date tells the reader nothing once the person leaves or the ticket closes. Google's guides attach a bug or a name to a `TODO` beside its description, and the Python guide adds "Avoid adding TODOs that refer to an individual or team as the context". | 2026-10-18 |
+
+## What never goes in a comment
+
+| Bullet                    | Source                                                                                                                                                                                                                                                                                                                 | Read       |
+| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Delete commented-out code | House choice: commented-out code escapes the type checker and the tests, so it rots while reading as an option still open, and version control already keeps it                                                                                                                                                        | 2026-10-18 |
+| No edit history           | House choice: a comment recording the edit that made the code goes stale at the next edit and duplicates what `git log` and `git blame` hold                                                                                                                                                                           | 2026-10-18 |
+| No deferred work          | House choice: deferred work in a comment is work no tracker query finds, so nobody schedules it. [Google C++ Style Guide](https://google.github.io/styleguide/cppguide.html) asks for `TODO` comments carrying "the bug ID, name, e-mail address, or other identifier", which is Google's convention for its own code. | 2026-10-18 |
+
+## Degradation vocabulary
+
+| Bullet                         | Source                                                                                                                                                                                                                                                                                                                                                                                    | Read       |
+| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| `TODO`, `FIXME`, `HACK`, `XXX` | House choice: each term marks deferred work or a known defect in a place no tracker query reaches. Google's guides depart, asking for a `TODO` with an owner or a bug link so it "can be searched to find out how to get more details" (Python guide). Google's guide governs Google's code rather than settling the field, so this rule keeps the ban and sends the work to the tracker. | 2026-10-18 |
+
+## Declined
+
+Every bullet the rewrite removed or reshaped, grouped by why.
+
+### Merged or reworded
+
+- Merged "Let comment density follow how much of a file's behavior is decided outside that file" into the density bullet as its reason. On its own it named no line a reviewer could check.
+- Merged "State only what is true of the code as written" into the update bullet, which states the same requirement and adds when to meet it

package/governance/ledger/tooling/config-comments.md

@@ -0,0 +1,27 @@
+---
+title: Config comments rule ledger
+description: Sources for governance/rules/tooling/config-comments.md, one row per bullet
+---
+
+# Config comments rule ledger
+
+The field is comment style in configuration files. Neither the YAML spec nor the JSON-with-comments convention takes a side on what a comment says, and no published style guide covers config files the way Google's guides cover source. So every kept bullet stands on a house-choice row naming its bug class.
+
+## Comments
+
+| Bullet                                   | Source                                                                                                                                                                                                             | Read       |
+| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------- |
+| What a key does or accepts, not its name | House choice: the allowed values are set by the tool reading the file, a fact the key name does not carry, while a comment restating the name adds a line that tells the reader nothing and can drift from the key | 2026-10-18 |
+
+## Declined
+
+Every bullet the rewrite removed, grouped by why.
+
+### A convention Claude follows unprompted
+
+- Cut "Match the comment density of the surrounding file", since the Claude Code system prompt already tells the model to match the surrounding code's comment density
+
+### Cut without a source or a bug class
+
+- Cut "Keep each comment to one short line", since comment length is taste and no reviewer could point at a defect a two-line comment causes
+- Cut "Prefer a one-word category label over a sentence for a group header", as taste with no bug class

package/governance/ledger/tooling/dependencies.md

@@ -0,0 +1,38 @@
+---
+title: Dependencies rule ledger
+description: Sources for governance/rules/tooling/dependencies.md, one row per bullet
+---
+
+# Dependencies rule ledger
+
+The field is package management for JavaScript and Python projects. The authorities are each package manager's own documentation, being Bun at bun.com, npm at docs.npmjs.com, uv at docs.astral.sh, and pnpm at pnpm.io for the hoisting behavior it was built to remove.
+
+Bun's docs moved from bun.sh to bun.com, where the old paths now return a not-found page.
+
+## Declaration
+
+| Bullet                               | Source                                                                                                                                                                                                                                                                                                                                                                                                                                      | Read                        |
+| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- |
+| Declare before importing             | [Isolated installs](https://bun.com/docs/pm/isolated-installs): under isolated installs "packages can only access their explicitly declared dependencies", the default for new workspaces, so an undeclared import fails to resolve there                                                                                                                                                                                                   | 2026-10-18, Bun 1.3         |
+| Add through the package manager      | [uv, managing dependencies](https://docs.astral.sh/uv/concepts/projects/dependencies/): "uv supports modifying the project's dependencies with `uv add` and `uv remove`, but dependency metadata can also be updated by editing the `pyproject.toml` directly", and [uv, locking](https://docs.astral.sh/uv/concepts/projects/sync/): "if you add a dependency to your `pyproject.toml`, the lockfile will be considered outdated"          | 2026-10-18                  |
+| Commit the lockfile with the change  | [Bun lockfile](https://bun.com/docs/pm/lockfile): "Should it be committed to git? Yes". [package-lock.json](https://docs.npmjs.com/cli/v11/configuring-npm/package-lock-json): "This file is intended to be committed into source repositories". [bun install](https://bun.com/docs/pm/cli/install): a frozen install fails when the manifest and lockfile disagree, so "Run `bun install` and commit the updated `bun.lock`"               | 2026-10-18, Bun 1.3, npm 11 |
+| Development-only as a dev dependency | [package.json](https://docs.npmjs.com/cli/v11/configuring-npm/package-json): a module's users "probably don't want or need to download and build the external test or documentation framework that you use. In this case, it's best to map these additional items in a `devDependencies` object". [bun add](https://bun.com/docs/pm/cli/add): "Bun writes the package to `dependencies` unless you pass `--dev`, `--optional`, or `--peer`" | 2026-10-18, Bun 1.3, npm 11 |
+| No transitive-only imports           | [pnpm motivation](https://pnpm.io/motivation): under npm or Yarn Classic hoisting, "source code has access to dependencies that are not added as dependencies to the project". The import works until the parent package drops or bumps the dependency, then breaks with no change to this project's manifest                                                                                                                               | 2026-10-18                  |
+
+## Removal
+
+| Bullet                      | Source                                                                                                                                                                               | Read       |
+| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------- |
+| Remove with the last import | House choice: an entry nothing imports keeps installing on every machine and in every build, and nothing fails to point at it, so it stays until someone audits the manifest by hand | 2026-10-18 |
+
+## Declined
+
+Every bullet the rewrite removed or reshaped, grouped by why.
+
+### Contradicted by the docs
+
+- Rewrote "Never hand-edit the manifest" to re-locking after a hand edit, since uv documents editing `pyproject.toml` directly. The bug the ban guarded against is a stale lockfile.
+
+### Merged or reworded
+
+- Cut "never install without recording the result", which the declare bullet already covers, and which brought the line to 206 characters against the 200 limit

package/governance/ledger/ui/a11y.md

@@ -0,0 +1,55 @@
+---
+title: Accessibility rule ledger
+description: Sources for governance/rules/ui/a11y.md, one row per bullet
+---
+
+# Accessibility rule 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 |
+
+## Text alternatives
+
+| Bullet                                     | Source                                                                                                                                                                                                                                                           | Read       |
+| ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| `alt` on every image, empty for decoration | [Decorative images](https://www.w3.org/WAI/tutorials/images/decorative/): "a null (empty) alt text should be provided ( alt="" ) so that they can be ignored by assistive technologies"                                                                          | 2026-10-18 |
+| Meaning or action, not appearance          | [Functional images](https://www.w3.org/WAI/tutorials/images/functional/): the text "should convey the action that will be initiated (the purpose of the image), rather than a description of the image", so "print this page" rather than "(image of a) printer" | 2026-10-18 |
+
+## Contrast and color
+
+| 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 |
+| 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
+
+| Bullet                                 | Source                                                                                                                                                                                                                                                                                            | Read                 |
+| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
+| Reflow at 320                          | [Understanding Reflow](https://www.w3.org/WAI/WCAG22/Understanding/reflow.html): "without requiring scrolling in two dimensions" at "a width equivalent to 320 CSS pixels", "Except for parts of the content which require two-dimensional layout", such as "maps and diagrams" and "data tables" | 2026-10-18, WCAG 2.2 |
+| 320 is 1280 at 400 percent             | [Understanding Reflow](https://www.w3.org/WAI/WCAG22/Understanding/reflow.html): "320 CSS pixels is equivalent to a starting viewport width of 1280 CSS pixels wide at 400% zoom"                                                                                                                 | 2026-10-18, WCAG 2.2 |
+| The same floor beside resizable chrome | House choice: a panel widened to 480 in a 768 window leaves 288 for the content, under the floor at a window width the criterion passes                                                                                                                                                           | 2026-10-18           |
+
+## Declined
+
+Every bullet the rewrite removed or reshaped, grouped by why.
+
+### Moved to `keyboard.md`
+
+- Moved the focus styles, keyboard model, pointer targets, composite widgets, and focus management H2s to `keyboard.md`, whose ledger records each of those bullets.
+
+### Merged or reworded
+
+- Merged "a `<div>` with a click handler requires a role, a tab index, and keyboard handlers" into the native element bullet, which states the same choice from the other side.
+- Merged "set role on custom controls" and "synchronize state attributes with visual state" into one bullet, since both rest on the same success criterion.
+- Merged "describe the content or function, not its appearance" and "alt text for functional images should describe the action" into one bullet.
+- Shortened the reflow criterion bullet and its 1280 equivalence to fit the 200 character limit, keeping the criterion's exceptions.
+- Shortened the resizable chrome bullet and moved its worked example into this ledger's row, since it explained rather than directed.

package/governance/ledger/ui/copy.md

@@ -0,0 +1,49 @@
+---
+title: UI copy rule ledger
+description: Sources for governance/rules/ui/copy.md, one row per bullet
+---
+
+# UI copy rule ledger
+
+The field is content design, and the authority for researched interface copy is the GOV.UK Design System and its style guide.
+
+## 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 |
+
+## 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.

package/governance/ledger/ui/design-reference.md

@@ -0,0 +1,42 @@
+---
+title: Design reference rule ledger
+description: Sources for governance/rules/ui/design-reference.md, one row per bullet
+---
+
+# Design reference rule ledger
+
+The rule states canon's own design handoff, generalized from Frameboard's project rule, so every row is a house choice naming the bug the bullet prevents.
+
+## Where the design lives
+
+| Bullet                         | Source                                                                                                                                                              | Read       |
+| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Build against the tracked copy | House choice: a canvas changes under the build with no history, so a reviewer cannot tell which version a surface was built against                                 | 2026-10-18 |
+| Land a design first            | House choice: a design landing inside a feature pull request is reviewed as code, and a second feature building against it meanwhile reads a design nobody accepted | 2026-10-18 |
+| No hand edits                  | House choice: a reference edited by hand drifts from its canvas source, and the next sync overwrites the edit or reports it as a change nobody made                 | 2026-10-18 |
+| Index row before the sync      | House choice: the sync writes only the surfaces the index names, so a missing row drops the new surface's reference, and a stale row keeps a removed surface's      | 2026-10-18 |
+
+## Building against a reference
+
+| Bullet                     | Source                                                                                                                     | Read       |
+| -------------------------- | -------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Open both themes first     | House choice: a build read from the dark image alone ships a light theme nobody saw                                        | 2026-10-18 |
+| Values from the frame HTML | House choice: sizes and colors read off an image are estimates, and the frame HTML carries the exact values the design set | 2026-10-18 |
+
+## Showing the comparison
+
+| Bullet                             | Source                                                                                                                       | Read       |
+| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Reference beside capture           | House choice: a reviewer shown the build alone has nothing to compare it to, and approves a departure without seeing it      | 2026-10-18 |
+| Name each departure                | House choice: an unnamed departure reads as an accident, and the next build against the same reference repeats or reverts it | 2026-10-18 |
+| Unexplained departure is a finding | House choice: without the finding, an unexplained departure merges as the new design with no one having chosen it            | 2026-10-18 |
+
+## Naming
+
+| Bullet                  | Source                                                                                                                                 | Read       |
+| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| One folder per app part | House choice: a fixed folder and theme suffix let the sync and a reviewer find a surface's pair of references without reading an index | 2026-10-18 |
+
+## Declined
+
+The rewrite kept every bullet. Each was already under 200 characters and states a step a reviewer can check against the pull request.

package/governance/ledger/ui/design-taste.md

@@ -0,0 +1,19 @@
+---
+title: Design taste rule ledger
+description: Sources for governance/rules/ui/design-taste.md, one row per bullet
+---
+
+# Design taste rule ledger
+
+The rule is a pointer to the `design-taste` skill, which carries its own sources, so both rows are house choices naming the bug the pointer prevents.
+
+## Authority
+
+| Bullet                     | Source                                                                                                                                                                     | Read       |
+| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Load the skill             | House choice: a style edit made without the layer order or the coherence locks reaches for a model's defaults, and a second copy of them in the rule drifts from the skill | 2026-10-18 |
+| Report an unresolved skill | House choice: the rule ships with the CLI and the skill with the plugin, so a project holding governance alone would otherwise proceed silently without it                 | 2026-10-18 |
+
+## Declined
+
+The rewrite kept both bullets unchanged.

package/governance/ledger/ui/forms.md

@@ -0,0 +1,71 @@
+---
+title: Forms rule ledger
+description: Sources for governance/rules/ui/forms.md, one row per bullet
+---
+
+# Forms rule 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`.
+
+## Validation timing
+
+| Bullet                     | Source                                                                                                                                                                                                            | Read       |
+| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Validate on submit         | [Recover from validation errors](https://design-system.service.gov.uk/patterns/validation/): "Do not validate when the user moves away from a field. Wait until they try to move to the next part of the service" | 2026-10-18 |
+| Re-validate after an error | House choice: an error left in place after the input turns valid tells the person their correct answer is still wrong, and they edit a field that needed nothing                                                  | 2026-10-18 |
+
+## Submission
+
+| Bullet                            | Source                                                                                                                                                                                                                                                                                                    | Read       |
+| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Refuse with errors, never disable | [Button](https://design-system.service.gov.uk/components/button/): "Disabled buttons have poor contrast and can confuse some users, so avoid them if possible", and [validation](https://design-system.service.gov.uk/patterns/validation/) refuses "missing information, if the information is required" | 2026-10-18 |
+
+## Error placement
+
+| Bullet                                | Source                                                                                                                                                                                         | Read       |
+| ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Error next to its field               | [Error message](https://design-system.service.gov.uk/components/error-message/): "Show an error message next to the field and in the Error summary component when there is a validation error" | 2026-10-18 |
+| Cross-field error on the edited field | House choice: an error under the field the person did not touch sends them to change a value they meant, rather than the one they just entered                                                 | 2026-10-18 |
+| Focus to a linked summary             | [Error summary](https://design-system.service.gov.uk/components/error-summary/): "move keyboard focus to the error summary" and "link to each of the answers that have validation errors"      | 2026-10-18 |
+
+## Authentication and re-entry
+
+| Bullet                   | Source                                                                                                                                                                                                                                                                                         | Read                 |
+| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
+| Allow paste and autofill | [Understanding Accessible Authentication (Minimum)](https://www.w3.org/WAI/WCAG22/Understanding/accessible-authentication-minimum.html): mechanisms that satisfy it include "support for password entry by password managers" and "copy and paste to reduce the cognitive burden of re-typing" | 2026-10-18, WCAG 2.2 |
+| No redundant entry       | [Understanding Redundant Entry](https://www.w3.org/WAI/WCAG22/Understanding/redundant-entry.html): information previously entered in the same process is "either auto-populated, or available for the user to select"                                                                          | 2026-10-18, WCAG 2.2 |
+
+## Input sanitization
+
+| Bullet                        | Source                                                                                                                                                                                                                                                                    | Read       |
+| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Trim on submit                | [Recover from validation errors](https://design-system.service.gov.uk/patterns/validation/): "Use validation to ignore unwanted characters", such as spaces entered "before or after" an answer, since an error over one "would be difficult for the user to see and fix" | 2026-10-18 |
+| Say a field is case-sensitive | House choice: a value rejected or duplicated on case alone fails with no visible reason, since `Foo` and `foo` read as the same answer                                                                                                                                    | 2026-10-18 |
+
+## Derived display state
+
+| Bullet                        | Source                                                                                                                                                       | Read       |
+| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------- |
+| Reset derived state on change | House choice: a status, count, or result left from the previous input reports on a value the field no longer holds, such as a "connected" dot for an old URL | 2026-10-18 |
+
+## Declined
+
+Every bullet the rewrite removed or reshaped, grouped by why.
+
+### Contradicted by the source
+
+- Replaced "validate on blur" with validation on submit, since GOV.UK says "Do not validate when the user moves away from a field".
+- Kept GOV.UK over NN/g's [form errors guidelines](https://www.nngroup.com/articles/errors-forms-design-guidelines/), which favor validation "as soon as the user has finished filling in a field".
+- Replaced "block save when a required field is empty or invalid" with the submission bullet. Read as a disabled button, it contradicts GOV.UK.
+
+### Made redundant by the rewrite
+
+- Cut "apply the same validation timing to all fields in a form", since validating on submit gives every field one timing.
+- Cut "do not show an error on a field the user has never touched", since no error shows before a submit.
+
+### Merged or reworded
+
+- Merged "treat whitespace-only values as empty for required fields" into the submission bullet.
+- Merged the `## Submission errors` H2 into `## Error placement`, which took the form to 6 H2s.
+- Reworded "under the field" to "next to the field", since GOV.UK places the message between the label and the input.
+- Took in the status indicator reset from `ux-completeness.md`, so the reset has one copy.

package/governance/ledger/ui/interface-casing.md

@@ -0,0 +1,47 @@
+---
+title: Interface casing rule ledger
+description: Sources for governance/rules/ui/interface-casing.md, one row per bullet
+---
+
+# Interface casing rule ledger
+
+The field is content design, and the authority is the GOV.UK style guide, which sets sentence case for every heading and title. The label count and the scope bullets are canon's own.
+
+## 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 |
+
+## Declined
+
+Every bullet the rewrite removed or reshaped, grouped by why.
+
+### 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.
+
+### Merged or reworded
+
+- 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.

package/governance/ledger/ui/keyboard.md

@@ -0,0 +1,68 @@
+---
+title: Keyboard rule ledger
+description: Sources for governance/rules/ui/keyboard.md, one row per bullet
+---
+
+# Keyboard rule ledger
+
+The field is web accessibility, and the authorities are the W3C, through WCAG 2.2 and the ARIA Authoring Practices Guide, MDN for 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 |
+
+## Keyboard operation
+
+| Bullet                         | Source                                                                                                                                                                                                                               | Read                 |
+| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------- |
+| Escape closes                  | [Dialog (modal) pattern](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/): "Escape : Closes the dialog", and the [combobox pattern](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/) gives Escape the same job for a popup | 2026-10-18, APG      |
+| No bare character shortcut     | [Understanding Character Key Shortcuts](https://www.w3.org/WAI/WCAG22/Understanding/character-key-shortcuts.html): a character-only shortcut needs a way to "Turn off", to "Remap", or to be "Active only on focus"                  | 2026-10-18, WCAG 2.2 |
+| Drag has a single-pointer path | [Understanding Dragging Movements](https://www.w3.org/WAI/WCAG22/Understanding/dragging-movements.html): "For any action that involves dragging, provide a simple pointer alternative"                                               | 2026-10-18, WCAG 2.2 |
+
+## 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 |
+
+## 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 |
+
+## Pointer targets
+
+| Bullet              | Source                                                                                                                                                                                                                                                                                                                              | Read                 |
+| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
+| 24 by 24 on the web | [Understanding Target Size (Minimum)](https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum.html): "at least 24 by 24 CSS pixels", except where "a 24 CSS pixel diameter circle is centered on the bounding box of each" and "the circles do not intersect"                                                               | 2026-10-18, WCAG 2.2 |
+| Native figures      | [Apple accessibility guidelines](https://developer.apple.com/design/human-interface-guidelines/accessibility): a default "44x44 pt" control size on iOS and iPadOS, and [Android accessibility](https://developer.android.com/guide/topics/ui/accessibility/apps): "a focusable area, or touch target size , of at least 48dpx48dp" | 2026-10-18           |
+
+## Declined
+
+Every bullet the split removed or reshaped, grouped by why.
+
+### 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/link-behavior.md

@@ -0,0 +1,29 @@
+---
+title: Link behavior rule ledger
+description: Sources for governance/rules/ui/link-behavior.md, one row per bullet
+---
+
+# Link behavior rule ledger
+
+The field is interaction design, and the authority is the Nielsen Norman Group's research on new windows and tabs.
+
+## 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.
+
+### 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/motion.md

@@ -0,0 +1,33 @@
+---
+title: Motion rule ledger
+description: Sources for governance/rules/ui/motion.md, one row per bullet
+---
+
+# Motion rule 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.
+
+## Moving content
+
+| Bullet                          | Source                                                                                                                                                                                                                                                                          | Read                 |
+| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
+| Pause past five seconds         | [Understanding Pause, Stop, Hide](https://www.w3.org/WAI/WCAG22/Understanding/pause-stop-hide.html): moving information that "starts automatically", "lasts more than five seconds", and sits beside other content needs "a mechanism for the user to pause , stop, or hide it" | 2026-10-18, WCAG 2.2 |
+| Halt rotation on focus or hover | [Carousel pattern](https://www.w3.org/WAI/ARIA/apg/patterns/carousel/): a rotating carousel "Stops rotating when keyboard focus enters the carousel" and "whenever the mouse is hovering over the carousel"                                                                     | 2026-10-18, APG      |
+| Three flashes                   | [Understanding Three Flashes or Below Threshold](https://www.w3.org/WAI/WCAG22/Understanding/three-flashes-or-below-threshold.html): pages "do not contain anything that flashes more than three times in any one second period"                                                | 2026-10-18, WCAG 2.2 |
+
+## Reduced motion
+
+| Bullet                           | Source                                                                                                                                                                                                                                                         | Read                 |
+| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
+| Honor the preference             | [prefers-reduced-motion](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-reduced-motion): it detects a setting "to minimize the amount of non-essential motion", for an interface "that removes, reduces, or replaces motion-based animations" | 2026-10-18           |
+| Essential changes stay visible   | [Understanding Animation from Interactions](https://www.w3.org/WAI/WCAG22/Understanding/animation-from-interactions.html): motion can be disabled "unless the animation is essential to the functionality or the information being conveyed"                   | 2026-10-18, WCAG 2.2 |
+| No autoplay under the preference | [prefers-reduced-motion](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-reduced-motion): the setting asks the browser for an interface that "removes, reduces, or replaces motion-based animations", and a self-starting video is one         | 2026-10-18           |
+
+## Declined
+
+Every bullet the rewrite removed or reshaped, grouped by why.
+
+### Merged or reworded
+
+- Added the criterion number to the three flashes bullet, so every WCAG bullet in the rule names the criterion it rests on.
+- Reworded "do not" bans to "never" and "start no" forms, with no change of meaning.