---
name: aria-apg
description: "WAI-ARIA Authoring Practices Guide (APG) design pattern knowledge base for accessibility assessment"
---

# WAI-ARIA Authoring Practices Guide

This skill packages the W3C WAI-ARIA Authoring Practices Guide (APG) as an accessibility assessment knowledge base. APG documents the keyboard interaction, ARIA roles, states, and properties for the common interactive widget patterns that web authors implement. The skill groups 44 design patterns into seven families (Disclosure, Combobox, Grid, Menu, Tabs, Treegrid, and Dialog) and points the Accessibility Skill Assessor subagent at the per-family reference files in `references/` when a finding involves a specific pattern.

APG is non-normative implementation guidance that operationalises the normative WAI-ARIA specification, so APG patterns sit alongside the [`wcag-22`](../wcag-22/SKILL.md) skill: APG describes how to build the widget, WCAG 2.2 describes which behaviours the finished widget must satisfy. Assessor subagents typically cite both — the APG pattern for the widget contract and the relevant WCAG 2.2 success criterion for the user-facing requirement.

Source: W3C WAI-ARIA Authoring Practices Guide, <https://www.w3.org/WAI/ARIA/apg/>. APG content is published under the W3C Document License. Per the repository licensing posture in `.github/instructions/accessibility/accessibility-license-posture.instructions.md`, pattern summaries in this skill are paraphrased in the authors' own words and every reference file links to the canonical W3C pattern URL for verification.

## Pattern roll-up

