@erclx/canon 5.44.0 → 5.46.0

package/governance/rules/lib/pydantic.md

@@ -8,31 +8,29 @@ paths:
 
 ## Models
 
-- Use `pydantic.BaseModel` over `dataclass` at I/O and API boundaries.
-- Use `model_config = ConfigDict(...)` over the legacy nested `Config` class.
-- Set `extra="forbid"` on models receiving external input to prevent data pollution.
-- Use `Field(...)` for defaults, descriptions, and constraints over docstring conventions.
+- Use `pydantic.BaseModel` over a standard library `dataclass` at I/O and API boundaries, since a `dataclass` validates nothing.
+- On Pydantic 2, configure a model with `model_config = ConfigDict(...)`, never the deprecated nested `Config` class.
+- Set `extra="forbid"` on a model receiving external input, since the default ignores an unknown key silently.
+- Declare a constraint with `Field(...)`, such as `gt=0`, so validation enforces it rather than a docstring.
 
 ## Validation
 
-- Use `Model.model_validate(data)` over `Model(**data)` for untrusted dict input.
-- Use `Model.model_validate_json(s)` over `json.loads` followed by validation.
-- Use `@field_validator` over the legacy `@validator`.
-- Use `@model_validator(mode="after")` for cross-field invariants.
+- Validate an untrusted dict with `Model.model_validate(data)`, and a JSON string with `Model.model_validate_json(s)` rather than `json.loads` first.
+- On Pydantic 2, write `@field_validator` and `@model_validator`, never the deprecated `@validator` or `@root_validator`.
+- Check a cross-field invariant in `@model_validator(mode="after")`.
 
 ## Types
 
-- Use `AnyUrl`, `EmailStr`, `SecretStr`, and `PositiveInt` over hand-rolled regex constraints.
-- Use `Annotated[T, Field(...)]` over default-value `Field(...)` for reusable constrained types.
-- Do not use `Any` in fields. Reach for `JsonValue` or a `Union` of concrete types.
+- Use `SecretStr` for a credential, so its value stays out of logs and tracebacks.
+- Use a constrained type such as `PositiveInt` or `EmailStr` over a hand-rolled regex.
+- Share a constrained type as `Annotated[T, Field(...)]`.
+- Never type a field `Any`, which allows any value including `None`. Use `JsonValue` or a union of concrete types.
 
 ## Settings
 
-- Use `pydantic_settings.BaseSettings` for env-driven configuration.
-- Load environment through a single `Settings` model. Do not read `os.environ` directly elsewhere.
+- Load environment through one `pydantic_settings.BaseSettings` model. Never read `os.environ` directly elsewhere.
 
 ## Serialization
 
-- Use `model.model_dump(mode="json")` over the legacy `.dict()`.
-- Use `model.model_dump_json()` over `json.dumps(model.dict())`.
-- Use `by_alias=True` when serializing to external schemas with non-Python field names.
+- On Pydantic 2, serialize with `model_dump(mode="json")` or `model_dump_json()`, never the deprecated `.dict()` or `.json()`.
+- Pass `by_alias=True` when serializing to an external schema, since a dump ignores aliases by default.

package/governance/rules/lib/security-server.md

@@ -19,7 +19,7 @@ paths:
 
 ## Credentials
 
-- Hash passwords with a memory-hard algorithm and a per-record salt. Never store a reversible password.
+- Hash passwords with Argon2id, or scrypt or bcrypt where it is missing, and a per-password salt. Never store a reversible password.
 - Compare tokens, signatures, and password hashes with a constant-time function.
 - Expire and revoke sessions and refresh tokens on the server. Do not rely on client-side deletion.
 
@@ -27,7 +27,7 @@ paths:
 
 - Read every secret from the environment or a secret manager at runtime.
 - Never commit a secret, connection string, or private key to the repository.
-- Never return a secret, connection string, or internal hostname in a response body.
+- Never return a secret, connection string, stack trace, or internal hostname in a response body.
 
 ## Abuse limits
 
@@ -37,5 +37,5 @@ paths:
 
 ## Transport
 
