The ARIA Authoring Practices Guide (APG) explains how to create accessible web experiences for users of assistive technologies and keyboard interfaces by developing web sites that properly convey accessibility semantics and implement common keyboard conventions. It also provides guidance on some closely related topics, such as supporting operating system settings for high contrast and reduced motion.
Accessibility semantics refer to the meaning of user interface elements that need to be conveyed to assistive technology users in order for those users to understand and use the elements. For example, people who can visually perceive a search icon button understand the element can be activated to perform a search by the way it is styled and positioned. To make that icon accessible to a screen reader user, one of the semantics that needs to be communicated is that the element represents an interactive button. In addition, keyboard accessibility requires the button to be focusable, and keyboard conventions call for pressing Enter or Space to activate the button when it is focused. The APG describes how to convey accessibility semantics and implement keyboard accessibility for many common design patterns, ranging from typical buttons and popup menus to complex tree grids. It also explains essential practices related to these patterns, such as how to convey web page structure with ARIA landmark regions and effectively utilize the many ways of encoding accessible names.
The APG is organized into two major sections: patterns and practices. Each pattern explains how to make a common user interface element, such as a button, menu, or dialog, accessible, and provides functional example implementations of the pattern. The practices section gives in-depth explanation of how to satisfy a variety of accessibility needs that surface when making rich internet application experiences accessible. For instance, the practices section on providing accessible names and descriptions gives detailed descriptions of seven different naming techniques as well as a table providing guidance for naming more than 80 types of elements.
The APG assumes basic understanding of web development, especially of HTML and CSS. It may be particularly useful to designers and engineers who are working on site design systems and component libraries. However, it is important to understand that the APG only covers a portion of what is needed to create accessible experiences. To understand accessibility more broadly, it is advisable to start with the WAI Accessibility Fundamentals and WAI Overview of Design and Development.
The accessibility semantics used in the APG patterns and described in APG practices are defined in the
WAI-ARIA 1.2 Specification.
That is, the ARIA specification standardizes the meaning of the attributes that describe elements and their states to assistive technologies, such as the meaning of
The W3C Web Accessibility Initiative's (WAI) Accessible Rich Internet Applications working group (ARIA WG) is addressing these deficiencies through several W3C standards efforts.
The WAI-ARIA Overview
provides additional background on WAI-ARIA, summarizes those efforts, and lists the other documents included in the WAI-ARIA suite.
APG 1.1 supported ARIA 1.1, and this version, APG 1.2, includes changes to support version 1.2 of the ARIA specification. It also includes nearly 200 significant updates to improve the quality and breadth of content. A detailed log of all changes is available on the wiki of the w3c/aria-practices GitHub repository. Highlights of major changes to support ARIA 1.2 as well as some of the improvements include the following.
- Added section to provide guidance related to 38 document structure roles, 18 of which are new in ARIA 1.2.
- Revised guidance for roles where naming requirements changed in ARIA 1.2. ARIA 1.2 prohibits names on some roles. ARIA 1.2 removed naming requirements from some other roles.
- Added naming guidance for 18 roles that are new in ARIA 1.2.
- Revised the combobox pattern and 4 combobox examples to reflect the ARIA 1.2 revisions to combobox.
- Added example illustrating changes in ARIA 1.2 that enable creation of custom select-only comboboxes, which are similar to HTML select elements. This replaces the Collapsible Listbox example, which is now deprecated.
- Revised the listbox pattern to specify how to utilize the new ARIA 1.2 support for named groups of options and Added a new listbox example to demonstrate the named option group feature.
- Revised the editor menubar example to illustrate new ARIA 1.2 support for named groups of items in a menu.
- Updated the listbox and tree patterns to reflect current browser processing of aria-selected and provided guidance regarding the use of aria-checked to communicate selection.
- Added section providing guidance about properties used with range widgets, such as aria-valuemin and aria-valuemax.
- Added a design pattern and example implementation of the meter role, which is new in ARIA 1.2
- Added two examples that demonstrate how to create rating inputs, one based on slider and one based on radio group.
- Added two other slider examples: a vertical temperature slider and a media seek slider.
- Added a switch design pattern and three example implementations: one made from a div element, one based on HTML button, and one that uses HTML checkbox input.
- Added a button example that illustrates use of the new ARIA 1.2 IDL interface.
- Added a date picker example that illustrates choosing a date with a combobox.
- Added another example of a disclosure navigation menu that demonstrates how to include top-level links.
- Added example of a sortable table.
- Changed all example pages to include a
Jump tomenu, a button to open the example in CodePen, and added a prominently placed warning with guidance about testing before re-using example code.
- Improved support for high contrast settings and added detailed documentation of high contrast support in many examples.
- Improved support for touch-based screen readers in several examples, most notably in sliders.
- Due to change in ARIA 1.2, removed Math role from list of roles that have presentational children.
- In response to feedback, fixed many documentation errors and functional bugs in examples.
Comprehensive lists of closed issues included in APG 1.2 release 1 are tracked in the following GitHub milestones:
- APG 1.2 Release 1 Milestone: Github issues closed in the first publication of APG 1.2 as a W3C Note in November 2021.
- APG 1.2 Working Draft 3 Milestone: Github issues closed in the third working draft of APG 1.2 published in November 2019.
- APG 1.2 Working Draft 1 milestone: GitHub issues closed in the first working draft of APG 1.2 published on July 17, 2018.
- Current editors:
- Former editors:
This version of the ARIA Authoring Practices Guide is dedicated to the memory of Carolyn MacLeod whose contributions are visible throughout the entire guide. She was dedicated to all aspects of the work of the APG Task Force from writing code and suggesting editorial revisions to testing examples with assistive technologies.
- Carolyn MacLeod (IBM Canada)
Major Contributors to Version 1.1
While WAI-ARIA Authoring Practices 1.1 is the work of the entire Authoring Practices Task Force and also benefits from many people throughout the open source community who both contribute significant work and provide valuable feedback, special thanks goes to the following people who provided distinctly large portions of the content and code in version 1.1.
- Jon Gunderson and Nicholas Hoyt of the Division of Disability Resources and Education Services at the University of Illinois Urbana/Champaign and the students Max Foltz, Sulaiman Sanaullah, Mark McCarthy, and Jinyuan Zhou for their contributions to the development of many of the design pattern examples.
- Valerie Young of Bocoup and her sponsor, Facebook, for development of the example test framework and regressions tests for more than 50 examples.
- Simon Pieters of Bocoup and his sponsor, Facebook, for authoring of significant guidance sections, including comprehensive treatment of the topic of accessible names and descriptions.
Other commenters and contributors to Version 1.1
- Vyacheslav Aristov
- J. Renée Beach
- Kasper Christensen
- Gerard K. Cohen
- Anne-Gaelle Colom
- Kevin Coughlin
- Cameron Cundiff
- Manish Dahamiwal
- Gilmore Davidson
- Boris Dušek
- Michael Fairchild
- Jeremy Felt
- Rob Fentress
- Tatiana Iskandar
- Patrick Lauke
- Marek Lewandowski
- Dan Matthew
- Shane McCarron
- Victor Meyer
- Jonathan Neal
- Philipp Rudloff
- Joseph Scheuhammer
- Nick Schonning
- Christopher Tryens
- HTML Standard. Anne van Kesteren; Domenic Denicola; Ian Hickson; Philip Jägenstedt; Simon Pieters. WHATWG. Living Standard. URL: https://html.spec.whatwg.org/multipage/
- HTML Accessibility API Mappings 1.0. Steve Faulkner; Scott O'Hara. W3C. 26 October 2022. W3C Working Draft. URL: https://www.w3.org/TR/html-aam-1.0/
- ARIA in HTML. Steve Faulkner; Scott O'Hara; Patrick Lauke. W3C. 27 September 2022. W3C Recommendation. URL: https://www.w3.org/TR/html-aria/
- Scalable Vector Graphics (SVG) 2. Amelia Bellamy-Royds; Bogdan Brinza; Chris Lilley; Dirk Schulze; David Storey; Eric Willigers. W3C. 4 October 2018. W3C Candidate Recommendation. URL: https://www.w3.org/TR/SVG2/
- Accessible Rich Internet Applications (WAI-ARIA) 1.1. Joanmarie Diggs; Shane McCarron; Michael Cooper; Richard Schwerdtfeger; James Craig. W3C. 14 December 2017. W3C Recommendation. URL: https://www.w3.org/TR/wai-aria-1.1/
- Accessible Rich Internet Applications (WAI-ARIA) 1.2. Joanmarie Diggs; James Nurthen; Michael Cooper. W3C. 8 December 2021. W3C Candidate Recommendation. URL: https://www.w3.org/TR/wai-aria-1.2/