ARIA Authoring Practices Guide

The ARIA spec defines a vocabulary of roles, states, and properties. The ARIA Authoring Practices Guide explains how to actually use them: which keyboard interactions each pattern requires, how focus moves through a widget, what to announce when state changes, and what the DOM should look like.

What the APG contains

The APG documents the canonical implementation of every widget pattern the ARIA spec was written to support:

• Comboboxes (the autocomplete pattern with tricky keyboard behaviour that almost everyone implements wrong).
• Dialogs — modal and non-modal, with full focus-trap and return-focus-on-close behaviour.
• Disclosure widgets (the simple show/hide pattern).
• Menus and menubars — the kind that need arrow-key navigation, not just tab.
• Tabs — tab/tabpanel pairs with keyboard arrow navigation and automatic vs manual activation semantics.
• Treeviews — file-tree-style hierarchical navigation.
• Listboxes — single and multi-select.
• Spin buttons, sliders, carousels, and a dozen more.

Each pattern page has three parts: a working live example, the keyboard interaction table, and the precise ARIA attributes used. There are also landmark patterns — guidance on <header>, <nav>, <main>, and the ARIA roles that map to them — and a section on anti-patterns explaining what not to do.

When to reach for it

The APG is most useful when you’re about to build a widget that doesn’t have a native HTML element. Before writing a single line of code, check whether the APG has the pattern. Nearly always:

• The keyboard interactions you need to implement are already specified.
• The DOM shape is already documented.
• The ARIA attributes are already worked out.

Skipping this step is how teams ship “accessible” widgets that confuse screen readers in ways no automated tool catches. The APG is the difference between a comboBox that works for everyone and one that compiles but breaks for screen-reader users.

What the APG explicitly is not

The APG is not a normative specification. The normative documents are the ARIA spec itself and WCAG. The APG is guidance: implementing a widget exactly as the APG shows is the recommended path, but not the only legal path. That said, deviating from the APG without a documented reason is a signal you may not understand the pattern fully.

The APG also does not replace native HTML. If <select> will work for your dropdown, use <select> — don’t reach for the APG combobox pattern just because it sounds more advanced.