From 73a5e70fca865844644f13ae5d662c5439a104a4 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 19 Aug 2026 13:19:14 +0000 Subject: [PATCH 1/5] improve: enhance accessibility-tester agent based on automated review - Fix pa11y guidance to use --runner axe (default htmlcs runner is WCAG 2.0-era, misses 2.1/2.2 violations) - Note axe-core version requirement (>=4.5) for reliable WCAG 2.2 rule coverage - Annotate which WCAG 2.2 new criteria are actually automatable (only 2.5.8 via axe-core target-size) - Add a fully worked example finding to anchor severity/remediation phrasing - Add document/PDF accessibility checklist item (Section 508/EAA scope) - Add forced-colors / prefers-contrast manual checklist item Automated review cycle | Co-Authored-By: Claude Code --- .../accessibility/accessibility-tester.md | 21 ++++++++++++++++++- 1 file changed, 20 insertions(+), 1 deletion(-) diff --git a/cli-tool/components/agents/accessibility/accessibility-tester.md b/cli-tool/components/agents/accessibility/accessibility-tester.md index 03ebf06a8..c0a9f74a9 100644 --- a/cli-tool/components/agents/accessibility/accessibility-tester.md +++ b/cli-tool/components/agents/accessibility/accessibility-tester.md @@ -17,10 +17,12 @@ Automated tools typically catch 30–40% of WCAG violations industry-wide (axe-c Use CLI tools to identify programmatic violations efficiently: - `npx @axe-core/cli --exit` — catches ARIA errors, missing labels, contrast failures; add `--tags wcag2a,wcag2aa,wcag21a,wcag21aa,wcag22aa` to explicitly request WCAG 2.2 rule coverage - `npx lighthouse --only-categories=accessibility` — Lighthouse accessibility score with opportunities -- `npx pa11y ` — WCAG 2.1/2.2 rule-set with detailed failure messages +- `npx pa11y --runner axe --standard WCAG2AA` — pa11y's default runner is `htmlcs` (HTML_CodeSniffer), which is WCAG 2.0-era and does not reliably surface WCAG 2.1/2.2 violations; pass `--runner axe` explicitly to get axe-core-backed, WCAG 2.1/2.2-aligned results Parse tool output and deduplicate findings before reporting. +Confirm the resolved `axe-core` version is ≥4.5 (ideally current, e.g. 4.11) before trusting WCAG 2.2 coverage — run `npx @axe-core/cli --version` — since older pinned/cached versions silently omit WCAG 2.2 rules even when `wcag22aa` is requested. + **Track 1b — Scripted interaction testing (where test infra exists)** For repeatable checks of tab order, focus trapping in modals, `aria-expanded`/`aria-selected` state changes, and focus restoration on close, use Deque's official Playwright integration rather than relying solely on the manual checklist: - `npx playwright test --grep @a11y` — run tagged accessibility interaction tests @@ -44,6 +46,8 @@ Run after automated scan to surface human-judgement violations: - Images: meaningful images have descriptive alt text; decorative images use `alt=""` - Forms: all inputs have associated labels; error messages are specific and programmatically linked - Live regions: dynamic content updates announced via `aria-live` with appropriate politeness +- Documents: linked PDFs/Office files are tagged, have a logical reading order, and include alt text for embedded images (Section 508 and EAA scope commonly extends to downloadable documents, not just rendered web pages) +- Forced colors: UI remains usable and all information is conveyed when Windows High Contrast / `forced-colors: active` is enabled; no information conveyed by background-image or box-shadow alone ## WCAG 2.2 Reference Standard @@ -65,6 +69,8 @@ WCAG 3.0 remains a W3C Working Draft (not expected before ~2029) and will not re | 3.3.8 | AA | Accessible Authentication (Minimum) | No cognitive function test required unless an alternative or assistance is provided | | 3.3.9 | AAA | Accessible Authentication (Enhanced) | No cognitive function test required at all during authentication | +Of these 9 criteria, only **2.5.8 Target Size (Minimum)** has a dedicated automated check today — axe-core's `target-size` rule (axe-core ≥4.5, only fires when the `wcag22aa` tag is requested). The remaining 8 criteria have no reliable automated coverage and must be verified via the Track 2 manual checklist. + ## ARIA Patterns and Screen Reader Guidance ### Common ARIA Patterns to Verify @@ -115,6 +121,19 @@ Remediation: Verification: ``` +**Worked example:** + +``` +ID: A11Y-001 +WCAG: 1.4.3 Contrast (Minimum) (Level AA) +Severity: High +Source: Automated (axe-core) +Element: button.checkout-submit +Issue: Button text color (#999999) on white background yields 2.85:1 contrast, below the 4.5:1 minimum for normal text. +Remediation: Change text color to #595959 or darker (yields 7:1) to meet WCAG 1.4.3. +Verification: Re-run axe-core color-contrast rule; confirm ratio ≥4.5:1 with a contrast checker. +``` + **Severity definitions:** - **Critical** — complete barrier; users with disabilities cannot complete the task - **High** — significant barrier; task completion is severely impaired From b9cf870555ff7012ae270435b8a572a03285ec43 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 19 Aug 2026 13:25:32 +0000 Subject: [PATCH 2/5] fix: cover prefers-contrast alongside forced-colors in accessibility-tester MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Addresses review feedback on PR #814 — the manual checklist tested Windows High Contrast (forced-colors) but omitted the distinct prefers-contrast media feature, which interfaces can also use for alternate high-contrast styling. Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_01QTTuf1dEt7QW83eyAPV7Lm --- .../components/agents/accessibility/accessibility-tester.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cli-tool/components/agents/accessibility/accessibility-tester.md b/cli-tool/components/agents/accessibility/accessibility-tester.md index c0a9f74a9..be1d1eaee 100644 --- a/cli-tool/components/agents/accessibility/accessibility-tester.md +++ b/cli-tool/components/agents/accessibility/accessibility-tester.md @@ -47,7 +47,7 @@ Run after automated scan to surface human-judgement violations: - Forms: all inputs have associated labels; error messages are specific and programmatically linked - Live regions: dynamic content updates announced via `aria-live` with appropriate politeness - Documents: linked PDFs/Office files are tagged, have a logical reading order, and include alt text for embedded images (Section 508 and EAA scope commonly extends to downloadable documents, not just rendered web pages) -- Forced colors: UI remains usable and all information is conveyed when Windows High Contrast / `forced-colors: active` is enabled; no information conveyed by background-image or box-shadow alone +- Contrast preferences: UI remains usable and all information is conveyed when Windows High Contrast / `forced-colors: active` or `prefers-contrast: more` is enabled; no information conveyed by background-image or box-shadow alone ## WCAG 2.2 Reference Standard From f0fe55bf1ec3a335e6b7076e5da4887769260125 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 19 Aug 2026 13:27:51 +0000 Subject: [PATCH 3/5] fix: require both forced-colors and prefers-contrast checks explicitly The previous wording used "or", allowing an audit to satisfy the checklist item by testing only one of the two distinct contrast display modes. Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_01QTTuf1dEt7QW83eyAPV7Lm --- .../components/agents/accessibility/accessibility-tester.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cli-tool/components/agents/accessibility/accessibility-tester.md b/cli-tool/components/agents/accessibility/accessibility-tester.md index be1d1eaee..cac049585 100644 --- a/cli-tool/components/agents/accessibility/accessibility-tester.md +++ b/cli-tool/components/agents/accessibility/accessibility-tester.md @@ -47,7 +47,7 @@ Run after automated scan to surface human-judgement violations: - Forms: all inputs have associated labels; error messages are specific and programmatically linked - Live regions: dynamic content updates announced via `aria-live` with appropriate politeness - Documents: linked PDFs/Office files are tagged, have a logical reading order, and include alt text for embedded images (Section 508 and EAA scope commonly extends to downloadable documents, not just rendered web pages) -- Contrast preferences: UI remains usable and all information is conveyed when Windows High Contrast / `forced-colors: active` or `prefers-contrast: more` is enabled; no information conveyed by background-image or box-shadow alone +- Contrast preferences: UI remains usable and all information is conveyed when Windows High Contrast / `forced-colors: active` and `prefers-contrast: more` are each enabled; no information conveyed by background-image or box-shadow alone ## WCAG 2.2 Reference Standard From 975dce744f33d06726519e94692fb525c92c381c Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 19 Aug 2026 13:30:41 +0000 Subject: [PATCH 4/5] fix: correct pa11y WCAG 2.2 coverage claim and axe-core version check scope MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit pa11y's axe runner maps WCAG2AA to wcag2a/wcag21a/wcag2aa/wcag21aa tags only (confirmed against pa11y/pa11y#666 and lib/runners/axe.js) — it does not include wcag22aa, and pa11y has no --tags CLI flag. Also scope the axe-core version check to the tool actually being run, since @axe-core/cli --version only reports its own bundled axe-core, not pa11y's or @axe-core/playwright's independently-resolved versions. Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_01QTTuf1dEt7QW83eyAPV7Lm --- .../components/agents/accessibility/accessibility-tester.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/cli-tool/components/agents/accessibility/accessibility-tester.md b/cli-tool/components/agents/accessibility/accessibility-tester.md index cac049585..4383f3401 100644 --- a/cli-tool/components/agents/accessibility/accessibility-tester.md +++ b/cli-tool/components/agents/accessibility/accessibility-tester.md @@ -17,11 +17,11 @@ Automated tools typically catch 30–40% of WCAG violations industry-wide (axe-c Use CLI tools to identify programmatic violations efficiently: - `npx @axe-core/cli --exit` — catches ARIA errors, missing labels, contrast failures; add `--tags wcag2a,wcag2aa,wcag21a,wcag21aa,wcag22aa` to explicitly request WCAG 2.2 rule coverage - `npx lighthouse --only-categories=accessibility` — Lighthouse accessibility score with opportunities -- `npx pa11y --runner axe --standard WCAG2AA` — pa11y's default runner is `htmlcs` (HTML_CodeSniffer), which is WCAG 2.0-era and does not reliably surface WCAG 2.1/2.2 violations; pass `--runner axe` explicitly to get axe-core-backed, WCAG 2.1/2.2-aligned results +- `npx pa11y --runner axe --standard WCAG2AA` — pa11y's default runner is `htmlcs` (HTML_CodeSniffer), which is WCAG 2.0-era; pass `--runner axe` explicitly to get axe-core-backed WCAG 2.1 results. Note: pa11y's `WCAG2AA` standard maps only to the `wcag2a`/`wcag21a`/`wcag2aa`/`wcag21aa` axe tags (no `--tags` CLI flag exists) — it does **not** cover WCAG 2.2. For WCAG 2.2 rule coverage, add `wcag22aa` to `runnerConfig.axe.runOnly` in `.pa11yrc`, or rely on the `@axe-core/cli` command above. Parse tool output and deduplicate findings before reporting. -Confirm the resolved `axe-core` version is ≥4.5 (ideally current, e.g. 4.11) before trusting WCAG 2.2 coverage — run `npx @axe-core/cli --version` — since older pinned/cached versions silently omit WCAG 2.2 rules even when `wcag22aa` is requested. +Confirm the `axe-core` version actually used by each tool is ≥4.5 (ideally current, e.g. 4.11) before trusting WCAG 2.2 coverage — `npx @axe-core/cli --version` only reports the CLI's own bundled version, not pa11y's or `@axe-core/playwright`'s independently-resolved axe-core, which can lag behind. Check each tool's bundled version separately since older pinned/cached versions silently omit WCAG 2.2 rules even when `wcag22aa` is requested. **Track 1b — Scripted interaction testing (where test infra exists)** For repeatable checks of tab order, focus trapping in modals, `aria-expanded`/`aria-selected` state changes, and focus restoration on close, use Deque's official Playwright integration rather than relying solely on the manual checklist: From c34a572661ccc3aaf9dd8b9866a043bbddddbd32 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 19 Aug 2026 13:40:56 +0000 Subject: [PATCH 5/5] fix: give a concrete command for checking per-tool axe-core versions Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_01QTTuf1dEt7QW83eyAPV7Lm --- .../components/agents/accessibility/accessibility-tester.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cli-tool/components/agents/accessibility/accessibility-tester.md b/cli-tool/components/agents/accessibility/accessibility-tester.md index 4383f3401..261b4b144 100644 --- a/cli-tool/components/agents/accessibility/accessibility-tester.md +++ b/cli-tool/components/agents/accessibility/accessibility-tester.md @@ -21,7 +21,7 @@ Use CLI tools to identify programmatic violations efficiently: Parse tool output and deduplicate findings before reporting. -Confirm the `axe-core` version actually used by each tool is ≥4.5 (ideally current, e.g. 4.11) before trusting WCAG 2.2 coverage — `npx @axe-core/cli --version` only reports the CLI's own bundled version, not pa11y's or `@axe-core/playwright`'s independently-resolved axe-core, which can lag behind. Check each tool's bundled version separately since older pinned/cached versions silently omit WCAG 2.2 rules even when `wcag22aa` is requested. +Confirm the `axe-core` version actually used by each tool is ≥4.5 (ideally current, e.g. 4.11) before trusting WCAG 2.2 coverage — `npx @axe-core/cli --version` only reports the CLI's own bundled version, not pa11y's or `@axe-core/playwright`'s independently-resolved axe-core, which can lag behind. Check each tool's bundled version separately (e.g. `npm ls axe-core` against the project's lockfile, or inspect `node_modules/axe-core/package.json`) since older pinned/cached versions silently omit WCAG 2.2 rules even when `wcag22aa` is requested. **Track 1b — Scripted interaction testing (where test infra exists)** For repeatable checks of tab order, focus trapping in modals, `aria-expanded`/`aria-selected` state changes, and focus restoration on close, use Deque's official Playwright integration rather than relying solely on the manual checklist: