with one click
aria-apg
WAI-ARIA Authoring Practices Guide (APG) design pattern knowledge base for accessibility assessment
Menu
WAI-ARIA Authoring Practices Guide (APG) design pattern knowledge base for accessibility assessment
| name | aria-apg |
| description | WAI-ARIA Authoring Practices Guide (APG) design pattern knowledge base for accessibility assessment |
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 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 | 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 |
| Disclosure (Show/Hide) | Disclosure | button | Enter, Space | aria-expanded, aria-controls (optional) | 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 |
| Carousel (Tabbed) | Disclosure | tablist, tab, tabpanel | Left/Right arrows, Enter, Space | aria-selected | family-disclosure.md#pattern-carousel-tabbed |
| Disclosure Navigation | Disclosure | button, navigation | Enter, Space, Escape (optional), Tab | aria-expanded | 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| Alert | Dialog | alert | None (announced on insertion); Tab through embedded controls | aria-live="assertive", aria-atomic="true" | 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 |
| Dialog (Modal) | Dialog | dialog | Tab, Shift+Tab, Escape, Enter on submit | aria-modal="true", aria-labelledby, aria-describedby | 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 |
| Breadcrumb | Dialog | navigation, link | Tab, Enter | aria-label, aria-current="page" | 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 |
| Switch | Dialog | switch | Space, Enter (optional), Tab | aria-checked, aria-label, aria-disabled | family-dialog.md#pattern-switch |
| Radio Group | Dialog | radiogroup, radio | Tab, Space, arrow keys | aria-checked, aria-label | 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 |
| Checkbox (Dual State) | Dialog | checkbox | Space, Tab | aria-checked (true or false), aria-label, aria-disabled | 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 |
| Button | Dialog | button | Enter, Space, Tab, Shift+F10 (optional) | aria-pressed, aria-haspopup, aria-expanded, aria-disabled, aria-label | 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 |
| Tooltip | Dialog | tooltip | Tab triggers display, Escape (optional) | aria-describedby on trigger, aria-expanded (optional) | 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 |
| 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 |
Total: 44 patterns across 7 families (Disclosure: 6; Combobox: 6; Grid: 6; Menu: 5; Tabs: 2; Treegrid: 3; Dialog: 16).
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. 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.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.🤖 Crafted with precision by ✨Copilot following brilliant human instruction, then carefully refined by our team of discerning human reviewers.
W3C Making Content Usable for People with Cognitive and Learning Disabilities (COGA) knowledge base for accessibility assessment
European EN 301 549 V3.2.1 ICT Accessibility Standard knowledge base for accessibility assessment
US Section 508 ICT Accessibility Standards (revised 2017) knowledge base for accessibility assessment
WCAG 2.2 success criteria knowledge base for accessibility assessment
Shared work-item templates and conventions for ADO and GitHub backlog handoff across the RAI, Security, SSSC, and Accessibility planners
Foundational Python best practices, idioms, and code quality fundamentals