| Pattern                            | Family     | Primary roles                                                                                   | Required keyboard                                                                          | Required ARIA                                                                                            | Reference                                                                                                                         |
|------------------------------------|------------|-------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------|
| Accordion                          | Disclosure | `button`, `region`                                                                              | Enter, Space, Down/Up arrows (optional), Home, End                                         | `aria-expanded`, `aria-controls`                                                                         | [family-disclosure.md#pattern-accordion](references/family-disclosure.md#pattern-accordion)                                       |
| Disclosure (Show/Hide)             | Disclosure | `button`                                                                                        | Enter, Space                                                                               | `aria-expanded`, `aria-controls` (optional)                                                              | [family-disclosure.md#pattern-disclosure-show-hide](references/family-disclosure.md#pattern-disclosure-show-hide)                 |
| Carousel (Auto-Rotating)           | Disclosure | `region`, `button`                                                                              | Left/Right arrows, Space or Enter (pause)                                                  | `aria-live`, `aria-controls`                                                                             | [family-disclosure.md#pattern-carousel-auto-rotating](references/family-disclosure.md#pattern-carousel-auto-rotating)             |
| Carousel (Tabbed)                  | Disclosure | `tablist`, `tab`, `tabpanel`                                                                    | Left/Right arrows, Enter, Space                                                            | `aria-selected`                                                                                          | [family-disclosure.md#pattern-carousel-tabbed](references/family-disclosure.md#pattern-carousel-tabbed)                           |
| Disclosure Navigation              | Disclosure | `button`, `navigation`                                                                          | Enter, Space, Escape (optional), Tab                                                       | `aria-expanded`                                                                                          | [family-disclosure.md#pattern-disclosure-navigation](references/family-disclosure.md#pattern-disclosure-navigation)               |
| Disclosure Navigation Hybrid       | Disclosure | `button`, `link`                                                                                | Enter, Space, Tab, arrow keys (optional)                                                   | `aria-expanded`, `aria-haspopup` (optional)                                                              | [family-disclosure.md#pattern-disclosure-navigation-hybrid](references/family-disclosure.md#pattern-disclosure-navigation-hybrid) |
| Combobox (Autocomplete Both)       | Combobox   | `combobox`, `listbox`, `option`                                                                 | Down/Up arrows, Escape, Enter, Alt+Down or Alt+Up                                          | `aria-expanded`, `aria-controls`, `aria-autocomplete="both"`, `aria-activedescendant`                    | [family-combobox.md#pattern-combobox-autocomplete-both](references/family-combobox.md#pattern-combobox-autocomplete-both)         |
| Combobox (List)                    | Combobox   | `combobox`, `listbox`, `option`                                                                 | Down/Up arrows, Escape, Enter, Backspace                                                   | `aria-expanded`, `aria-controls`, `aria-autocomplete="list"`, `aria-activedescendant`                    | [family-combobox.md#pattern-combobox-list](references/family-combobox.md#pattern-combobox-list)                                   |
| Combobox (None)                    | Combobox   | `combobox`, `listbox`, `option`                                                                 | Down arrow, Enter, Escape                                                                  | `aria-expanded`, `aria-controls`, `aria-autocomplete="none"`, `aria-activedescendant`                    | [family-combobox.md#pattern-combobox-none](references/family-combobox.md#pattern-combobox-none)                                   |
| Combobox (Select-Only)             | Combobox   | `combobox`, `listbox`, `option`                                                                 | Down/Up arrows, Escape, Enter, Space, printable characters                                 | `aria-expanded`, `aria-controls`, `aria-activedescendant`                                                | [family-combobox.md#pattern-combobox-select-only](references/family-combobox.md#pattern-combobox-select-only)                     |
| Combobox (Grid Popup)              | Combobox   | `combobox`, `grid`, `gridcell`                                                                  | Arrow keys, Home, End, Enter, Escape                                                       | `aria-haspopup="grid"`, `aria-expanded`, `aria-controls`, `aria-activedescendant`                        | [family-combobox.md#pattern-combobox-grid-popup](references/family-combobox.md#pattern-combobox-grid-popup)                       |
| Listbox                            | Combobox   | `listbox`, `option`                                                                             | Down/Up arrows, Space, Shift+Space, Home, End, Ctrl+A                                      | `aria-selected`, `aria-multiselectable`, `aria-disabled`                                                 | [family-combobox.md#pattern-listbox](references/family-combobox.md#pattern-listbox)                                               |
| Grid (Layout)                      | Grid       | `grid`, `row`, `gridcell`                                                                       | Arrow keys, Home, End, Ctrl+Home, Ctrl+End, Enter or Space                                 | `aria-selected`                                                                                          | [family-grid.md#pattern-grid-layout](references/family-grid.md#pattern-grid-layout)                                               |
| Grid (Data, Single-Cell Selection) | Grid       | `grid`, `row`, `gridcell`, `columnheader`                                                       | Arrow keys, Home, End, Ctrl+Home, Ctrl+End, Enter or Space                                 | `aria-selected`, `aria-readonly`                                                                         | [family-grid.md#pattern-grid-data-single-cell](references/family-grid.md#pattern-grid-data-single-cell)                           |
| Grid (Data, Multi-Cell Selection)  | Grid       | `grid`, `row`, `gridcell`                                                                       | Arrow keys, Ctrl+Space, Shift+arrow keys, Ctrl+A                                           | `aria-multiselectable`, `aria-selected`                                                                  | [family-grid.md#pattern-grid-data-multi-cell](references/family-grid.md#pattern-grid-data-multi-cell)                             |
| Spinbutton                         | Grid       | `spinbutton`                                                                                    | Up/Down arrows, Page Up, Page Down, Home, End                                              | `aria-valuenow`, `aria-valuemin`, `aria-valuemax`, `aria-valuetext`, `aria-disabled`                     | [family-grid.md#pattern-spinbutton](references/family-grid.md#pattern-spinbutton)                                                 |
| Slider (Single-Thumb)              | Grid       | `slider`                                                                                        | Left/Right or Up/Down arrows, Home, End, Page Up, Page Down                                | `aria-valuenow`, `aria-valuemin`, `aria-valuemax`, `aria-valuetext`, `aria-orientation`, `aria-disabled` | [family-grid.md#pattern-slider-single-thumb](references/family-grid.md#pattern-slider-single-thumb)                               |
| Slider (Two-Thumb)                 | Grid       | `slider`                                                                                        | Arrow keys, Tab between thumbs, Home, End                                                  | `aria-valuenow`, `aria-valuemin`, `aria-valuemax`, `aria-valuetext`, `aria-label`, `aria-orientation`    | [family-grid.md#pattern-slider-two-thumb](references/family-grid.md#pattern-slider-two-thumb)                                     |
| Menu Button                        | Menu       | `button`, `menu`, `menuitem`                                                                    | Enter, Space, Down/Up arrows, Escape, Tab, printable characters                            | `aria-haspopup="menu"`, `aria-expanded`, `aria-controls`                                                 | [family-menu.md#pattern-menu-button](references/family-menu.md#pattern-menu-button)                                               |
| Menubar (Editor)                   | Menu       | `menubar`, `menuitem`                                                                           | Tab, arrow keys, Down (open menu), Right (next menu), Enter, Space, Escape                 | `aria-haspopup="menu"`, `aria-expanded`, `aria-orientation`                                              | [family-menu.md#pattern-menubar-editor](references/family-menu.md#pattern-menubar-editor)                                         |
| Menubar (Navigation)               | Menu       | `menubar`, `menuitem`, `link`                                                                   | Tab, Left/Right arrows, Down (submenu), Up, Escape, Enter, Space                           | `aria-haspopup`, `aria-orientation`                                                                      | [family-menu.md#pattern-menubar-navigation](references/family-menu.md#pattern-menubar-navigation)                                 |
| Actions Menu Button                | Menu       | `button`, `menu`, `menuitem`                                                                    | Enter, Space, Down arrow, arrow keys, Escape, printable characters                         | `aria-haspopup="menu"`, `aria-expanded`                                                                  | [family-menu.md#pattern-actions-menu-button](references/family-menu.md#pattern-actions-menu-button)                               |
| Menubar with Multiple Selection    | Menu       | `menubar`, `menuitemcheckbox`, `menuitemradio`                                                  | Arrow keys, Space, Enter, Shift+arrow (optional), Ctrl+A (optional)                        | `aria-checked`, `aria-multiselectable`                                                                   | [family-menu.md#pattern-menubar-multi-select](references/family-menu.md#pattern-menubar-multi-select)                             |
| Tabs (Manual Activation)           | Tabs       | `tablist`, `tab`, `tabpanel`                                                                    | Tab, Left/Right or Up/Down arrows, Home, End, Enter, Space, Delete (optional)              | `aria-selected`, `aria-controls`, `aria-labelledby`, `aria-orientation`                                  | [family-tabs.md#pattern-tabs-manual-activation](references/family-tabs.md#pattern-tabs-manual-activation)                         |
| Tabs (Automatic Activation)        | Tabs       | `tablist`, `tab`, `tabpanel`                                                                    | Tab, Left/Right or Up/Down arrows, Home, End, Delete (optional)                            | `aria-selected`, `aria-controls`, `aria-labelledby`, `aria-orientation`                                  | [family-tabs.md#pattern-tabs-automatic-activation](references/family-tabs.md#pattern-tabs-automatic-activation)                   |
| Tree View                          | Treegrid   | `tree`, `treeitem`                                                                              | Arrow keys, Home, End, asterisk (optional), printable characters                           | `aria-expanded`, `aria-level`, `aria-posinset`, `aria-setsize`, `aria-selected`                          | [family-treegrid.md#pattern-tree-view](references/family-treegrid.md#pattern-tree-view)                                           |
| Treegrid (Email Client)            | Treegrid   | `treegrid`, `row`, `gridcell`                                                                   | Right/Left arrows (expand/collapse), Down/Up arrows, Home, End, Ctrl+Home, Ctrl+End, Space | `aria-expanded`, `aria-level`, `aria-selected`, `aria-controls`                                          | [family-treegrid.md#pattern-treegrid-email-client](references/family-treegrid.md#pattern-treegrid-email-client)                   |
| Link                               | Treegrid   | `link` (native `<a>` or role)                                                                   | Enter, Space (optional with role), Tab                                                     | `aria-current`, `aria-disabled`, `aria-label`, `aria-expanded` (optional)                                | [family-treegrid.md#pattern-link](references/family-treegrid.md#pattern-link)                                                     |
| Alert                              | Dialog     | `alert`                                                                                         | None (announced on insertion); Tab through embedded controls                               | `aria-live="assertive"`, `aria-atomic="true"`                                                            | [family-dialog.md#pattern-alert](references/family-dialog.md#pattern-alert)                                                       |
| Alert Dialog (Modal)               | Dialog     | `alertdialog`                                                                                   | Tab, Shift+Tab, Escape, Enter on default button                                            | `aria-modal="true"`, `aria-labelledby`, `aria-describedby`                                               | [family-dialog.md#pattern-alert-dialog-modal](references/family-dialog.md#pattern-alert-dialog-modal)                             |
| Dialog (Modal)                     | Dialog     | `dialog`                                                                                        | Tab, Shift+Tab, Escape, Enter on submit                                                    | `aria-modal="true"`, `aria-labelledby`, `aria-describedby`                                               | [family-dialog.md#pattern-dialog-modal](references/family-dialog.md#pattern-dialog-modal)                                         |
| Feed                               | Dialog     | `feed`, `article`                                                                               | Page Up, Page Down, Home, End (optional), Tab                                              | `aria-label`, `aria-live="polite"`, `aria-relevant`, `aria-busy`                                         | [family-dialog.md#pattern-feed](references/family-dialog.md#pattern-feed)                                                         |
| Breadcrumb                         | Dialog     | `navigation`, `link`                                                                            | Tab, Enter                                                                                 | `aria-label`, `aria-current="page"`                                                                      | [family-dialog.md#pattern-breadcrumb](references/family-dialog.md#pattern-breadcrumb)                                             |
| Notification (Live Region)         | Dialog     | `alert`, `status`, `log`                                                                        | None (announced); Tab through embedded controls                                            | `aria-live`, `aria-atomic`, `aria-relevant`                                                              | [family-dialog.md#pattern-notification-live-region](references/family-dialog.md#pattern-notification-live-region)                 |
| Switch                             | Dialog     | `switch`                                                                                        | Space, Enter (optional), Tab                                                               | `aria-checked`, `aria-label`, `aria-disabled`                                                            | [family-dialog.md#pattern-switch](references/family-dialog.md#pattern-switch)                                                     |
| Radio Group                        | Dialog     | `radiogroup`, `radio`                                                                           | Tab, Space, arrow keys                                                                     | `aria-checked`, `aria-label`                                                                             | [family-dialog.md#pattern-radio-group](references/family-dialog.md#pattern-radio-group)                                           |
| Radio Group (Roving Tabindex)      | Dialog     | `radiogroup`, `radio`                                                                           | Tab, arrow keys, Space (optional)                                                          | `aria-checked`, managed `tabindex`                                                                       | [family-dialog.md#pattern-radio-group-roving-tabindex](references/family-dialog.md#pattern-radio-group-roving-tabindex)           |
| Checkbox (Dual State)              | Dialog     | `checkbox`                                                                                      | Space, Tab                                                                                 | `aria-checked` (true or false), `aria-label`, `aria-disabled`                                            | [family-dialog.md#pattern-checkbox-dual-state](references/family-dialog.md#pattern-checkbox-dual-state)                           |
| Checkbox (Mixed State)             | Dialog     | `checkbox`                                                                                      | Space, Tab                                                                                 | `aria-checked="mixed"` (plus true and false), `aria-label`, `aria-disabled`                              | [family-dialog.md#pattern-checkbox-mixed-state](references/family-dialog.md#pattern-checkbox-mixed-state)                         |
| Button                             | Dialog     | `button`                                                                                        | Enter, Space, Tab, Shift+F10 (optional)                                                    | `aria-pressed`, `aria-haspopup`, `aria-expanded`, `aria-disabled`, `aria-label`                          | [family-dialog.md#pattern-button](references/family-dialog.md#pattern-button)                                                     |
| Meter                              | Dialog     | `meter`                                                                                         | None (read-only display)                                                                   | `aria-valuenow`, `aria-valuemin`, `aria-valuemax`, `aria-valuetext`, `aria-label`                        | [family-dialog.md#pattern-meter](references/family-dialog.md#pattern-meter)                                                       |
| Tooltip                            | Dialog     | `tooltip`                                                                                       | Tab triggers display, Escape (optional)                                                    | `aria-describedby` on trigger, `aria-expanded` (optional)                                                | [family-dialog.md#pattern-tooltip](references/family-dialog.md#pattern-tooltip)                                                   |
| Window Splitter                    | Dialog     | `separator`                                                                                     | Tab, arrow keys, Home, End, Enter (optional)                                               | `aria-valuenow`, `aria-valuemin`, `aria-valuemax`, `aria-orientation`, `aria-label`, `aria-controls`     | [family-dialog.md#pattern-window-splitter](references/family-dialog.md#pattern-window-splitter)                                   |
| Landmarks                          | Dialog     | `navigation`, `main`, `complementary`, `contentinfo`, `search`, `region`, `form`, `application` | None (structural; screen-reader landmark navigation)                                       | `aria-label`, `aria-labelledby`, `aria-current`                                                          | [family-dialog.md#pattern-landmarks](references/family-dialog.md#pattern-landmarks)                                               |

Total: 44 patterns across 7 families (Disclosure: 6; Combobox: 6; Grid: 6; Menu: 5; Tabs: 2; Treegrid: 3; Dialog: 16).

## Assessment heuristics

Per-pattern keyboard interaction lists, ARIA role and state requirements, and pattern-specific notes live inside the per-family reference files in `references/`. The Accessibility Skill Assessor subagent consumes the appropriate `family-<name>.md#pattern-<slug>` section when evaluating a finding against a specific APG pattern.

Cross-skill use is the common case: an APG finding usually cites both the pattern reference here and the relevant WCAG 2.2 success criterion in [`wcag-22`](../wcag-22/SKILL.md). For example, a custom combobox with broken keyboard support is cited against `family-combobox.md#pattern-combobox-list` (for the missing keyboard contract) and `../wcag-22/references/guideline-2-1.md#sc-2-1-1` (for the WCAG 2.1.1 Keyboard requirement).

## Skill layout

* `SKILL.md` — this file (skill entrypoint and 44-row roll-up table).
* `references/` — one markdown file per APG pattern family. Each file contains a paraphrased description of every pattern in the family, its keyboard interaction contract, its ARIA roles, states, and properties, and a canonical W3C source URL.