codebyplan 1.5.1 → 1.9.0

package/templates/skills/cbp-checkpoint-plan/reference/dep-decision-rubric.md

@@ -0,0 +1,50 @@
+---
+scope: org-shared
+---
+
+# Dependency Decision Rubric
+
+Loaded by `/cbp-checkpoint-plan` Step 5. Use when an idea could be built by extending something already installed OR by pulling in a new dependency. The goal is a deliberate, recorded choice — never a silent `pnpm add`.
+
+## Decision tree
+
+1. **Does an installed dependency already cover this?**
+   - Check `package.json` (root + the relevant workspace) and `vendor/INDEX.md` for an existing library.
+   - Grep the codebase for prior art — the capability may already be wrapped in a util/hook/service.
+   - If yes and it fits → **extend the existing dependency**. Record a `locked` decision and stop.
+
+2. **Can the existing dependency be extended at acceptable cost?**
+   - A thin wrapper / adapter over an installed lib almost always beats a new dependency.
+   - If extension means forking or fighting the library → a new dependency may be justified; continue.
+
+3. **Is a new dependency warranted?** Weigh:
+
+   | Factor | Favors extending | Favors new dependency |
+   |--------|------------------|-----------------------|
+   | Capability gap | Existing covers ~all of it | Existing covers little / poorly |
+   | Bundle weight | Adds to an already-loaded dep | Heavy add to a lean surface (esp. mobile) |
+   | Maintenance | No new supply-chain surface | Well-maintained, widely used, typed |
+   | Vendor docs | — | A `vendor/{lib}/v{ver}/` mirror exists or can be scaffolded via `/cbp-build-vendor-doc` |
+   | Lock-in / migration | Reuses known patterns | One-way door; migration cost later |
+
+4. **Consequential choice?** If adding a new dependency meaningfully changes bundle size, security surface, or architecture, surface it to the user via AskUserQuestion with the trade-off table above. Otherwise decide inline and record it.
+
+## Record format
+
+Write the outcome as a `context.decisions[]` entry (read-merge-write the full context per Step 10):
+
+```json
+{
+  "decision": "Extend the installed date-fns rather than add dayjs",
+  "rationale": "date-fns already bundled; needed formatter is a 3-line wrapper; avoids a second date lib",
+  "locked": true
+}
+```
+
+When a new dependency IS chosen, also add a `context.dependencies[]` entry naming it and (if no vendor mirror exists) a plan step to scaffold one via `/cbp-build-vendor-doc`.
+
+## Anti-patterns
+
+- Adding a library for something the standard lib or an installed dep already does.
+- Two libraries that solve the same problem (e.g. two date libs, two state managers) — consolidate instead.
+- Deciding silently — every extend-vs-add fork must leave a recorded, locked decision so the executor and future planners can see the reasoning.

package/templates/skills/cbp-checkpoint-plan/reference/e2e-discovery-probe.md