-- Serve every route over TLS and reject plaintext requests.
-- Restrict CORS to an explicit origin list. Never reflect the request origin or pair a wildcard with credentials.
+- Serve every route over TLS. Fail a plaintext API request rather than redirecting it.
+- List CORS origins explicitly whenever credentials are allowed, since a wildcard is refused then. Never reflect the request origin.

package/governance/rules/lib/security-web.md

@@ -9,24 +9,20 @@ paths:
 
 # Web security standards
 
-## Link safety
-
-- Add `rel="noopener noreferrer"` to all external links with `target="_blank"`.
-
 ## Content sanitization
 
-- Sanitize all user-generated content rendered via `dangerouslySetInnerHTML` using DOMPurify or equivalent.
-- Never use `dangerouslySetInnerHTML` without sanitization.
+- Sanitize HTML with DOMPurify before passing it to `dangerouslySetInnerHTML`, `innerHTML`, or `set:html`. Never render it raw.
+- Allow only `http:` and `https:` in a user-supplied URL before rendering it in `href` or `src`.
 
 ## Input validation
 
-- Validate all URL parameters and query strings using schema validation before use.
+- Parse URL parameters and query strings through a schema before use.
 
 ## Storage and tokens
 
-- Do not store sensitive data (tokens, passwords, PII) in `localStorage` or `sessionStorage`.
-- Store authentication tokens in httpOnly cookies over exposing them to JavaScript.
+- Never store a session token, password, or personal data in `localStorage` or `sessionStorage`, which any script on the page can read.
+- Keep an authentication token in an `HttpOnly` cookie, out of reach of JavaScript.
 
 ## Third-party scripts
 
-- Audit and pin versions for all third-party scripts loaded in the browser.
+- Pin a third-party script to a version and load it with an `integrity` hash.

package/governance/rules/lib/tanstack-query.md

@@ -9,24 +9,22 @@ paths:
 
 ## Query conventions
 
-- Define query keys as `readonly` tuple constants.
-- Co-locate query keys with their query functions.
-- Encapsulate each query in a custom `use*Query` hook over calling `useQuery` inline in components.
-- Set explicit `staleTime` per query based on data volatility over relying on the default.
+- Define a query's key and function together with `queryOptions()`, and reuse that object at every call site.
+- Include every variable the query function reads in its query key.
+- Set `staleTime` per query from how often its data changes, since the default treats cached data as stale at once.
+- Throw from a query function on a response that is not `ok`, since `fetch` does not reject on an HTTP error.
 
 ## Mutations
 
-- Use `useMutation` for all write operations.
-- Never mutate data outside the mutation lifecycle.
-- Invalidate related query keys in `onSuccess` over manual cache updates unless optimistic UI is required.
-- Handle `onError` at the mutation site with user-facing feedback.
+- Write data through `useMutation`, never by calling the API from an event handler and patching the cache.
+- Invalidate the related query keys in `onSuccess` and return that promise. Reserve `setQueryData` for an optimistic update.
+- Handle `onError` at the mutation site with feedback the user sees.
 
 ## Cache management
 
-- Use `queryClient.invalidateQueries` over `queryClient.setQueryData` unless implementing optimistic updates.
-- Prefetch predictable navigations with `queryClient.prefetchQuery` at route boundaries.
+- Prefetch a predictable navigation's data in its route loader.
 
 ## Separation of concerns
 
-- Keep query functions as pure async data fetchers with no UI logic or side effects.
-- Use the query `enabled` option for conditional fetching over `useEffect`.
+- Keep a query function a pure data fetcher with no UI logic or side effects, since a background refetch runs it again.
+- Use the query `enabled` option for a conditional or dependent fetch, never `useEffect`.

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

@@ -9,9 +9,9 @@ paths:
 ## Selecting a run
 
 - Narrow an end-to-end run by spec path or by test name. Never narrow it by engine.
