Screenshot of the WAI-ARIA Authoring Practices 1.1 Draft

Maintaining ARIA Authoring Practices


Contributing to the ARIA Authoring Practices Guide (APG) for authoring accessible web pages.

View project

We are actively maintaining the APG, adding new guidelines for new features in the ARIA specification, reviewing contributions from the community, and maintaining CI and testing for the APG examples.


Originally, the ARIA spec shipped without guidance on how to use ARIA in web sites and web applications. This made it difficult for web developers, browser implementers and assistive technology developers to know how to write and render accessible experiences with ARIA. The ARIA Authoring Practices Guide was introduced in 2014 to address this, and provides advice, examples, and context that help explain the intended use of ARIA.

Although originally published in 2014, the Authoring Practices Guide is a living document that needs continuous updating to stay in sync with the ARIA spec and web accessibility ecosystem.

At the beginning of 2019, the Guide lacked comprehensive instructions for important ARIA 1.2 features, like providing elements with accessible names, live regions, range related properties, the aria-hidden attribute, aria-level hierarchies, and others. The APG needed new sections written to distill the intent of ARIA into guidelines for real-world behavior of assistive technologies, as well as an ongoing maintenance strategy.


With initial funding from Facebook, we added guidelines for providing HTML elements with accessible names and descriptions, contributed new sections on live regions, range related properties, the aria-hidden attribute, and aria-level hierarchies.

We contributed a new top-level chapter on accessible names and descriptions, including an explanation of how names are derived by assistive technologies and a table of guidance by role for common web page widgets, including alerts, banners, feeds, menus, progress bars, and tooltips.

The pull request for naming-and-describing alone counted over 130 revisions to incorporate editorial and community feedback. We also contributed new sections for live regions, range-related properties, the accessibility tree, aria-hidden, and aria-level.

Since this initial push to get the APG up to date with ARAI in 2019, we have stayed on, providing ongoing contributions, review for other contributors, and infrastructure maintenance.


The updated ARIA Authoring Practices Guide helps web developers implement accessible web sites and apps, and provides a basis for new initiatives in interoperability testing for web accessbility. Our initial push helped get ARIA 1.2 out the door with up-to-date practice guidelines, and our continued maintenance helps ensure that the guide continues to support the ARIA community.

Writing the new guidelines has also uncovered issues where the original specification could be improved or clarified. For example, in the first year of maintenance, we opened over a dozen issues in the ARIA spec, and in associated specifications that cover ARIA integration into the web platform, including html-aria, html-aam, and accname.

This work occasionally also leads us to accessibility bugs in browsers, like this one in Chromium which we came across through an investigation into aria-level.

Contact Us

We'd love to hear from you. Get in touch!


P.O. Box 961436
Boston, MA 02196