@@ -0,0 +1,57 @@
+---
+scope: org-shared
+---
+
+# E2E Discovery Probe
+
+Loaded by `/cbp-checkpoint-plan` Step 4. The probe answers one question before you plan a fix: **is this area actually broken, and how?** It reuses `cbp-test-e2e-agent` (the sole owner of e2e execution) in `whole_checkpoint_mode` rather than introducing a second smoke-test path.
+
+## When to offer the probe
+
+Offer it only when BOTH hold:
+
+- An idea touches a UI surface — its text or the affected files mention a page / screen / route / form / component.
+- You have a concrete suspicion that an existing flow is already broken (not "let's test everything"). The probe targets a named area, not the whole app.
+
+Skip silently for backend-only / infra / `claude_only` checkpoints, or when you have no breakage suspicion.
+
+## Procedure
+
+1. **State the suspicion** — name the area, the specific pages/screens, and why you think it is broken (a stale selector, a route that 404s, a recent refactor nearby).
+2. **Confirm with the user** via AskUserQuestion — the probe needs a running dev server, so it is opt-in. Options: run the probe / skip and plan from assumption / let me name different pages.
+3. **Resolve the dev-server port** from `.codebyplan/server.json` `port_allocations[]` (pick the entry whose `server_type` matches the app, e.g. `nextjs`). If nothing is running there, ask the user to start it or skip.
+4. **Resolve `test_strategy`** — call MCP `get_repos()`, find the entry where `id === repo_id`, and read the affected app's platform + e2e framework from its `tech_stack` record. If the record has no e2e data, pass `null` for the unknown fields — the agent resolves them itself at its Step 1.5. Do NOT pass placeholder strings.
+5. **Spawn** `cbp-test-e2e-agent` with the payload below.
+6. **Interpret** the result: compare what actually failed against what you assumed. Record the delta in `context.discoveries[]` so the plan targets real defects, not imagined ones.
+
+## Spawn payload (whole_checkpoint_mode)
+
+`round_number: 0` is the documented sentinel for `whole_checkpoint_mode` in the agent's Input Contract — in that mode `files_changed` / `prior_round_files_changed` are ignored and the agent runs the `pages_affected` you give it.
+
+```yaml
+input:
+  repo_id: <repo UUID from .codebyplan/repo.json>
+  round_number: 0                 # sentinel — whole_checkpoint_mode
+  whole_checkpoint_mode: true
+  files_changed: []               # nothing changed yet — probing current state
+  prior_round_files_changed: []   # ignored under whole_checkpoint_mode; required for non-probe round_number >= 2 calls
+
+  test_strategy:
+    platform: <from tech_stack DB record>
+    e2e_framework: <playwright | maestro | webdriverio | xcuitest | vscode-test>
+  pages_affected: ["<route or screen you suspect>", ...]
+  has_auth: <true | false>
+  dev_server_port: <port from server.json, or null>
+```
+
+## What you get back
+
+The agent returns `test_results` (passed / failed / skipped + per-failure `category` and `classification_reason`) and `preflight`. For planning purposes:
+
+- `category: 'real'` failures → genuine defects; turn each into a plan step / task.
+- `category: 'env' | 'auth' | 'access' | 'flake'` → not the feature's fault; note it but do not plan a code fix around it.
+- A clean pass → your breakage suspicion was wrong; plan the actual requested change without a "fix" step you did not need.
+
+## Why reuse the agent (not a new smoke probe)
+
+`cbp-test-e2e-agent` is the declared sole owner of e2e: it auto-detects the platform, reconciles against the `tech_stack` DB record, configures the framework if missing, and classifies failures. A bespoke in-skill smoke check would duplicate that ownership and drift. The probe is a thin, opt-in caller of the existing agent.

package/templates/skills/cbp-checkpoint-plan/reference/gap-analysis-playbook.md

@@ -0,0 +1,47 @@
+---
+scope: org-shared
+---
+
+# Gap Analysis Playbook
+
+Loaded by `/cbp-checkpoint-plan` Step 3. The job: find what the raw request misses, before any task is created. Most "half-ass" outcomes come from planning only what was literally asked and ignoring the foundations it depends on or the adjacent breakage it sits next to.
+
+## Two passes
+
+### Pass 1 — in-scope gaps
+
+For each idea, compare the stated requirements against codebase reality (Glob/Grep/Read the affected area). Look for:
+
+- **Missing foundations** — the request assumes a helper / table / route / type that does not exist yet.
+- **Half-implemented patterns** — a similar feature exists but is incomplete (e.g. a hook with no test, a route with no error path, a component with no loading/empty state).
+- **Implicit requirements** — auth, validation, RLS, migration, types regen, i18n, a11y that the request did not name but the feature needs to be production-ready.
+- **Consistency debt** — the new work would diverge from an established convention unless explicitly aligned.
+
+Record each as a `context.discoveries[]` entry: `{ topic, finding }`. These become plan steps in Step 8.
+
+### Pass 2 — adjacent findings
+
+While reading the area, you will notice problems just outside the literal request (a neighbouring bug, a stale comment referencing a removed symbol, a sibling file with the same latent defect). Classify each:
+
+| Class | Meaning | Default action |
+|-------|---------|----------------|
+| `in_scope_gap` | Needed for the request to be production-ready | Add a plan step (Pass 1) |
+| `adjacent_absorbed` | Same neighbourhood, cheap to fix while here, low risk | **Pull into this checkpoint** as a task (locked policy) |
+| `adjacent_deferred` | Real but large/independent enough to warrant its own checkpoint | Record as discovery; confirm with user in Step 7 before dropping |
+
+The locked CHK-138 policy is **scope absorption**: prefer `adjacent_absorbed` over `adjacent_deferred`. Only defer when the user explicitly scopes it out in Step 7, or when absorbing it would balloon the checkpoint beyond its deadline.
+
+## What "production-ready" means here
+
+A plan is complete when, for every idea, you can answer yes to:
+
+- Does every requirement have a covering plan step?
+- Are the implicit requirements (auth / validation / migration / types / tests) either covered or explicitly deemed N/A?
+- Did Pass 2 findings get a disposition (absorbed or deferred-with-user-confirmation)?
+- Would shipping this leave any half-implemented pattern in the touched files?
+
+If any answer is no, the plan is not done — add the step or ask the question.
+
+## Output
+
+Everything from this playbook lands in `context.discoveries[]` and, after Step 8, in `plan.steps[]`. Do not create tasks here — task creation is Step 9, after dependency decisions and alternatives are settled.