-- Run one named test while iterating on a behavior: `bun run test:e2e -- -g '<name>'`.
-- Run one surface while iterating on that surface: `bun run test:e2e -- e2e/<area>.spec.ts`.
-- Run `bun run test:e2e:changed` to select specs from the import graph.
+- Run `playwright test -g '<name>'` for one named test while iterating on a behavior.
+- Run `playwright test e2e/<area>.spec.ts` for one surface while iterating on that surface.
+- Run `playwright test --only-changed` to select the specs a branch changed.
 - Run the whole suite before pushing.
 - Pass `--project` in a local run only to reproduce a failure that engine has already reported. The CI matrix passes it on every job, one engine per leg, which is the gate rather than a narrowed run.
 - Do not add a script that pins a default run to one engine.
@@ -19,6 +19,6 @@ paths:
 ## Instruments
 
 - Answer a question about the running page with a script against the dev server rather than with the suite.
-- Do not enable `fullyParallel` in `playwright.config.ts`.
+- Do not enable `fullyParallel` in the Playwright config.
 - Follow `.claude/rules/canon/ui/surface-capture.md` for capture scope.
 - Follow `.claude/rules/canon/lib/e2e-reliability.md` for waits and guards.

package/governance/rules/lib/testing-go.md

@@ -13,7 +13,6 @@ paths:
 ## Framework
 
 - Use the standard `testing` package. Do not add an assertion library for what `t.Errorf` and `t.Fatalf` already state.
-- Place a test beside the code it tests, in a `_test.go` file of the same package.
 - Use an external `<pkg>_test` package when a test should see only the exported API.
 
 ## Table-driven cases
@@ -24,7 +23,7 @@ paths:
 ## Helpers and setup
 
 - Call `t.Helper()` first in every test helper.
-- Use `t.Cleanup` over `defer` for teardown a helper registers.
+- Use `t.Cleanup` over `defer` for teardown a helper registers, since a `defer` runs when the helper returns.
 - Use `t.TempDir` and `t.Setenv` over hand-rolled temp directories or environment stashes.
 - Use `net/http/httptest` over a real listener.
 

package/governance/rules/lib/testing-php.md

@@ -15,16 +15,15 @@ paths:
 
 - Use PHPUnit for all tests.
 - Declare each test class `final` and extend `PHPUnit\Framework\TestCase`.
-- Place tests under `tests/`, mirroring the `src/` namespace layout, in files named `*Test.php`.
 
 ## Attributes
 
-- Use attributes (`#[Test]`, `#[DataProvider]`, `#[CoversClass]`) over docblock annotations.
-- Use a static data provider method for table-driven cases over per-case test methods.
+- On PHPUnit 10 or later, use attributes (`#[Test]`, `#[DataProvider]`, `#[CoversClass]`) over docblock annotations, which PHPUnit 12 no longer reads.
+- Use a `public static` data provider method for table-driven cases over per-case test methods.
 
 ## Assertions and doubles
 
-- Use `assertSame` over `assertEquals`.
-- Use `expectException` over `try` and `catch` for expected exceptions.
+- Use `assertSame` over `assertEquals`, which compares with `==`.
+- Call `expectException` before the throwing call, over `try` and `catch`, for an expected exception.
 - Use `createStub` where no interaction is asserted. Reserve `createMock` for asserting a call.
 - Do not make real network calls. Use a fake or a stubbed client.

package/governance/rules/lib/testing-py.md

@@ -10,35 +10,27 @@ paths:
 
 ## Framework
 
-- Use `pytest` for all tests. Do not use `unittest.TestCase`.
-- Place tests under `tests/`, mirroring the `src/` package layout.
-- Name files `test_*.py` and test functions `test_*`.
+- Write tests as plain `pytest` functions, never `unittest.TestCase` subclasses, which lose fixtures and parametrization.
 
 ## Fixtures
 
-- Use `@pytest.fixture` over setup and teardown methods.
-- Place shared fixtures in `conftest.py` at the narrowest scope that needs them.
-- Set `scope=` (`"session"`, `"module"`, `"function"`) explicitly when reuse matters.
-- Use `tmp_path` and `monkeypatch` over hand-rolled temp directories or env stashes.
+- Write setup and teardown as a `@pytest.fixture` that yields, over setup and teardown methods.
+- Place a shared fixture in the `conftest.py` of the narrowest directory whose tests need it.
+- Widen a fixture's `scope=` past the `function` default only for state no test mutates.
+- Use `tmp_path` and `monkeypatch` over hand-rolled temp directories or environment stashes, since both undo themselves.
 
 ## Parametrize
 
 - Use `@pytest.mark.parametrize` for table-driven cases over per-case test functions.
-- Use `ids=` to label parametrized cases when their repr is unclear.
 
 ## Async
 
-- Mark async tests with `@pytest.mark.asyncio` or configure `asyncio_mode = "auto"`.
-- Do not start a fresh event loop inside tests.
+- Mark each async test `@pytest.mark.asyncio`, or set `asyncio_mode = "auto"`, since strict mode runs only marked tests.
+- Run on the event loop `pytest-asyncio` provides. Never call `asyncio.run()` or create a loop inside a test.
 
 ## Assertions and mocks
 
-- Use plain `assert` over `self.assertEqual`. Pytest rewrites assertions for readable diffs.
-- Use `pytest.raises(...)` over `try/except` for expected exceptions.
-- Use `monkeypatch.setattr` or `unittest.mock.patch` over ad hoc module rewrites.
-- Do not make real network calls. Use `responses`, `httpx_mock`, or fakes.
-
-## Conventions
-
-- Arrange, act, assert per test, with one logical assertion group.
-- Use descriptive `test_*` names that read as the assertion. Do not prefix with `should_`.
+- Use plain `assert`, which pytest rewrites to report the values, over `self.assertEqual`.
+- Use `pytest.raises(...)` over `try` and `except` for an expected exception.
+- Patch with `monkeypatch.setattr` or `unittest.mock.patch`, never by assigning a module attribute by hand.
+- Do not make real network calls. Use `responses`, `pytest-httpx`, or a fake.

package/governance/rules/lib/testing-ts.md

@@ -12,29 +12,20 @@ paths:
 ## Unit and integration
 
 - Use Vitest for unit and integration tests.
-- Co-locate unit tests with their respective components.
-- Use `userEvent` over synthetic events for interaction simulation.
-- Use MSW for network mocking. Do not mock fetch or axios manually.
-- Select elements by accessibility attributes first (`getByRole`, `getByLabelText`).
+- Simulate interaction with `userEvent` over `fireEvent`, since it refuses what a browser would, such as a click on a hidden element.
+- Mock the network with MSW. Never mock `fetch` or axios by hand, and never let a unit test make a real call.
+- Query by role or label first, such as `getByRole` and `getByLabelText`, and by test ID only when neither matches.
 
 ## End-to-end
 
 - Use Playwright for end-to-end tests.
-- Place all Playwright tests within the `e2e/` directory.
-- Never place Playwright tests inside `src/`.
-- Scope the three rules above to tests the Playwright runner executes. A Vitest test importing a browser driver to exercise project code stays beside its module, where Vitest looks for it.
-- Keep specs apart from their fixtures, page objects, and helpers inside `e2e/`. Load the `canon:codebase-layout` skill for the folder shape.
+- Place every test the Playwright runner executes under `e2e/`, never `src/`. A Vitest test that drives a browser stays beside its module.
 
 ## Timers and async
 
-- Never use `vi.useFakeTimers()` in `beforeEach` when tests use `waitFor`, `act`, or `userEvent`.
-- Scope fake timers to the individual test that needs them.
-- Restore real timers with `vi.useRealTimers()` in a matching `afterEach`.
+- Pass `advanceTimers: vi.advanceTimersByTime` to `userEvent.setup()` whenever fake timers are on.
+- Restore real timers with `vi.useRealTimers()` in `afterEach`, after `vi.runOnlyPendingTimers()`.
 
 ## Conventions
 
-- Use `.test.ts` / `.test.tsx` for unit tests.
-- Use `.spec.ts` / `.spec.tsx` for integration tests and for Playwright tests under `e2e/`.
-- Do not make real network calls in unit tests.
-- `describe()` labels use the exact identifier of the subject under test in its natural casing.
-- `it()` descriptions use "should" + sentence case.
+- Name a unit test `.test.ts` or `.test.tsx`, and an integration or Playwright test `.spec.ts` or `.spec.tsx`.

