Claude Prompt to Audit Web Accessibility (WCAG 2.2)

What this prompt does

This prompt runs a structured WCAG 2.2 accessibility audit against real code you paste in. It covers all four POUR principles (Perceivable, Operable, Understandable, Robust) and outputs per-violation reports that include the exact criterion number, severity tier, the broken code, the corrected code, and how screen readers behave differently after the fix.

The template works because it forces the model to be accountable at the criterion level — not just "check for contrast issues" but "report against 1.4.3 Contrast Minimum with the specific contrast ratio you set." That specificity separates actionable output from vague checklists. You also get a screen reader testing script and automated testing setup wired to the tool you choose, so the audit feeds directly into your QA workflow rather than sitting in a doc nobody reads.

Because the template targets WCAG 2.2 specifically, the model will flag criteria that did not exist in 2.1: 2.4.11 Focus Appearance (minimum focus indicator size and contrast at AA), 3.3.7 Redundant Entry (no re-entering information already provided in a session), and 3.3.8 Accessible Authentication (no cognitive function tests in login flows). If you're only auditing against 2.1, set [compliance_level] to AA-2.1 so the output doesn't generate false violations on 2.2-only rules.

When to use it

• You've built a custom form, modal, or date picker and need to verify it before shipping — not after a user complaint.
• A QA engineer or client needs documented WCAG AA compliance evidence for a contract or government tender.
• You're inheriting a legacy component and need to triage what to fix first (critical vs. minor).
• You want to generate axe-core or Playwright accessibility test scaffolding for a component alongside the audit.
• You're onboarding a junior dev and want a teaching artifact that shows the before/after diff with screen reader context.
• You're targeting AAA for a healthcare, education, or public-sector audience where the bar is higher than the default AA.

Example output

For a navigation dropdown audited at AA with NVDA as the screen reader:

WCAG Violation: 4.1.2 Name, Role, Value — CRITICAL

Problem code:
  <div class="dropdown" onclick="toggle()">Menu</div>

Fixed code:
  <button class="dropdown" aria-haspopup="true" aria-expanded="false">Menu</button>

  Note: aria-expanded must be toggled dynamically in JavaScript — the HTML above
  shows the closed state only. Your toggle() function must also set
  button.setAttribute('aria-expanded', isOpen ? 'true' : 'false') on each call.
  Static markup that never flips the attribute will announce "collapsed" forever.

Screen reader behavior:
  Before: NVDA announces "Menu" with no role — user has no idea it's interactive.
  After:  NVDA announces "Menu, button, collapsed" — user can activate it and
          expect a submenu to appear; "expanded" is announced on open.

NVDA testing script:
  1. Tab to the button — confirm "Menu, button, collapsed" is announced.
  2. Press Enter — confirm "expanded" state change is announced.
  3. Arrow-key through items — confirm each item name is read in sequence.
  4. Press Escape — confirm focus returns to the trigger and "collapsed" is announced.

Keyboard navigation flow diagram: the model outputs this as an ASCII flowchart showing Tab stop order, arrow-key loops within the dropdown, and Escape/Enter paths. Useful for documentation; treat it as a first draft — verify the actual Tab order in a real browser.

Summary: 7 violations found (2 critical, 3 major, 2 minor)

Pro tips

• Set [contrast_ratio] explicitly. AA body text requires 4.5:1, large text (18pt/14pt bold) requires 3:1, and AAA text requires 7:1. If you leave it vague, the model defaults to AA body text and may miss your UI's large-heading exemptions or a stricter client requirement.
• Match [screen_reader] to your actual test environment. NVDA + Firefox, JAWS + Chrome, and VoiceOver + Safari produce different announcements for identical ARIA patterns. Audit against the combination your users actually run — a script written for NVDA Browse mode will use keyboard shortcuts that don't exist in VoiceOver.
• Paste isolated components, not full pages. The more focused the code, the more precise the violations. For a full page, split it into logical sections and run separate audits — nav shell, form, modal — then consolidate.
• Use [testing_tool]: axe-core if you want runnable test code. The prompt outputs a test file you can drop into your Playwright or Jest suite, not just a description of what to test. [testing_tool]: Lighthouse gives a CLI command instead.
• Pair with a real contrast checker after. AI-generated contrast ratios can be wrong when your colors are CSS variables or design tokens — the model sees the token name, not the computed hex. Confirm values with browser DevTools or TPGi's Colour Contrast Analyser before filing the report.