Contributing to the ARIA Authoring Practices Guide

We believe that inclusivity and accessibility are of utmost importance to the open web platform. One of the ways that we empower the full diversity of Internet users is by ensuring that those with permanent disabilities and temporary limitations, can browse websites with assistive technologies. Writing accessible code improves the experience of browsing a website for everyone and removes interaction obstacles that a site’s creator may not have foreseen. Keyboard navigation, for example, benefits both users who permanently use alternative input devices, as well as users temporarily resting their wrists after a long day gripping a mouse. Even with the best of intentions, however, it can be difficult to write truly accessible HTML, CSS, and JavaScript. Understanding best practices by reading ARIA, the technical specification for accessibility, is no small feat.

To help make writing accessible web apps easier, Bocoup has been contributing to a document called the Authoring Practices guide which provides advice, examples, and context that help web developers understand topics in the ARIA specification. Our contributions to the Authoring Practices guide include a new chapter on providing elements with accessible names and descriptions. We also added or proposed new sections on live regions, range related properties, the aria-hidden attribute, and aria-level hierarchies.

In this post, we’d like to go over some of these additions as well as provide some broader context on why the Authoring Practices guide exists and how it has helped improve the ARIA spec itself. You can also read our case study about related, ongoing work ensuring correctness of ARIA examples through automated regression tests!

What is the ARIA Authoring Practices guide?

ARIA, or Accessible Rich Internet Applications, is the technical specification for adding accessibility information to web apps, published by the W3C Web Accessibility Initiative (WAI). The WAI also publishes Web Content Accessibility Guidelines (WCAG) which are a more general set of guidelines that are not technology-specific. Where the WCAG says that content must be perceivable, operable, understandable, and robust, ARIA specifies how to override and augment the accessibility information of HTML and SVG to satisfy WCAG when creating custom, non-native UI components.

One important caveat to note is that many semantic HTML elements already incorporate built-in accessibility and ARIA roles. If you use semantic input elements or navigation elements, for example, you don’t need to duplicate information implied by the semantic element itself. One of the biggest barriers to accessibility, is the incorrect application of ARIA roles in markup. The adage goes: no ARIA is better than bad ARIA. In fact, a recent study showed that among a million sampled sites, those with ARIA attributes in markup had more accessibility errors than those without!

Successfully following the ARIA specification can be a difficult task for many developers. The Authoring Practices guide attempts to fill the gap of missing instructional material. Much as MDN docs help developers understand HTML, CSS, and JS specifications, the Authoring Practices guide helps developers understand ARIA with high-level explanations and examples of how assistive technology uses ARIA metadata in practice.

Contributing to ARIA Authoring Practices

This year, Bocoup worked to improve the Authoring Practices guide with actionable information for sections of ARIA that needed further explanation. The biggest update was a new chapter on providing accessible names and descriptions for elements. They say there are only two hard things in computer science: cache invalidation and naming things. Although caching issues aren’t relevant to ARIA, naming things is certainly one of the most important and difficult parts of making your web page structure accessible!

A new chart now shows the role names and markup guidance for common web page widgets, including alerts, banners, feeds, menus, progress bars, and tooltips. In addition, the section provides real-world examples, such as how to name a button that uses the X character as an icon (hint, the name should be “Close” not “X”) or how to handle repeated actions in a list of items (hint, always make the operative word first, so “Edit My Resource” and “Delete My Resource” are better than “My Resource Edit” and “My Resource Delete”).

<!–– Button does not have an accessible name. ––>
<button>×</button>

<!–– Button uses aria-label to provide an accessible name. ––>
<button aria-label="Close">×</button>

<!–– Button uses visible descendant content to provide accessible name.
No aria-label is needed ––>
<button>Close</button>

Other important additions were a section on live regions, which describes how to use aria-live to properly annotate sections of a web page which are updated without user input, and a section on range-related properties, which help indicate the relative position of widgets like sliders or progress bars.

We also clarified the usage of attributes related to a web page’s structural hierarchy. We added a new section on the accessibility tree and how developers can use the aria-hidden attribute to selectively hide parts of the document. Similarly, we documented how to use aria-level to provide detailed hierarchical information for things like headings, list items, and rows.

Improving the ARIA spec and browser implementations

One side effect of writing documentation to explain the correct usage of a specification, is that bugs in the spec itself and bugs in the browser implementations of the spec both come to light! In the process of contributing to the Authoring Practices guide, we uncovered a number of issues that needed clarification in the spec itself and in associated specifications that cover how ARIA is integrated into other parts of the web platform. These issues tended to be about consistency between similar elements or improving the wording for the algorithms used to calculate accessible names. We also filed a bug in Chromium after discovering that aria-level attributes only worked up to a certain value.

In general, the process of specifying any web platform feature involves a feedback loop between browser developers implementing the spec and spec writers incorporating suggestions from browser developers. As we discovered in our blog post about maintaining Test262, the presence of a third party, such as a test maintainer or in this case a developer documentation author, often contributes positively to the balance between implementers and spec writers and helps uncover valuable issues along the way.

Going forward, we hope to continue contributing to the ARIA Authoring Practices guide in order to make it easier for developers to correctly add accessibility markup to their web pages. In addition, we hope to invest in a broader set of tools such as validators and accessibility auditors in order to provide comprehensive support to developers making accessible apps. Whether you’re new to ARIA or a veteran at adding labels, check out the Authoring Practices guide for more context and practical implementation techniques. If you have any ideas for how to improve the guide, don’t hesitate to file an issue and get involved!