package/governance/rules/lib/zod.md

@@ -9,17 +9,15 @@ paths:
 
 ## Type inference
 
-- Use `z.infer<typeof Schema>` to generate TypeScript types (Single Source of Truth).
-- Do not manually declare interfaces that duplicate Zod schemas.
-- Do not export the runtime Schema if only the inferred Type is required by consumers.
+- Derive a schema's type with `z.infer<typeof Schema>`, never a hand-written interface that duplicates the schema.
 
 ## Boundary validation
 
-- Use `.strict()` for untrusted external API boundaries to prevent data pollution.
-- Use `.parse()` for blocking validation (env vars) and `.safeParse()` for recoverable flows (forms).
-- Restrict `z.coerce` to I/O boundaries (e.g., URL params). Never use it for internal data flow.
+- Parse untrusted input with `z.strictObject()` so an unknown key fails, never with a method the Zod 4 changelog marks legacy.
+- Narrow a schema with `.pick()` or `.omit()`, never by passing unknown keys through with `z.looseObject()`.
+- Call `.parse()` where a failure should throw, and `.safeParse()` where the caller recovers, such as a form.
+- Restrict `z.coerce` to string input at an I/O boundary such as URL params, since it converts with `String()` or `Boolean()`.
 
 ## Schema safety
 
-- Use `z.unknown()` for truly ambiguous inputs instead of `z.any()`.
-- Prefer `.strict()` at boundaries or explicit `.pick()`/`.omit()` over `.passthrough()`.
+- Use `z.unknown()` for an input of unknown shape, never `z.any()`, which infers `any` and switches off checking downstream.

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

@@ -16,14 +16,12 @@ paths:
 - Write a comment only when it records a fact the reader cannot recover from the code: an external contract, a rejected alternative, or the reason a surprising line is correct.
 - Do not restate in prose what the line beside it already says.
 - Do not comment a self-contained function whose signature and body already carry its behavior.
-- Let comment density follow how much of a file's behavior is decided outside that file. Treat density as an outcome, never as a target.
-- Do not add or delete a comment to move a file toward a density figure.
+- Do not add or delete a comment to move a file toward a density figure, since density follows how much of its behavior is decided outside it.
 
 ## What a comment may claim
 
-- State only what is true of the code as written.
+- Keep each comment true of the code as written, and update or delete one a change invalidates in that same change.
 - Describe a function's contract and its constraints, never its steps line by line.
-- Update or delete an invalidated comment in the same change that invalidates it.
 - Do not name a person, a ticket, or a date in place of the fact itself.
 
 ## What never goes in a comment

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

@@ -1,5 +1,5 @@
 ---
-description: Keep comments terse in dotfiles, config, and workflow files
+description: Keep comments in dotfiles, config, and workflow files to what a key does or accepts
 paths:
   - '**/.env*'
   - '**/.gitignore'
@@ -16,7 +16,4 @@ paths:
 
 ## Comments
 
-- Keep each comment to one short line. Do not wrap a single key in a multi-line explanation.
-- Prefer a one-word category label over a sentence for a group header.
-- Match the comment density of the surrounding file. Do not add a verbose comment next to terse ones.
 - Comment what a key does or its allowed values. Do not restate the key name.

package/governance/rules/tooling/dependencies.md

@@ -15,7 +15,7 @@ paths:
 ## Declaration
 
 - Declare a package in the project manifest before importing it anywhere in the source.
-- Add a package with the package manager command that writes the manifest and the lockfile together, such as `bun add` or `uv add`. Never hand-edit the manifest and never install without recording the result.
+- Add a package with the command that writes the manifest and the lockfile together, such as `bun add` or `uv add`. Re-lock in the same change after any hand edit to the manifest.
 - Commit the lockfile with the manifest change in the same commit.
 - Declare a package used only by tests, builds, or tooling as a development dependency.
 - Never import a package that arrives only as a transitive dependency of another package.

package/governance/rules/ui/a11y.md

@@ -1,5 +1,5 @@
 ---
-description: Keyboard interaction, focus management, and ARIA accessibility for rendered UI
+description: Semantics, text alternatives, contrast, and reflow for rendered UI
 paths:
   - '**/*.tsx'
   - '**/*.jsx'