package/templates/skills/cbp-checkpoint-start/SKILL.md

@@ -0,0 +1,84 @@
+---
+scope: org-shared
+name: cbp-checkpoint-start
+description: Activate a planned checkpoint and claim it for the current user/worktree, then route into task work. Runs after /cbp-checkpoint-plan (which produces tasks but never activates). Refuses to start an unplanned checkpoint.
+argument-hint: [checkpoint-number]
+effort: high
+---
+
+# Checkpoint Start Command
+
+The activation + claim gate of the checkpoint pipeline. `/cbp-checkpoint-plan` produces tasks but deliberately leaves the checkpoint `pending` and possibly unclaimed so it can sit in a team queue. This skill flips it to `active`, claims it for the caller's worktree if still open, and routes into the first task.
+
+## Pipeline
+
+```
+/cbp-checkpoint-create → /cbp-checkpoint-plan (tasks, no activation) → /cbp-checkpoint-start (activate + claim, here) → /cbp-task-start
+```
+
+## Instructions
+
+### Step 0: Parse `$ARGUMENTS`
+
+Source `repo_id` from `.codebyplan/repo.json`. Resolve caller worktree once for the whole skill: `CALLER_WT=$(npx codebyplan resolve-worktree 2>/dev/null)`.
+
+| Shape | Resolves to |
+|-------|-------------|
+| `{chk}` (e.g. `138`) | CHK-{chk} via MCP `get_checkpoints` filtered by `number` |
+| _(empty)_ | The next `pending` checkpoint that already has tasks (planned but not yet started); if several, the lowest-numbered |
+
+Malformed (non-numeric, contains `-`): surface `checkpoint-start: invalid argument` and stop.
+
+### Step 1: Load Checkpoint + Tasks
+
+Load the checkpoint (`status`, `worktree_id`, `plan`) and its tasks via MCP `get_tasks(checkpoint_id)`.
+
+### Step 2: Planned-Gate
+
+A checkpoint must be planned before it can start.
+
+- **No tasks AND empty `plan.steps[]`** → refuse: surface `CHK-NNN is not planned yet.` and auto-trigger `/cbp-checkpoint-plan {NNN}`. STOP. (An unplanned checkpoint is `worktree_id`-null, so there is nothing to own yet — always kick off planning, matching `/cbp-todo` Rule A.)
+- **Already `active`** → no activation needed; skip to Step 3 for a claim-check only, then Step 5.
+- **`pending` with tasks** → proceed.
+
+### Step 3: Claim Logic
+
+Compare the checkpoint's `worktree_id` against `CALLER_WT`:
+
+| Checkpoint `worktree_id` | Action |
+|--------------------------|--------|
+| null (left open at create) | Claim it: in Step 4 pass `worktree_id: CALLER_WT`. If `CALLER_WT` is empty, warn the checkpoint will stay unclaimed and proceed without it. |
+| equals `CALLER_WT` | Already yours — no-op. |
+| a DIFFERENT worktree | STOP. Surface: `CHK-NNN is claimed by worktree {other}; current worktree is {CALLER_WT}. If {other} is dead, a maintainer can release it via the release_assignment MCP tool, then re-run /cbp-checkpoint-start.` Do not activate. |
+
+This mirrors the CHK-104 hard-lock model — never wrest a checkpoint from a live worktree.
+
+### Step 4: Activate
+
+If the checkpoint is already `active` AND `worktree_id` already equals `CALLER_WT` (the Step 3 no-op row), skip this step entirely and proceed to Step 5 — nothing to write.
+
+Otherwise set the checkpoint `active` via MCP `update_checkpoint(checkpoint_id, status: "active"`, plus `worktree_id: CALLER_WT` when claiming per Step 3, plus `caller_worktree_id: CALLER_WT` so the hard-lock pre-guard accepts the call (omit `caller_worktree_id` only when `CALLER_WT` is empty). If the checkpoint was already `active` but a claim is still needed, skip the status write and only write `worktree_id`.
+
+### Step 5: Route
+
+Follow the close-out routing convention — auto-trigger the next same-context step, never an A/B/C menu. `{first-pending-task}` is the lowest-numbered pending task from Step 1 (not necessarily TASK-1, since additive re-planning may have completed earlier ones):
+
+- **Claimed by THIS session** (`CALLER_WT` now owns the checkpoint): auto-trigger `/cbp-task-start {chk}-{first-pending-task}` in the same context.
+- **`CALLER_WT` empty / unresolved**: surface a single directive — `Next: /cbp-task-start {chk}-{first-pending-task}` — and let the user proceed.
+
+Show a one-line confirmation before routing:
+
+```
+## Checkpoint Started
+
+**CHK-NNN**: [title]  •  **Status**: active  •  **Claimed by**: [worktree or "open"]
+**Next task**: TASK-[N] — [title]
+```
+
+## Integration
+
+- **Reads**: MCP `get_checkpoints`, `get_tasks`; `npx codebyplan resolve-worktree`
+- **Writes**: MCP `update_checkpoint` (status + worktree_id, with caller_worktree_id pre-guard)
+- **Triggered by**: `/cbp-checkpoint-plan` (auto when claimed at create), `/cbp-todo` (planned-but-pending gate), or user directly
+- **Triggers**: `/cbp-task-start` (auto when claimed), or `/cbp-checkpoint-plan` (when the checkpoint is unplanned)
+- **Never**: plans or creates tasks — that is `/cbp-checkpoint-plan`

