Skip to content

Validate ARIA Implementation Against WAI-ARIA Authoring Practices

Updated 2026-06-08·advanced·Accessibility Testing

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