aria-authoring-patternslisted
Install: claude install-skill testland/qa
# aria-authoring-patterns
## Overview
The W3C ARIA Authoring Practices Guide (APG) is the canonical
reference for **how** to build accessible custom widgets - patterns
where native HTML doesn't have a single matching element
([apg-patterns][apg]).
[apg]: https://www.w3.org/WAI/ARIA/apg/patterns/
The APG documents 31 patterns; each one specifies:
- The required `role` attribute.
- Required and optional `aria-*` states (e.g. `aria-expanded`,
`aria-selected`, `aria-current`).
- The full keyboard-interaction model (Tab / Arrow keys / Enter /
Escape / Home / End / Type-ahead).
- DOM structure conventions.
- Common pitfalls.
## When to use
- Authoring a custom widget (Combobox, Tabs, Tree, Carousel, etc.).
- Reviewing a third-party UI library's component for ARIA
correctness.
- Adding ARIA to an existing widget that was hand-rolled without
it.
- Configuring assertions in `axe-a11y`
(or its pa11y reference) to enforce per-pattern
conventions.
## The first rule of ARIA
The APG (and WAI more broadly) consistently emphasizes:
> **No ARIA is better than bad ARIA.** Native HTML elements with
> built-in semantics are preferred over custom widgets whenever
> possible.
In practice:
| Native element | Don't replace with |
|-----------------------------------------------|-----------------------------------------------------|
| `<button>` | `<div role="button">` - same sem