@@ -8,56 +8,27 @@ paths:
   - '**/*.css'
 ---
 
-# Accessibility and keyboard standards
+# Accessibility standards
 
-## Focus styles
+## Semantics
 
-- All interactive elements must use the project focus ring. Do not define per-component focus styles.
-- Never apply `outline-none` without a custom focus ring in the same rule.
-- Focus ring must have 3:1 contrast against its background in both light and dark modes.
+- Use a native `<button>` or `<a>` over a `<div>` or `<span>` carrying a click handler, since the native element brings its role, focus, and keyboard activation.
+- Spell an attribute the way the file's syntax spells it, being `onclick` and `tabindex` in HTML and Astro markup and `onClick` and `tabIndex` in JSX.
+- Give a custom control the role its pattern names, such as `combobox` or `listbox`, and keep `aria-expanded`, `aria-selected`, and `aria-checked` in step with what it shows.
+- Give an interactive element with no visible text label a name through `aria-label` or `aria-labelledby`.
 
-## Keyboard interaction model
+## Text alternatives
 
-- Tab / Shift+Tab: move focus sequentially through interactive elements in DOM order.
-- Enter: activates buttons and links, submits forms.
-- Space: activates buttons and checkboxes, toggles selection in listboxes.
-- Arrow keys: navigate within composite widgets. Do not let them exit the widget.
-- Escape: closes any overlay, popover, dialog, or dropdown. Cancels in-progress edits.
-- Do not introduce non-standard key bindings for common actions.
-- Give every author-defined drag a single-pointer alternative and a keyboard path, such as move buttons or arrow-key reordering (WCAG 2.2 Dragging Movements, 2.5.7).
+- Give every `<img>` an `alt`, and use `alt=""` for a decorative image.
+- Describe what an image means, or the action an icon control takes, never its appearance. Do not prefix it with "Image of" or "Photo of".
 
-## Pointer targets
+## Contrast and color
 
-- Size a web pointer target at least 24 by 24 CSS pixels, or space it so a 24 pixel circle centered on it touches no other target (WCAG 2.2 Target Size Minimum, 2.5.8).
-- Size a native touch target at the platform figure, 44 points on iOS and 48 dp on Android. Do not apply the web figure to native, and do not apply the native figure as the web minimum.
-
-## Composite widgets
-
-- Roving tabindex for interactive collections: one item in the tab sequence at a time.
-- Combobox: arrow keys navigate options, Enter selects, Escape closes, typing filters.
-
-## Focus management
-
-- Move focus into any overlay, popover, or dialog on open. Return focus to the trigger on close.
-- Never move focus on hover. Only on keyboard input or explicit pointer activation.
-- Do not let a sticky header, footer, or overlay fully cover the focused control. Scroll it into view clear of them (WCAG 2.2 Focus Not Obscured, 2.4.11).
-
-## ARIA semantics
-
-- Use semantic HTML over custom elements: `<button>` over a `<div>` carrying a click handler, `<a>` over a `<span>` carrying one.
-- A `<div>` with a click handler requires a role, a tab index, and keyboard handlers. Use `<button>` instead.
-- Spell an attribute the way the file's syntax spells it: `onclick` and `tabindex` in HTML and Astro markup, `onClick` and `tabIndex` in JSX.
-- Set role on custom controls: `role="combobox"`, `role="listbox"`, `role="menu"`, `role="option"`.
-- Synchronize state attributes with visual state: `aria-expanded`, `aria-selected`, `aria-checked`, `aria-disabled`.
-- Add `aria-label` or `aria-labelledby` to interactive elements with no visible text label.
-- Always provide `alt` on `<img>`. Use `alt=""` for decorative images.
-- Describe the content or function of the image, not its appearance. Do not prefix with "Image of" or "Photo of".
-- Alt text for functional images (icons, buttons) should describe the action, not the graphic.
-- Give the visual boundary of a control and every graphic that carries meaning at least 3:1 contrast against adjacent colors (WCAG Non-text Contrast, 1.4.11).
-- Never make color the only carrier of a state, error, or distinction. Pair it with text, an icon, or a pattern (WCAG Use of Color, 1.4.1).
+- Give a control's visual boundary and every graphic that carries meaning at least 3:1 contrast against adjacent colors (WCAG 1.4.11).
+- Never make color the only carrier of a state, error, or distinction. Pair it with text, an icon, or a pattern (WCAG 1.4.1).
 
 ## Reflow
 
