git:20261008.a85674e to git:20261015.f440cbb

- description: Use when reviewing changes for accessibility — WCAG conformance, axe-core findings, keyboard and screen-reader support, contrast. Triggers on "accessibility", "a11y", "WCAG", "screen reader", "无障碍", "可访问性". Not for general code quality (use code-review), machine-detectable lint (use linting), or runtime behavior bugs (use debugging).

- Accessibility is a verify-phase audit, the same shape as `security-review`: define the

- conformance target, run the automated layer, walk the manual checks, triage each finding

- to fix or accept-with-rationale. Automated tools (axe-core) catch ~30–40% of issues; the

- rest require a keyboard and screen-reader walkthrough. A page that passes axe but fails

- keyboard nav is not accessible.

-

- - Reviewing a UI change (new page, component, form, interaction) before merge.

- - A feature touches focus order, dynamic content, media, or color-only signaling.

- - Hitting a conformance requirement (WCAG 2.1/2.2 AA is the legal/commercial default; AA is the target here unless stated).

- - An automated a11y scan (axe, Lighthouse) surfaced findings to triage.

- **Not for:** general code-quality review (use `code-review`); machine-detectable lint/style (use `linting`); runtime behavior bugs (use `debugging`). a11y-review is the human-judgment + tool-assisted audit layer.

- ### 1. Confirm the conformance target and scope

-

- WCAG 2.2 AA is the default (covers 2.1 AA + new criteria). AAA is opt-in and only for specific surfaces. Scope: which pages/components are in this review? A full-site audit is different from a single-PR review — state the boundary.

-

- ### 2. Run the automated layer

-

- axe-core (or Lighthouse a11y audit) catches the machine-detectable class: missing alt text, empty buttons, insufficient contrast (ratio < 4.5:1 for text), duplicate IDs, missing form labels, invalid ARIA roles. Run it against the rendered DOM, not the source — client-rendered content needs a real browser. Capture every finding with its rule ID.

-

- ### 3. Walk the manual WCAG checks

-

- Automated tools miss the structural and interaction issues. Check per page/component — see [references/wcag-checklist.md](references/wcag-checklist.md) for the criterion-by-criterion list. The high-value manual checks:

-

- - **Keyboard** — every interactive element reachable in logical order via Tab; no keyboard traps; visible focus indicator on every focusable element.

- - **Focus management** — route changes and modal opens move focus; modals trap focus correctly and return it on close.

- - **Heading order** — `<h1>`→`<h2>`→`<h3>` without skipping levels; one `<h1>` per view.

- - **Color independence** — information isn't conveyed by color alone (error states have text/icon, not just red); links are distinguishable beyond color.

- - **Dynamic content** — `aria-live` regions announce updates; loading and error states are perceivable by AT.

- - **Media** — images have alt (decorative = `alt=""`); video has captions; audio has transcript.

-

- ### 4. Keyboard + screen-reader walkthrough

-

- Navigate the flow with the keyboard only (no mouse). Then run a screen-reader (NVDA/VoiceOver) through the critical path: land in the page, find the main content, complete the primary task, perceive errors and confirmations. This catches what axe can't: reading order vs visual order, landmark navigation, live-region announcements, form-error association.

-

- ### 5. Triage — fix or accept with rationale

- Each finding is either **fix** (the default for AA-level issues) or **accept with a documented rationale** (AAA, or a genuine constraint with a mitigation). Record the WCAG criterion, severity, and the fix or rationale per finding — never silently drop a finding.

- ## Red flags

- - A PR adding interactive UI with no keyboard-focus test; modals that don't trap or return focus; `div`/`span` used as a button without `role` and `tabindex`; error states signaled by color alone; `aria-live` missing on dynamic updates; images with meaningful content marked `alt=""`; a contrast ratio just under 4.5:1 left "because it looks fine"; automated scan green but no manual keyboard walkthrough done.

- **Output:** `docs/a11y-report.md` — findings by WCAG criterion / axe rule, severity, and the fix or accept rationale per finding. Mirrors `docs/security-report.md`. Each finding ends with the human's decision (修复/接受/驳回 + reason) recorded in the report. Format: `${CLAUDE_PLUGIN_ROOT}/references/human-audit.md`.

- - [ ] Conformance target stated (default WCAG 2.2 AA); scope boundary defined

- - [ ] axe-core / Lighthouse run against rendered DOM; every finding captured with rule ID

- - [ ] Full keyboard pass completed — every interactive element reachable, no traps, focus visible

- - [ ] Focus management checked on route changes and modals (trap + return)

- - [ ] Heading order has no skipped levels; one `<h1>` per view

- - [ ] No information conveyed by color alone; links distinguishable beyond color

- - [ ] Screen-reader walkthrough completed on the critical path

- - [ ] Every finding triaged to fix or accept-with-rationale; none silently dropped

- - [ ] `docs/a11y-report.md` produced with criterion, severity, and resolution per finding

- - [${CLAUDE_PLUGIN_ROOT}/references/engineering-principles.md](${CLAUDE_PLUGIN_ROOT}/references/engineering-principles.md) — shared discipline (verify don't assume, surgical scope)

- - [${CLAUDE_PLUGIN_ROOT}/references/human-audit.md](${CLAUDE_PLUGIN_ROOT}/references/human-audit.md) — audit-block baseline: AUD vs 确认 blocks, status lifecycle, readability bar