Notes on relying on the ARIA Authoring Practices Guide

Eric wrote about how to instruct an LLM to fetch the "valuable stuff" from the ARIA Authoring Practices Guide (APG). The article includes some points about APG itself that are worth highlighting. And what's the valuable stuff?

If you don't know the Authoring Practice Guide, here's what you'll see after finding it online looking for ARIA patterns.

As you see above, the guide is supposed to teach how to use accessibility semantics defined by the Accessible Rich Internet Application (ARIA). And it looks very authoritative. When I first discovered it after some googling, I treated this guide as the source of truth because it lives under w3.org and looks very official. I learned early on that using ARIA correctly is hard; and thought that APG must be the place showing me how to do ARIA correctly.

It sort of is but not really.

Lately, I've seen many accessibility folks raise concerns about APG, and Eric's article echoes some of them.

The APG was created to demonstrate ARIA's capabilities. Because of this, it disproportionately favors ARIA in its code examples.

The guide is there to showcase ARIA usage patterns and if people want to showcase something they might overuse it at times. This is true for ARIA usage in the APG, too.

The APG was also not created to serve as a pattern library, design system, or single source of truth for the "right way" to make something. Unfortunately, a lot of people treat it this way.

I understand Eric's point, but I also can't blame people for treating the guide as "the right way". The home page literally says that "APG provides design patterns and functional examples". It's hosted on w3.org. It looks very official. If there's a line between "a collection of design patterns" and a "pattern library" at all, it's a very thin one.

Of course people treat the Authoring Practice Guide as the right way to do things — when I discovered it, I did, too.

Recall here that the original reason for APG code is to be a showpiece for how ARIA could hypothetically be used. Because of this, it is not the APG's concern that ARIA does not have perfect support.

This is by far the biggest reason why I don't pretend to know when something is truly accessible. Nothing is ever fully accessible to everyone, and the world of assistive technology is huge. A single ARIA attribute might make things more accessible in theory, but who knows if it works across all browser-screen reader combinations.

The effort alone to verify that an ARIA pattern works well across assistive technologies is massive.

But what are the guide's valuable parts? Eric highlights the pattern names, "about this pattern" section and the keyboard interaction specification.

The pattern names. Having a standardized way to refer to a discrete piece of UI that is larger than any one company is highly beneficial.

The content contained in the "About This Pattern" section. This is what the discrete piece of UI does, and how it goes about doing it.

The content contained in the "Keyboard Interaction" section. This is how people who use assistive technology will expect things to work.

That's good to know!

So if you've been treating APG as the definitive source of truth, think again. Its examples demonstrate what ARIA can do, not necessarily what you should do.

It doesn't matter if you've discovered the ARIA Authoring Practices Guide or not, before reaching for a complex ARIA pattern found on the internet, the usual rules apply:

• Always start with native HTML: the first rule of ARIA is to use a native HTML element before adding ARIA. A <button> beats a <div role="button"> every time regardless of what's written in a fancy ARIA guide or what your LLM claims to be accessible.
• Test with assistive technology yourself: nothing beats firing up a screen reader and actually navigating your own UI. It's hard and time-consuming but you can't claim that something is accessible if you haven't tested it.
• Follow practitioners who do the testing: as you might know, I'm a huge fan of Adrian Roselli who constantly puts in the work of testing ARIA patterns with different assistive technology combination. He publishes findings on what actually works versus what the spec promises. Huge!

Edit: Eric (partly responsible for the Authoring Practices Guide) shared on Mastodon how the project evolved into what it is today.