aria-authoring-patterns
Reference for the W3C ARIA Authoring Practices Guide (APG) - covers the 31 canonical interactive-widget patterns (Combobox, Dialog, Menu, Tabs, Tree, etc.), their required ARIA roles and states, the keyboard-interaction model per pattern, and the canonical-violations to watch for. Use when authoring a custom interactive widget that doesn't have a native HTML equivalent, or when reviewing one for ARIA correctness.
Install with skills.sh (any agent)
npx skills add testland/qa --skill aria-authoring-patternsaria-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 (opens in new window)).
The APG documents 31 patterns; each one specifies:
When to use
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 semantics, more code, easier to break. |
<input type="checkbox"> | Custom checkbox unless visual constraints demand it. |
<a href> | <div onclick="navigate(...)">. |
<select> | Custom listbox UNLESS multi-select with rich content per option. |
<input type="radio"> | Custom radio group. |
When the visual design demands a custom widget, follow the matching APG pattern exactly.
Canonical patterns (APG)
The 31 patterns documented per apg-patterns (opens in new window):
Form controls
| Pattern | When to use | Native fallback |
|---|---|---|
| Button | Trigger an action. | <button> - almost always. |
| Checkbox | Two-state binary; or three-state (mixed). | <input type="checkbox">. |
| Combobox | Searchable / filterable select with autocomplete. | <select> for plain selection only. |
| Disclosure | Show/hide content; one-way reveal. | <details> / <summary>. |
| Listbox | Multi-select OR rich-content single-select. | <select> for plain. |
| Menu / Menubar | Application menus (File / Edit / View bar). | (No native; APG required.) |
| Menu Button | Button that opens a menu. | (No native; APG required.) |
| Radio Group | Mutually-exclusive option set. | <input type="radio" name="x">. |
| Slider | Single-value within a range. | <input type="range">. |
| Slider (Multi-Thumb) | Range selection. | (No native; APG required.) |
| Spinbutton | Numeric input with increment/decrement controls. | <input type="number">. |
| Switch | On/off toggle, semantically distinct from checkbox. | (No native; APG required.) |
Containers / navigation
| Pattern | When to use |
|---|---|
| Accordion | Vertically-stacked list of headers; each expands. |
| Breadcrumb | Hierarchical-location indicator. |
| Carousel | Cycle through groups of equivalent content. |
| Dialog (Modal) | Overlay requiring user interaction. (See wcag-focus-trap.) |
| Alert Dialog | Modal that interrupts to convey urgency. |
| Tabs | Switch between sibling content sections. |
| Toolbar | Group of controls (buttons, dropdowns). |
| Tree View | Hierarchical navigation. |
| Treegrid | Hierarchical data grid (table rows that expand). |
| Window Splitter | Resize between two panes. |
Feedback / indicators
| Pattern | When to use |
|---|---|
| Alert | Important programmatically-determined message. |
| Feed | Dynamic stream of articles. |
| Grid | 2D widget for navigating tabular UI elements. |
| Meter | Scalar measurement within a known range. |
| Tooltip | Brief contextual hint on hover/focus. |
Content
| Pattern | When to use |
|---|---|
| Landmarks | Navigation regions (<nav>, <main>, etc.). |
| Link | Navigation to a different resource. |
| Table | Tabular data (use <table>). |
Per-pattern essentials
The APG's per-pattern documentation is detailed; for each pattern this skill highlights the load-bearing essentials.
Combobox
<label for="combo">Choose a fruit</label>
<input
id="combo"
role="combobox"
aria-expanded="false"
aria-controls="combo-listbox"
aria-autocomplete="list"
aria-activedescendant=""
/>
<ul id="combo-listbox" role="listbox" hidden>
<li id="opt-1" role="option" aria-selected="false">Apple</li>
<li id="opt-2" role="option" aria-selected="false">Banana</li>
</ul>| Required ARIA | Why |
|---|---|
role="combobox" | Identifies the input as a combobox. |
aria-expanded | Tracks open/closed state. |
aria-controls | Links to the listbox ID. |
aria-autocomplete | none / inline / list / both. |
aria-activedescendant | Tracks the focused option without moving DOM focus. |
Tabs
<div role="tablist" aria-label="Settings sections">
<button role="tab" id="tab-1" aria-selected="true" aria-controls="panel-1" tabindex="0">General</button>
<button role="tab" id="tab-2" aria-selected="false" aria-controls="panel-2" tabindex="-1">Privacy</button>
</div>
<div role="tabpanel" id="panel-1" aria-labelledby="tab-1">...</div>
<div role="tabpanel" id="panel-2" aria-labelledby="tab-2" hidden>...</div>| Keyboard | Behavior |
|---|---|
| Tab | One tabstop for the whole tablist (only the active tab is tabindex="0"). |
| Left/Right arrow | Navigate between tabs. |
| Home / End | First / last tab. |
| Enter / Space | Activate (or auto on focus per implementation). |
Disclosure (Show/Hide)
<button aria-expanded="false" aria-controls="disclosure-1">More details</button>
<div id="disclosure-1" hidden>... content ...</div>The simplest pattern; canonical native equivalent is <details> / <summary> - use that unless the visual design demands the button form.
Tooltip (per SC 1.4.13)
<button aria-describedby="tt-1">Save</button>
<div id="tt-1" role="tooltip" hidden>Save the current document</div>| Behavior |
|---|
| Show on hover OR focus. |
| Dismissable via Esc (per SC 1.4.13). |
| Hoverable - user can move pointer to tooltip text. |
| Persistent until pointer / focus leaves OR Esc dismisses. |
(See wcag-color-contrast SC 1.4.13 for the three conditions.)
ARIA states reference
The most-used aria-* states across patterns:
| State | Use |
|---|---|
aria-expanded | Disclosure / Accordion / Combobox / Menu Button. |
aria-selected | Listbox / Tab. |
aria-checked | Checkbox / Radio. |
aria-pressed | Toggle button. |
aria-current | Current item in a set (page in pagination, item in breadcrumb). |
aria-controls | Element that this trigger controls. |
aria-labelledby | Reference to the labelling element. |
aria-describedby | Reference to a description element (tooltip, hint). |
aria-live | Live region; polite / assertive / off. |
aria-invalid | Form field validation state. |
aria-required | Form field required (with native required for forms). |
aria-disabled | Functionally disabled but in tab order (vs. disabled attribute which removes from tab order). |
aria-modal | Dialog modal flag; see wcag-focus-trap. |
Common ARIA failures
| Failure | Why | Fix |
|---|---|---|
<div role="button"> without keyboard handlers | Custom button needs tabindex="0" AND Enter/Space handlers. | Use <button> OR add both. |
aria-label on a <div> that has visible text label | Redundant; aria-label overrides the visible text for screen readers (becomes confusing). | Use aria-labelledby referencing the visible text element. |
aria-hidden="true" on a focusable element | Element is hidden from screen readers but still in tab order - broken state. | If you want to hide, also remove from tab order. |
Forgetting role="tab" / role="tabpanel" pairs | Screen reader doesn't announce the relationship. | Pair every tab with a panel via aria-controls / aria-labelledby. |
Hand-rolled combobox without aria-activedescendant | Arrow keys don't announce options. | Implement aria-activedescendant or move actual DOM focus. |
role="presentation" on a meaningful container | Removes semantics; sometimes used to "fix" a layout issue but breaks structure. | Don't override structure to fix layout; fix layout. |
Anti-patterns
| Anti-pattern | Why it fails | Fix |
|---|---|---|
| Inventing a custom pattern not in the APG | No screen-reader convention; users can't form expectations. | Match an APG pattern exactly OR fall back to native HTML. |
Mixing native and ARIA semantics (<button role="link">) | Confusing - element behaves like a button but says it's a link. | One or the other; native is preferred. |
tabindex="3" to control sequence | Positive tabindex creates fragile order. | DOM order + tabindex="0" for custom focusables. |
Adding aria-label to every element "for accessibility" | If the element has a visible label, aria-label overrides it. Many elements don't need a label at all. | Only add aria-label when there's no visible text label AND the element is interactive. |
References
Related skills
a11y-violation-gate
Builds a CI gate that fails the build on **new** WCAG / a11y violations introduced by a PR while grandfathering pre-existing violations on a per-rule / per-page baseline. Aggregates verdicts from axe-core / pa11y / Lighthouse a11y / WAVE / IBM Equal Access scans. Use when a project has accumulated a11y debt and a strict "zero violations" gate would block every PR - the ratchet pattern lets the team ship while preventing regressions.
axe-a11y
Authors and runs axe-core accessibility scans - the most-deployed open-source a11y engine - via the `axe.run()` JavaScript API or the @axe-core/playwright / @axe-core/cli wrappers, parses the `violations[]` results into per-rule severity (critical / serious / moderate / minor), configures rule disable / disable-by-tag patterns, and emits JUnit-shaped output for CI gating. Use when the project ships UI tests in JavaScript / TypeScript and wants automated a11y coverage on every PR.
ibm-equal-access-a11y
Authors and runs IBM Equal Access accessibility-checker scans - IBM's open-source a11y engine with WCAG 2.0 / 2.1 / 2.2 + US Section 508 rule sets, integrating with Node / Selenium / Puppeteer / Playwright / Karma / Cypress test runners. Distinguished by IBM's enterprise-tier rule coverage and Section 508 specificity. Use when the project ships to US federal / public-sector customers (Section 508 mandate) or when the team values IBM-branded a11y reporting.
lighthouse-a11y
Configures Lighthouse CI's Accessibility category for automated accessibility testing (a11y / WCAG coverage) - `categories:accessibility` audits backed by axe-core (axe) - with per-URL minimum-score assertions (fail a build when a page's score drops below a threshold) and per-audit overrides, distinct from the Performance category that `lighthouse-perf` covers. Use when the project already runs Lighthouse CI for Web Vitals and the team wants to add accessibility coverage in the same pipeline rather than spinning up a separate scanner.
pa11y-a11y
Authors and runs pa11y accessibility scans - a CLI / Node.js tool that wraps HTML CodeSniffer (htmlcs) and / or axe-core engines - with `pa11y {url}` invocation, reporter selection (cli / csv / json / html / tsv), WCAG standard selection (WCAG2A / WCAG2AA / WCAG2AAA), and rule ignoring. Use when the project needs scriptable a11y scans without a full test framework, or when a Node-stack project wants an alternative to direct axe-core use.
screen-reader-test-author
Builds a screen-reader test narrative - a step-by-step manual test script for NVDA (Windows), JAWS (Windows), VoiceOver (macOS / iOS), or TalkBack (Android) - that exercises a specific user flow through a component or page and captures the expected announcement at each step. Use when authoring an accessibility-acceptance test the team will run before sign-off, OR when scripting a manual a11y audit.
wave-a11y
Runs WebAIM WAVE accessibility scans via the WAVE API or the browser-extension UI - produces visual overlay of errors / alerts / structural elements directly on the page, plus categorized JSON output for CI use. Use when the team values manual-review-friendly visual feedback (the WAVE overlay) alongside automated CI scans, or when a regulatory audit requires WebAIM-branded reports.
wcag-checklist-builder
Builds a per-component WCAG 2.2 accessibility checklist from a component spec - covers focus management, color contrast, ARIA roles & states, keyboard interaction, error handling, and live-region announcements - emitting a markdown checklist or YAML test plan that pairs with screen-reader-test-author for manual verification and the violation gate for automated scans. Use during component-spec review or pre-implementation acceptance.
wcag-color-contrast
Reference for WCAG 2.2 color-contrast conformance - covers SC 1.4.3 Contrast (Minimum, AA), 1.4.6 Contrast (Enhanced, AAA), 1.4.11 Non-text Contrast (AA), and 1.4.13 Content on Hover or Focus (AA) - with the canonical contrast ratios (4.5:1 normal text, 3:1 large text and UI components), measurement formula references, and bulk design-token checking patterns. Use when designing a color palette, reviewing a component for accessibility, or auditing existing CSS for contrast violations.
wcag-compliance-reporter
Builds a per-page WCAG 2.2 compliance score report by aggregating output from one or more accessibility scanners (axe-core / pa11y / lighthouse / WAVE / IBM Equal Access), pivoting violations by Success Criterion (1.4.3 contrast, 2.4.7 focus visible, etc.), grouping by conformance level (A / AA / AAA), reporting per-page coverage gaps explicitly (the "this page wasn't scanned" failure mode), and emitting both an executive summary and a per-page drill-down. Use after a multi-page accessibility scan - pa11y-ci, axe across a sitemap, lighthouse-batch - when the team needs a shareable conformance report rather than a per-page tool dump.
wcag-focus-trap
Reference for **intentional** focus management in modal / dialog / drawer / popover components - the canonical pattern that satisfies WCAG SC 2.4.3 (Focus Order) without violating SC 2.1.2 (No Keyboard Trap). Covers focus-on-open, focus-cycle-within-container, Escape-closes-and-restores, return-to-trigger, and inert-the-rest-of-the-page. Use when authoring or reviewing any component that displays content over the page (modals, drawers, popovers, command palettes).
wcag-keyboard-navigation
Reference catalog for WCAG 2.2 keyboard-navigation conformance - covers SC 2.1.1 (Keyboard), 2.1.2 (No Keyboard Trap), 2.1.4 (Character Key Shortcuts), 2.4.3 (Focus Order), 2.4.7 (Focus Visible), 2.4.11/2.4.12 (Focus Not Obscured) - with conformance levels (A/AA), test scripts, and per-criterion failure patterns. Use when authoring or reviewing keyboard-only interaction support.
widget-a11y-test-matrix
Per-widget manual accessibility test matrices where every row pairs one keystroke with the expected focus behavior, the expected NVDA announcement, the expected VoiceOver announcement, and the WCAG 2.2 success criterion that row verifies. Covers button, toggle button, checkbox, text input, modal dialog, menu button, and combobox archetypes, plus universal Tab traversal. Use when a rendered widget has cleared automated scanning and a tester needs a fill-in pass/fail sheet to run by hand against NVDA and VoiceOver.