WAI-ARIA Authoring Practices Guide (APG)

One name per control. The guide names 30 patterns: Accordion, Alert, Alert and Message Dialogs, Breadcrumb, Button, Carousel, Checkbox, Combobox, Dialog (Modal), Disclosure, Feed, Grid, Landmarks, Link, Listbox, Menu and Menubar, Menu Button, Meter, Radio Group, Slider, Slider (Multi-Thumb), Spinbutton, Switch, Table, Tabs, Toolbar, Tooltip, Tree View, Treegrid and Window Splitter. Where design systems call the same control "collapse", "expander" or "accordion", the APG name is one fixed reference.

Each pattern fixes the behaviour, not the look. A pattern page specifies the keyboard interaction (which keys do what), the roles, states and properties (role="menu", aria-expanded, aria-controls) and the focus management (where focus goes on open and close).

Composite widgets are one Tab stop; arrow keys move inside. A menubar, tab list, listbox, toolbar or tree is reached with Tab; a popup menu is not, it receives focus when it opens. Inside, arrow keys move between items, often through a roving tabindex or aria-activedescendant. Home and End depend on the pattern: optional for tabs, listboxes and toolbars, required in menus whose arrow keys do not wrap.

Working examples. Nearly every pattern links to example implementations in HTML, CSS and JavaScript (the Window Splitter is the exception), for instance the Disclosure Navigation Menu or the Action Menu Button.

Informative, not normative. The APG does not specify normative requirements and has no conformance model. It shows how to meet the requirements that WCAG and the ARIA specification set.

Native HTML first. Where a native element covers the pattern — <button>, <details>, <dialog>, <select> — it beats a hand-built ARIA widget. ARIA adds semantics and promises behaviour; it does not add the behaviour itself.

Specifying or generating an interactive control — menu, combobox, tabs, dialog, tree — so that keyboard and screen-reader behaviour come with it

Writing acceptance criteria for a component: the pattern’s keyboard table is a ready-made checklist

Reviewing a component library or generated UI code for wrong roles and missing keys

Settling naming disputes in a design system: which control is a "menu" and which a "disclosure"

Name the guide, then let the model pick the pattern, or name the pattern yourself. "Follow the WAI-ARIA Authoring Practices Guide (APG)." is enough for the model to choose a fitting pattern. Naming it ("Use the APG Menu Button pattern.") removes the choice.

Call the control by its common name, fix its behaviour with the APG. The common name tells the model what to build; the pattern tells it how the control behaves. The Component Gallery lists the common name and aliases of 60 controls across 95 design systems.

Combine with a style or system anchor, not instead of one. The APG says nothing about the look. "Swiss Style, WCAG 2.2 AA, APG patterns" covers look, accessibility requirement and control behaviour.

Use the full name. "WAI-ARIA Authoring Practices Guide (APG)" or "ARIA Authoring Practices". The bare "APG" has other meanings outside web development.

Example prompts:

Expecting accessible behaviour without asking for it. Partly right: in our prior test on 2026-10-30, all six baselines of an account menu already used role="menu", aria-expanded and arrow keys. Only one of six handled type-ahead and four of six Home and End. With "Follow the WAI-ARIA Authoring Practices Guide (APG)." six of six runs did both. Both are optional or conditional in the pattern’s keyboard table (type-ahead is optional; Home and End are required when arrow keys do not wrap), so the baselines may still conform; the anchor makes the model add them.

Turning site navigation into an application menu. The APG itself recommends the Disclosure pattern for typical site navigation: its Navigation Menubar example opens with a caution that the menubar’s functionality is "unnecessary for typical site navigation". Practitioners make the same point, because screen-reader users expect arrow-key behaviour from a menu (see Criticism). In our prior test, one of six baselines for a university site navigation used role="menu"; with the anchor, six of six chose the disclosure pattern and named it.

Reading the recommendation as a ban. The APG does not forbid menu roles: besides the Disclosure Navigation Menu it shows a Navigation Menu Button and a Navigation Menubar for sites that need application-style menus. In the same test, two Opus runs wrote that the APG says not to use role="menu" for site navigation, which turns the guide’s recommendation into a rule.

Copying the examples into production. The guide’s own objectives "do not include providing a comprehensive design system or production-ready code". The examples teach the pattern; test them with real assistive technology before shipping.

Using ARIA where HTML would do. A <div role="button"> needs focus handling, Enter and Space that a <button> brings for free.

Broken patterns in real projects. Adrian Roselli, in "No, APG’s Support Charts Are Not 'Can I Use' for ARIA" (2023), writes: "Yet I have spent years tearing broken APG patterns out of client projects". He warns against reading APG’s support tables as general ARIA support data; they cover only APG’s own examples with a few screen readers and browsers.

Menu roles do not belong in site navigation. Elle Smith argues in "Does your navigation need an ARIA menu? Probably not" (Pope Tech, 2026) that "ARIA menu roles are meant for true menus": site navigation should use landmarks and links.

A living guide, not a numbered Note. Since May 2022 the APG has been a multi-page resource at w3.org/WAI/ARIA/apg that is updated continuously; the numbered Notes 1.1 and 1.2 are its predecessors. The prior serves the current guide well: in our prior test all tiers listed the patterns, the keyboard models and roving tabindex without prompting.