aria-apg

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 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
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).

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. 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.

---

🤖 Crafted with precision by ✨Copilot following brilliant human instruction, then carefully refined by our team of discerning human reviewers.