Friday 26 Jun 2026

Please take a minute to understand what ARIA is and is not. ARIA and especially the ARIA Authoring Practices Guide (APG) are commonly misunderstood.

I read an article the other day that had this facepalm moment:

And with modern LLM agents, turning a spec into working code is surprisingly fast. Point the agent at the APG pattern, describe your component’s markup, and get a solid first draft you can refine and test.

This is worrying, and the use of “LLM agents” isn’t the worst part!

The APG is not a how-to guide of ‘best practices’ for building accessible websites. It exists to demonstrate how the ARIA specification should work in theory — regardless of support and regardless of whether more accessible, non-ARIA patterns exist (they do).

As Eric Bailey notes —

The guide was originally authored to help demonstrate ARIA’s capabilities. As a result, its code examples near-exclusively, overwhelmingly, and disproportionately favor ARIA.

What I Wish Someone Told Me When I Was Getting Into ARIA - Eric Bailey

— which makes sense, because:

Browser and assistive technology developers can thus utilize code in this guide to help assess the quality of their support for ARIA 1.2.

Read Me First - ARIA Authoring Practices Guide (APG)

Even if ARIA was fully supported (it’s not) the APG still wouldn’t be a ‘best practice’ guide. ‘Best practice’ is not using ARIA at all.

If you can use a native HTML element or attribute with the semantics and behavior you require already built in, instead of re-purposing an element and adding an ARIA role, state or property to make it accessible, then do so.

2.1 First Rule of ARIA Use - Using ARIA, W3C

APG exists in a vacuum to show off the ARIA spec.

The button example includes this code, for crying out loud!

<div tabindex="0"
     role="button"
     id="action">
  Print Page
</div>

I’m unaware of any circumstance where <div role="button"> should ever be used over a <button>. Before you tell me you can’t edit your React component library, do the web a favour and delete your codebase.

In fairness, the button example has a “Read This First” disclosure — and guess what: they use a <details> element and not the disclosure pattern because the APG isn’t best practice. It’s hard to blame developers for misusing ARIA and the APG. I’ve been confused myself. As W3C documentation goes, APG is rather sexy. It’s a useful resource if you understand why it exists.

Misuse of ARIA has made the web less accessible.

Increased ARIA usage on pages was associated with higher detected errors. The more ARIA attributes that were present, the more detected accessibility errors could be expected.

The WebAIM Million - WebAIM

TL;DR

Avoid ARIA where ever possible. Don’t point a freaking LLM at the APG! I can’t believe I’m saying this but use Google’s slop if you absolutely refuse to learn/code yourself. Apparently OpenAI is throwing ARIA at the web and seeing what sticks. Ahhh! I don’t know anymore, take some pride in your expertise?

P.S. name an assistive technology that isn’t a screen reader.

Ain’t easy, is it? So don’t be casually punctuating with the word “test” like it’s some get-out-of-jail-free card for your dubious practice and advice.

“Overview of Digital Accessibility Technologies” by Declan Chidlow is a great help if you want to win this game at parties.