-- Let content reflow at a viewport 320 CSS pixels wide with no loss of content or function and no two-dimensional scrolling. Only content whose meaning depends on both axes, such as a data table, a map, or a diagram, may scroll sideways (WCAG Reflow, 1.4.10, Level AA).
-- Treat 320 as the criterion's own test condition rather than a device width. It is equivalent to a 1280 pixel window at 400 percent zoom, so a layout that breaks there breaks for a person who zooms.
-- Hold the same 320 floor for the content region beside persistent chrome a person can resize. The criterion measures the viewport, so this extension is this rule's own rather than the criterion's: a panel widened to 480 in a 768 window leaves 288 for the content, under the floor at a window the criterion passes. `surface-capture` states where the frame for it gets taken.
+- Let content reflow at 320 CSS pixels wide with no loss and no two-dimensional scrolling, except a data table, map, or diagram (WCAG 1.4.10).
+- Treat 320 as a 1280 pixel window at 400 percent zoom rather than a device width, so a layout breaking there breaks for a person who zooms.
+- Hold the same 320 floor for the content region beside persistent chrome a person can resize. This extends the criterion, which measures the viewport alone.

package/governance/rules/ui/copy.md

@@ -11,21 +11,18 @@ paths:
 
 ## Punctuation
 
-- Do not use em dashes (`—`) or semicolons (`;`). Use a comma or period, or restructure the sentence.
-- Do not add punctuation to button labels or short action strings.
+- 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
 
-- Use imperative verbs for actions: `Save`, `Delete`, `Connect`, `Cancel`.
-- Avoid padded phrasing: `Save` over `Save changes`, `Delete` over `Click to delete`.
+- 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
 
-- State what to do, not what went wrong: `Enter a valid email` over `Email is invalid`.
-- Keep messages short and actionable.
-- One sentence maximum.
+- 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
 
-- Show format examples over instructions: `name@example.com` over `Enter your email here`.
-- Reserve instructions for labels or helper text below the input.
+- 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.

package/governance/rules/ui/forms.md

@@ -1,5 +1,5 @@
 ---
-description: Form validation timing, save-blocking, and derived state for rendered forms
+description: Form validation timing, submission, error placement, and derived state for rendered forms
 paths:
   - '**/*.tsx'
   - '**/*.jsx'
@@ -11,35 +11,29 @@ paths:
 
 ## Validation timing
 
-- Validate on blur, not on every keystroke. Exception: realtime feedback that is explicitly part of the feature (e.g. character count, live search).
-- After a field shows its first error (on blur), re-validate on every change so the error clears as soon as the input becomes valid.
-- Apply the same validation timing to all fields in a form. Do not mix blur-only and change-only validation within one form.
-- Do not show an error on a field the user has never touched.
+- Validate when the person submits or continues, never when focus leaves a field. Realtime feedback the feature exists for, such as a character count, is the exception.
+- Re-validate a field on every change once it shows an error, so the error clears as soon as the input is valid.
 
-## Save blocking
+## Submission
 
-- Block save when any required field is empty, invalid, or has never been touched.
-- Treat whitespace-only values as empty for required fields.
+- Refuse a submit while a required field is empty, whitespace-only, or invalid, and show each error. Keep the submit button enabled rather than disabling it.
 
 ## Error placement
 
-- Show the error directly under the field that caused it, not under an unrelated field.
-- When a change to field A causes a conflict involving field B, show the error under field A (the field the user edited), not under field B.
-
-## Submission errors
-
-- When a failed submission carries several errors, move focus to a summary that links to each failing field. Keep the inline error beside each field.
+- Show each error next to the field that caused it, never under an unrelated field.
+- Show a cross-field conflict under the field the person edited, not under the field it conflicts with.
+- Move focus to an error summary linking to each failing field when a submission fails, and keep the inline error beside each field.
 
 ## Authentication and re-entry
 
-- Let a password manager fill sign-in fields and accept a pasted value. Do not block paste or autofill on a password or code field (WCAG 2.2 Accessible Authentication, 3.3.8).
-- Do not ask for information the user already gave earlier in the same flow. Prefill it or offer it for selection (WCAG 2.2 Redundant Entry, 3.3.7).
+- Let a password manager fill sign-in fields and accept a pasted value. Never block paste or autofill on a password or code field (WCAG 3.3.8).
+- Never ask again for information the person gave earlier in the same flow. Prefill it or offer it for selection (WCAG 3.3.7).
 
 ## Input sanitization
 
-- Trim leading and trailing whitespace from text inputs on blur or submit, not on every keystroke.
-- If a field is case-sensitive, surface that constraint near the field. Do not silently treat `Foo` and `foo` as different values without warning.
+- Trim leading and trailing whitespace from a text input on submit, never on every keystroke.
+- Say near a case-sensitive field that it is case-sensitive, rather than silently treating `Foo` and `foo` as different values.
 
 ## Derived display state
 
-- Reset status indicators, counts, and derived display values when their source input changes.
+- Reset a status indicator, count, or derived value to neutral when its source input changes.

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

@@ -13,19 +13,17 @@ paths:
 
 ## Sentence case
 
-- Use sentence case for all rendered interface text: headings, labels, nav items, tab titles, and dialog titles.
-- Retain original casing for proper nouns and product names: `GitHub`, `macOS`, `TypeScript`.
-- Treat title case on every heading as a template tell, since it reads as a default rather than a choice.
+- 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 one per three sections, with the first screen counting as one. More than `ceil(sections / 3)` is too many, and the fix is usually to delete the label, since a section's position already says what it is.
-- Treat the count as a judgment, since a glob cannot check it.
+- 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
 
-- The rule covers markup, MDX, and content modules under a `content/` folder. Copy kept elsewhere, such as a locale file, is not reached, so apply the same casing there without the rule firing.
+- 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 where the case needs it, such as an acronym, a brand mark, or a set-in-caps identity the design chose on purpose.
+- 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.

package/governance/rules/ui/keyboard.md

@@ -0,0 +1,38 @@
+---
+description: Focus styles, keyboard operation, focus management, and pointer targets for rendered UI
+paths:
+  - '**/*.tsx'
+  - '**/*.jsx'
+  - '**/*.astro'
+  - '**/*.html'
+  - '**/*.css'
+---
+
+# Keyboard and focus standards
+
+## Focus styles
+
+- Style focus through the project's one focus ring rather than a per-component focus style.
+- Never set `outline: none` or `outline-none` without a replacement focus indicator in the same rule.
+- Give the focus ring 3:1 contrast against its background in every theme the project ships.
+
+## Keyboard operation
+
+- Close a dialog, popover, menu, or inline confirmation on Escape, and cancel an in-progress edit the same way.
+- Bind no single printable character as a shortcut unless a person can turn it off or remap it, or it fires only while its control has focus (WCAG 2.1.4).
+- Give every author-defined drag a single-pointer alternative and a keyboard path, such as move buttons or arrow-key reordering (WCAG 2.5.7).
+
+## Composite widgets
+
+- Keep one item of a composite widget in the tab sequence, and move between its items with the arrow keys through roving `tabindex` or `aria-activedescendant`.
+- Open a combobox popup on Down Arrow, accept the focused option on Enter, and close the popup on Escape without changing the value.
+
+## Focus management
+
+- Move focus into a dialog when it opens, and return it to the element that opened it when it closes.
+- Never let a sticky header, footer, or overlay fully cover the focused control. Scroll it clear of them (WCAG 2.4.11).
+
+## Pointer targets
+
+- Size a web pointer target at least 24 by 24 CSS pixels, or space it so a 24 pixel circle centered on it touches no other target (WCAG 2.5.8).
+- Size a native touch target at the platform figure, 44 points on iOS and 48 dp on Android, and never swap the web and native figures.