package/templates/skills/cbp-checkpoint-update/SKILL.md

@@ -0,0 +1,115 @@
+---
+scope: org-shared
+name: cbp-checkpoint-update
+description: Update checkpoint state (activate, update context, etc.)
+argument-hint: [checkpoint-number]
+effort: high
+---
+
+# Checkpoint Update Command
+
+Update checkpoint status, context, or other fields.
+
+## Instructions
+
+### Step 0.5: Parse `$ARGUMENTS`
+
+Parse the argument:
+
+| Shape | Regex | Resolves to |
+|-------|-------|-------------|
+| `{chk}` (e.g. `108`) | `^[0-9]+$` | Target CHK-{chk} |
+| _(empty)_ | — | Use MCP `get_current_task` to find the active checkpoint |
+
+Anything else is malformed — surface this error and stop:
+
+```
+checkpoint-update: invalid argument `{value}`. Expected:
+  108    → CHK-108
+  (empty) → active checkpoint
+```
+
+#### Worked examples
+
+- `checkpoint-update 108` → CHK-108
+- `checkpoint-update` (no arg) → active checkpoint via `get_current_task`
+- `checkpoint-update abc` → error: malformed
+- `checkpoint-update 108-1` → error: malformed (that is task-start's shape)
+
+### Step 1: Get Current Checkpoint
+
+Given the parse from Step 0.5:
+
+| Parse | Resolution path |
+|-------|-----------------|
+| `{chk}` | MCP `get_checkpoints(repo_id)` → filter `number === {chk}` (must exist). |
+| _(empty)_ | MCP `get_current_task` with repo_id (and worktree_id resolved via `npx codebyplan resolve-worktree`) to find the active checkpoint. If no active checkpoint, use MCP `get_checkpoints` filtered by `pending` status to find pending ones. |
+
+### Step 1.5: Detect Entry Context (from `/cbp-task-complete` expand path)
+
+When invoked with a preamble naming `Triggered from /cbp-task-complete with intent: expand`, the user just completed the last task in the checkpoint and chose Option B "Expand checkpoint with more tasks" per `task-complete/reference/checkpoint-done-branching.md`.
+
+In that case, lead with explicit guidance:
+
+```
+You're expanding [CHK-NNN]: [title]
+The checkpoint has no remaining tasks; you chose to add more before shipping.
+
+Recommended sequence:
+  1. (here) update context — record any new decisions / discoveries / scope clarifications driving the expansion
+  2. (next) `/cbp-task-create` — add the specific tasks the expansion calls for
+
+You can skip the context update (Steps 2–3) if the expansion is purely additive with no scope change. Run `/cbp-task-create` directly in that case.
+```
+
+When invoked WITHOUT this preamble (direct user invocation), skip the guidance and proceed normally.
+
+### Step 2: Determine Update
+
+Ask user via AskUserQuestion what to update:
+- **Activate**: Change pending → active (starts development)
+- **Update context**: Add decisions, discoveries, constraints
+- **Update goal**: Refine the checkpoint goal
+- **Update deadline**: Change the deadline
+
+When the entry context is "expand from task-complete", `Update context` is the recommended default.
+
+### Step 3: Apply Update
+
+Use MCP `update_checkpoint` with the appropriate fields.
+
+**For activation:**
+```
+update_checkpoint(checkpoint_id, status: "active")
+```
+
+**For context updates:**
+Read current checkpoint to get existing context, merge new data, then:
+```
+update_checkpoint(checkpoint_id, context: merged_context)
+```
+
+### Step 4: Show Result and Route
+
+```
+## Checkpoint Updated
+
+**CHK-[NNN]**: [Title]
+**Status**: [new status]
+**Updated**: [what changed]
+```
+
+When the entry context was "expand from task-complete", append:
+
+```
+**Next:**
+Run `/cbp-task-create` to add the new task(s) under this checkpoint.
+```
+
+Otherwise, no follow-up directive — the user is back in control.
+
+## Integration
+
+- **Reads**: MCP `get_current_task`, `get_checkpoints`
+- **Writes**: MCP `update_checkpoint`
+- **Triggered by**: User directly, OR `/cbp-task-complete` Step 9c (expand path) — see `task-complete/reference/checkpoint-done-branching.md`

package/templates/skills/cbp-frontend-a11y/SKILL.md

@@ -0,0 +1,109 @@
+---
+scope: org-shared
+name: cbp-frontend-a11y
+description: Pre-implementation accessibility playbook loaded BEFORE writing UI / styling code. Produces a per-component checklist of WCAG 2.1 AA obligations from semantic HTML, ARIA roles/states, keyboard patterns, and contrast requirements.
+effort: xhigh
+---
+
+# Frontend Accessibility (Pre-Implementation Playbook)
+
+Loaded by `round-executor` Step 2.6 BEFORE any UI or styling file is written, AFTER `frontend-design` has committed to an aesthetic direction. Produces a concrete pre-write checklist — not a post-implementation audit.
+
+## When this skill fires
+
+Invoked when the wave's `skill_preloads[]` contains `"frontend-a11y"` (set by planner Phase 5.6 when `wave.files[]` includes UI-bearing paths). See `rules/frontend-accessibility-invocation.md` for the trigger gate.
+
+If none of the wave files are UI-bearing, skip — proceed to Step 3.
+
+## Phase 1: Read tokens and sibling components
+
+1. Identify design tokens from the plan's context or `frontend-design` output — colour tokens are needed for contrast checks.
+2. Glob for sibling components in the same directory as files being authored. Read 1-2 examples to understand existing `aria-*` usage, `role` attributes, keyboard handlers, focus management patterns.
+3. Note the established a11y posture: does the codebase already use `role="dialog"` patterns? Does it trap focus in modals? Are there custom keyboard handlers?
+
+## Phase 2: Detect the stack
+
+Read the planner's `test_strategy.platform` or grep for signal files:
+
+| Signal | Stack |
+|--------|-------|
+| `next.config.ts` | Next.js (App Router) |
+| `expo` in deps | React Native / Expo |
+| `tauri.conf.json` | Tauri web view |
+
+Load the matching reference doc from `reference/` (relative to this SKILL.md):
+
+- Next.js / web: read `reference/semantic-html.md`, `reference/aria-roles-states.md`, `reference/keyboard-patterns.md`, `reference/contrast-visual.md`
+- React Native: read `reference/aria-roles-states.md`, `reference/contrast-visual.md` (semantic HTML n/a for RN)
+- Tauri web view: same as Next.js / web
+
+## Phase 3: Load reference docs
+
+For the detected stack, read EACH applicable reference doc in sequence. Do not skip — the pre-write checklist is derived from their combined content.
+
+Reference docs (paths relative to this SKILL.md):
+
+- `reference/semantic-html.md` — landmark roles, heading hierarchy, element semantics, anti-patterns
+- `reference/aria-roles-states.md` — role table, aria-label vs aria-labelledby, live regions, expanded/pressed/hidden
+- `reference/keyboard-patterns.md` — focus management, tab order, Esc, arrow keys, focus traps, type-ahead
+- `reference/contrast-visual.md` — WCAG 2.1 AA ratios, focus-visible, colour-only state, reduced-motion, touch targets
+
+## Phase 4: Commit to per-component obligations
+
+For each component or element type in `wave.files[]`, derive explicit obligations from the reference docs. Group by component:
+
+```
+Component: <ComponentName> (<path>)
+  - Semantic: [e.g. "use <button> not <div onClick>"]
+  - ARIA: [e.g. "aria-expanded on disclosure trigger"]
+  - Keyboard: [e.g. "Esc closes; focus returns to trigger"]
+  - Contrast: [e.g. "border token needs 3:1 vs background — verify"]
+  - Touch: [e.g. "min 44x44px tap target on mobile"]
+```
+
+Unknown component types get the universal checklist from Phase 5.
+
+## Phase 5: Universal guidelines (applied to every component)
+
+Regardless of component type, every UI component must satisfy:
+
+1. Every interactive element is keyboard-reachable and activatable (Enter/Space for buttons, Enter for links)
+2. Focus-visible is never removed via `outline: none` without a custom indicator meeting 3:1 contrast
+3. No state conveyed via colour alone — icon + text + colour
+4. `prefers-reduced-motion` media query wraps any animation
+5. Touch targets ≥ 44×44 CSS px
+6. Images have `alt` text (decorative images use `alt=""`)
+7. Form inputs have associated `<label htmlFor>` or `aria-label`
+
+## Phase 6: Output pre-write checklist
+
+Produce a flat checklist in `round.context.frontend_a11y_checklist`:
+
+```yaml
+frontend_a11y_checklist:
+  - component: "<ComponentName>"
+    file: "<path>"
+    items:
+      - "[Semantic] use <button> not <div onClick>"
+      - "[ARIA] aria-expanded on trigger; aria-controls referencing panel id"
+      - "[Keyboard] Esc closes panel; focus returns to trigger"
+      - "[Contrast] verify focus ring token meets 3:1 vs background"
+      - "[Touch] min 44x44px on mobile breakpoint"
+```
+
+The executor consults this checklist when authoring each component in Step 3.
+
+## Output back to round-executor
+
+```yaml
+round.context.frontend_a11y_loaded: true
+round.context.frontend_a11y_checklist: [per-component checklist items]
+```
+
+## Integration
+
+- **Invoked by**: `round-executor` Step 2.6 (when `"frontend-a11y"` in `wave.skill_preloads[]`)
+- **Reads**: `reference/semantic-html.md`, `reference/aria-roles-states.md`, `reference/keyboard-patterns.md`, `reference/contrast-visual.md`
+- **Output consumed by**: `round-executor` Step 3 (implementation guidance)
+- **Pairs with**: `frontend-design` (invoked first in Step 2.6), `frontend-ui` + `frontend-ux` (post-implementation Step 3.8)
+- **Trigger rule**: `rules/frontend-accessibility-invocation.md`

package/templates/skills/cbp-frontend-a11y/reference/aria-roles-states.md

@@ -0,0 +1,130 @@
+# ARIA Roles, States, and Properties Reference
+
+**Golden rule**: Prefer native HTML semantics. ARIA fills gaps — it does not replace semantic elements. An `<input type="checkbox">` is always better than `<div role="checkbox">`.
+
+## When to Add a Role
+
+Use `role` ONLY when no native HTML element maps to the semantic need:
+
+| Pattern | Native element | ARIA role (fallback) |
+|---------|---------------|----------------------|
+| Dialog / modal | — | `role="dialog"` + `aria-modal="true"` |
+| Alerting status message | — | `role="status"` or `role="alert"` |
+| Tab list | — | `role="tablist"`, `role="tab"`, `role="tabpanel"` |
+| Custom listbox | — | `role="listbox"`, `role="option"` |
+| Progress indicator | `<progress>` | `role="progressbar"` if `<progress>` unstyled |
+| Tooltip | `title` attr (limited) | `role="tooltip"` + `aria-describedby` |
+
+## aria-label vs aria-labelledby vs aria-describedby
+
+| Attribute | Use when | Priority |
+|-----------|----------|----------|
+| `aria-labelledby` | A visible text element names this element | Highest — overrides aria-label and native label |
+| `aria-label` | No visible text label exists (icon buttons, close buttons) | Medium |
+| `aria-describedby` | Additional descriptive text supplements the label | Lowest — supplementary, not a primary name |
+
+Examples:
+```jsx
+// Icon button — no visible label
+<button aria-label="Close dialog">
+  <Icon name="x" aria-hidden="true" />
+</button>
+
+// Element labelled by visible heading
+<section aria-labelledby="billing-heading">
+  <h2 id="billing-heading">Billing</h2>
+</section>
+
+// Field with hint text
+<input id="password" aria-describedby="password-hint" />
+<span id="password-hint">Must be at least 8 characters</span>
+```
+
+## Live Regions
+
+Announce dynamic content changes to screen readers without moving focus.
+
+| Role / Attribute | Urgency | Use for |
+|-----------------|---------|---------|
+| `aria-live="polite"` | Waits for user to be idle | Status messages, form validation summaries, search result counts |
+| `aria-live="assertive"` | Interrupts immediately | Critical errors, session timeout warnings |
+| `role="status"` | Same as `aria-live="polite"` | Status messages (shorthand) |
+| `role="alert"` | Same as `aria-live="assertive"` | Error alerts (shorthand) |
+
+Anti-pattern: using `role="alert"` for non-urgent messages — screen reader interruptions are disruptive. Reserve for true emergencies.
+
+```jsx
+// Status (polite)
+<div role="status" aria-live="polite">{statusMessage}</div>
+
+// Error (assertive)
+<div role="alert">{errorMessage}</div>
+```
+
+## Common State Attributes
+
+| Attribute | Values | Use for |
+|-----------|--------|---------|
+| `aria-expanded` | `true` / `false` | Disclosure triggers (accordion, dropdown, menu) |
+| `aria-pressed` | `true` / `false` / `"mixed"` | Toggle buttons (bold, like, mute) |
+| `aria-hidden` | `true` | Decorative elements, icon-only images — removes from accessibility tree |
+| `aria-checked` | `true` / `false` / `"mixed"` | Custom checkbox/radio when not using `<input type="checkbox">` |
+| `aria-disabled` | `true` | Visually disabled but still focusable (use sparingly) |
+| `aria-selected` | `true` / `false` | Selected tab, selected option in listbox |
+| `aria-current` | `"page"` / `"step"` / `true` | Current item in nav, current step in wizard |
+
+```jsx
+// Accordion trigger
+<button
+  aria-expanded={isOpen}
+  aria-controls="panel-1"
+>
+  Section title
+</button>
+<div id="panel-1" hidden={!isOpen}>...</div>
+
+// Toggle button
+<button
+  aria-pressed={isBold}
+  onClick={() => setIsBold(!isBold)}
+>
+  Bold
+</button>
+
+// Decorative icon
+<svg aria-hidden="true" focusable="false">...</svg>
+```
+
+## aria-hidden Usage Rules
+
+- `aria-hidden="true"` removes element and ALL descendants from accessibility tree
+- Never place `aria-hidden="true"` on a focusable element (keyboard users still reach it)
+- Common correct uses: decorative icons, background images, duplicate visible text (when the accessible name comes from aria-label)
+
+```jsx
+// Correct: icon inside labelled button
+<button aria-label="Delete">
+  <TrashIcon aria-hidden="true" />
+</button>
+
+// Wrong: aria-hidden on focusable element
+<button aria-hidden="true">...</button>  // users can still Tab to it
+```
+
+## Dialog Pattern
+
+```jsx
+<dialog
+  role="dialog"
+  aria-modal="true"
+  aria-labelledby="dialog-title"
+  aria-describedby="dialog-description"
+>
+  <h2 id="dialog-title">Confirm deletion</h2>
+  <p id="dialog-description">This action cannot be undone.</p>
+  <button onClick={onConfirm}>Delete</button>
+  <button onClick={onClose}>Cancel</button>
+</dialog>
+```
+
+Focus must move INTO the dialog on open and RETURN to the trigger on close. See `keyboard-patterns.md` for focus trap implementation.