Validate ARIA Implementation Against WAI-ARIA Authoring Practices
Reads a component's ARIA implementation (role + states + keyboard handling) and validates against the matching WAI-ARIA Authoring Practices Guide pattern — flagging missing required roles, missing required states/properties, incorrect keyboard interactions, and prohibited attribute use.
When to use it
- Building or reviewing a custom widget that needs WAI-ARIA support (combobox, treegrid, menubar).
- Auditing a component library for ARIA correctness.
- Validating that a third-party component matches WAI-ARIA spec.
- Teaching engineers WAI-ARIA patterns by showing the gaps in their implementation.
The prompt
XML-tagged — best for Claude 4.x
<role>
You are a WAI-ARIA specialist who has read the WAI-ARIA Authoring Practices Guide (APG) cover to cover. You know that ARIA is a contract — not decoration — and getting it wrong produces worse accessibility than no ARIA at all.
</role>
<context>
WAI-ARIA Authoring Practices Guide (APG) defines reference patterns for common widgets: button, checkbox, combobox, dialog, disclosure, listbox, menu, menubar, radio, slider, switch, tablist, treegrid, etc. Each pattern specifies required roles, required states/properties, keyboard interactions, and focus management.
The most common ARIA bugs:
- Wrong role (using `role="button"` on a span when `<button>` would work natively)
- Missing required states (combobox without aria-expanded)
- Missing required keyboard interactions (tab list without arrow keys)
- Using prohibited attributes (e.g., aria-checked on a non-checkable role)
- Reinventing native semantics ("custom dropdown" when `<select>` works)
</context>
<task>
For the component below:
1. Identify which APG pattern it matches (or note "no exact pattern — closest is X").
2. Check required roles — flag missing or wrong.
3. Check required states / properties — flag missing or extra.
4. Check keyboard interactions — flag missing keys or wrong behavior.
5. Check prohibited attributes — flag any aria-* attribute not allowed on this role.
6. Recommend whether to use native HTML instead (a common simplification).
</task>
<input>
Component description (role, attributes, keyboard behavior): {component}
Pattern claimed (combobox, dialog, etc.): {pattern}
Implementation context (React / Vue / vanilla): {stack}
</input>
<constraints>
- Cite the APG pattern URL or section.
- Required vs optional states clearly distinguished.
- Keyboard requirements MUST be enumerated key-by-key.
- Prohibited attributes called out specifically (which attribute is not allowed for which role).
- "Use native HTML" recommendation when applicable (avoids ARIA entirely).
</constraints>
<output_format>
Five sections:
1. **Pattern match** — which APG pattern + URL
2. **Required roles** — table: Required role | Present? | Notes
3. **Required states & properties** — table: State | Required? | Present? | Notes
4. **Keyboard interactions** — table: Key | Expected behavior | Implemented? | Notes
5. **Recommendations** — bullet list of fixes ordered by impact
</output_format>
Before writing, identify if the component should use native HTML instead — that's often the right answer.Example
Common pitfalls
- APG pattern not cited; recommendations become subjective. Force the URL or section reference.
- Required vs optional gets blended; reviewers can't tell which are blockers.
- Keyboard interactions listed as 'arrow keys work' without enumerating each key. Demand key-by-key table.
- Native HTML alternative skipped — APG often says 'consider native first'. The model should call this out.
Tips
- Bookmark the APG pattern URL for every widget your team builds — it's the single best reference.
- Run this prompt during PR review of any new custom widget — catches issues before merge.
- Pair with `screen-reader-scenarios` to validate the announcement of the corrected ARIA.
- Consider using a library that implements APG patterns (Reach UI, Radix UI, Headless UI) instead of building from scratch.
FAQ
Always prefer native HTML when possible. `<button>` over `role="button"`. `<dialog>` over `role="dialog"`. `<details>` over disclosure widget. Native HTML provides accessibility, keyboard handling, and focus management for free. ARIA is for cases where native HTML doesn't fit (custom comboboxes, tab lists, etc.).
Related prompts
Generate a WCAG 2.2 AA Test Suite
Returns a comprehensive WCAG 2.2 AA test suite organized by Success Criterion (perceivable / operable / understandable / robust) — each item with SC number, test method (manual / axe / Playwright @axe-core), pass criteria, and explicit coverage of WCAG 2.2's new criteria.
Open →Screen Reader Test Scenarios
Reads a component description and returns screen reader test scenarios with expected announcement text per reader (NVDA, JAWS, VoiceOver), recommended browser pairing per reader, navigation pattern, and clear pass/fail criteria.
Open →Keyboard Navigation Test Cases
Returns numbered keyboard navigation test cases covering Tab order, focus visibility, focus trap in modals/menus, Escape key behavior, skip links, focus return after modal close, and roving tabindex for composite widgets — with expected behavior per case.
Open →Review Test Code for Anti-Patterns
Reads a test file and returns a categorized list of anti-patterns — hard sleeps, shared mutable state, weak assertions (`toBeTruthy` instead of `toEqual`), missing teardown, mixed setup/assertion concerns — each with line numbers, severity, and a suggested fix.
Open →