My ideal accessible components resource is holistic, well tested and easy to use

It would be easier to have an accessible web if all we did with it was publish documents. Blobs of text, images here and there. But modern sites (or “applications”) do a lot more than documents. Often for better, sometimes for worse. To improve accessibility of the web as it is today, I feel we dearly need accessibility guidance that is holistic, well tested and easy to use.

Web sites or applications often come with menus, tooltips, dialogs, drag and drop, tabs and emoji pickers. Some say this is unnecessary and argue interfaces must be simpler. Sometimes they are right—a lot of interfaces can benefit from being simpler. Yet, complex UI components are often genuinely helpful to users. Like, it's good if not all information is always visible at the same time. Hiding less important stuff in less prominent places can help hierarchy. It can be good if, instead of selecting a city from a <select> of thousands, there's some comboboxing going on. ‘No that's an input!’, you say… yeah, maybe, but it could be important for the business to have a city chosen out of a predefined list of options. And that can give certainties that are beneficial to users too.

So, complex UI patterns (widgets, components, etc) are sometimes needed. A lot of sites have them, for reasons ranging from good to bad. A lot of organisations hand-build these components as part of a design system effort, to make their investments reusable. Reusable components can have a huge impact on accessibilility. Because reuse means repetition: of good patterns, bad patterns, accessible patterns, inaccessible patterns… the stakes are high!

Over the years I've seen and heard a lot of developers talk about building components. I heard them speak about the developer experience of building these components. When I was working on guidance at WAI, I listened extra carefully. From what I gathered, many actually want to truly invest in the quality of their components, including the accessibility of those components. But the official guidance they can find is lacking: WCAG's supporting documents are often unclear (with reading levels, for what they are worth, up to professor grade), unpractical (a lot more words than concrete advice) and outdated (eg still recommending the title attribute). WCAG still works best for the web as a series of documents.

In other words, to better match the realities of people making websites, I feel the W3C's accessibility guidance should be more holistic, well-tested and easy to use.


The closest to a guide on building accessible components is the ARIA Authoring Practices Guide (“APG”). It's a super useful resource for finding how to build components with ARIA, but it isn't “holistic”.

By holistic advice, I mean advice that considers the reader within their entire environment as a developer. Advice that builds on the best that can be done with HTML, CSS, JavaScript, WAI-ARIA and SVG (technologies websites commonly rely upon). The WAI-ARIA Authoring Practices Guide isn't holistic in that sense: it focuses on patterns built with ARIA only. From developer-who-wants-advice or user-who-needs-a-good-experience perspectives, that's not ideal. As accessibility specialists learn again and again, WAI-ARIA isn't what makes components accessible, it's merely one of the languages (ok, an ontology) that can help us build accessibly (see also: the first rule of ARIA). I don't mean to say any of these specificiations is inherently better, I mean the most accessible component is always some combination of these specs.

If that's the case, you may wonder, why does APG focus on ARIA only? There's no bad intent here… I think it is simply because it is written by a subgroup of the ARIA Working Group. That Working Group specifies ARIA and it has a deliverable to show how to use it. This makes good sense. But again, it isn't ideal if the intention is guidance that helps developers build the very best for users with disabilities (which I think is the goal we should really want to optimise for). Nobody seems to have that as a deliverable.

There is a W3C/WAI resource that is holistic in the way I described: WAI Tutorials. Shoutout to the great work of Eric Eggert and EOWG! It's a good resource, but it did not get expanded or updated much after the initial release.

There are resources outside of W3C/WAI that I can recommend, such as:

Well tested

Web accessibility ultimately is about whether people can use a thing. Some friends in the accessibility community like to emphasise that it's about people, not meeting standards. I get that sentiment, but there's a false dichotomy at play: making the web more usable for people with disabilities is a central goal for accessibility standards at organisations like W3C/WAI) They are a means to the same end. Either way, web accessibility is all about people. So, yes, user testing matters. We've got to find out which specific patterns are mostly to work well for people.

While it's essential and beneficial to involve people with disabilities in user tests, there can be challenges:

  • just like one single user doesn't speak for all users, one person with a disability doesn't speak for everyone with that disability; you'll want larger samples;
  • there are many disabilities; sometimes people with different disabilities could even have “competing” needs. For instance, high contrast benefits some, but could constitute a barrier to others;
  • it may be more difficult to recruit users with disabilities and ensure the group you recruit for a given project is the right group in terms of what you want to test;

My friend Peter has documented some of his approach to testing with disabled users and WAI itself has a great page on involving users with disabilities too. Others have blogged about their user testing efforts: Fable tested Loom's video clipping functionality and the GOV.UK Design System team documented what they found testing conditionally revealing questions. These posts show there is a lot of nuance in determining if a complex pattern is accessible. But they also show this nuance can be described and help inform people.

As an aside: another aspect of testing guidance for accessible components is how well they perform across different browsers and assistive technologies. Bocoup, Meta and others are doing great work in this area in the ARIA-AT effort: they define tests (over a thousand drafted), but also pioneer ways to test assistive technologies automatically. I believe the plan is (was?) to show the results of this project next to code examples, which is great.

Easy to use

‘Developer experience’ is a phrase sometimes frowned upon, especially when contrasted with user experience. If we had to choose between them, of course, user experience would be the first choice. But the choice isn't binary like that. If the stars are aligned, one can lead to the other. Companies that make developer-focused products (like CMSes, versioning control, authentication, payment providers, databases etc) usually have a dedicated “developer experience” department that ensures developers can use the product well. Among other things, they try to reduce friction.

Friction could result in income loss for these companies. If the tool constantly displays unhelpful error messages, has code examples that are tricky to follow or documentation that is out of date, developers might look for a different tool. And the opposite is true too: if this payment provider makes it super easy to implement secure payments, a developer will likely want to use it again.

Friction could also cause a product to be “used wrong”. For instance, large groups of developers easily got started with this cool new authentication product, but the docs were so unclear that they missed important security steps? Or, in a CI/CD product, developers manage to get started quickly, but a majority does it in a way that uses way too many resources, because the example projects do? If the company charges overages unexpectedly, it may upset customers, if it doesn't, it could end up costing the company too much.

I'll admit it is a bit of a stretch: what if both of these frictions are at play with accessibility standards? And instead of looking for different standards, developers choose the “easier” route of inaccessibility? This could happen in places where leadership or organisational procedures don't enforce accessibility. They'll get away with it. It could also happen in places that do have a mature accessibility program or even a handful of accessibility-minded individual developers. If the most accessible solution isn't easy to learn (e.g. they get lost between different kinds of guidance), it could still result in inaccessibility, even with the best intentions.

I believe effective accessibility guidance answers “how easy will this make it for people to get it right”, and probably also ”how will this avoid that people take the wrong turn”.

Some examples of what could constitute good developer experience (dreaming aloud here):

  • easy to copy examples that closely match real-world components people are building, like privacy setting banners and comboboxes (just to name two examples of major barriers I saw blind users encounters in a user test)
  • full example projects for some popular frameworks and languages, eg here's how to build an accessible blog with Next.js, or how to report errors in a form in vanilla JS + 5 popular frameworks
  • a specific focus on eliminating inconsistencies in documentation (“boring” work, maybe, but inconsistencies inevitably creep into any set of content—the more inconsistencies are avoided, the more effective documentation is)

While these examples are developer focused, the same kind of focus could be applied other roles like quality assurance and design (see also Roles involved in accessibility, which is a great document, though still in draft status).

I suspect many people with disabilities among us have a mental list or accessibility barriere they encounter most often. Many who do regular accessibility audits will have a list of things they find often. Many developers will have a list of components they are unsure how to build accessibly. Et cetera, et cetera. If I had a magic wand, I would try and put all of these people in one room.

In summary

In this post, I've tried to lay out what my ideal accessibility guidance looks like. The gist of it is: make it easier for people to get accessibility right. And the opposite, too: make it harder to get it wrong. I feel the closer we can get to that, the more accessible interfaces can become. I think this is the way to go: guidance that is holistic, well-tested and optimised for developer experience (or, more broadly, the experience of anyone touching web projects in a way that can make or break accessibility).

And to be clear, this is not an invite for people to care less or circumvent the responsibilities and duties they have. Accessibility needs to be part of one's MVP. But it is an invite for people to rethink our collective efforts in improving web accessibility: WCAG 3.0 may not be it, the world may benefit more from better guidance than from better testing methodologies.

My expectations are probably a tad unrealistic. I probably missed my chance to try and materialise them more when I worked for WAI. Yet, I hope the perspective is helpful to some. Get in touch if you have thoughts!

Thanks to Job van Achterberg for helpful comments on an earlier draft.

Comments, likes & shares (56)

@hdv great read, another thing to add to the list of “things i’ve needed this whole time and never even knew”
My ideal accessible components resource is well tested, holistic, and easy to use.…
My Ideal Accessible Components Resource Is Holistic, Well Tested and Easy to Use, by…
My ideal accessible components resource is holistic, well tested and easy to use:… #accessibility #a11y
@hdv @deanbirkett @wai Yeah, I like all these resources, but I have also seen them making things unclear and confusing at times. I think we have to re-think how to communicate about accessibility from the core. (It would help if the official quickref would be even more useful, but it’s a taboo to simplify WCAG in other “official” documents, which is understandable.)And even well visited resources barely make a dent.
@hdv @deanbirkett @wai The tutorials get 2.5m visits every year. Most top issues are mentioned there. Some impact, for sure. But is educating and posting resources really the best thing we can do? Or can we change the system, so that it is the logical thing that an output is accessible?
@hdv Thanks for sharing! I've learned a lot from talking with @bkardell, and your experience with Open UI is fascinating. This is where I feel like a layer _on top of_ HTML helps alleviate some of the issues that standards bump into. Standards understandably need to be comprehensive, and with this approach there's kinda a "here's the 80% use case" pragmatism to it.
@hdv @bkardell All to say, it would be great to be able to create solutions for the obvious and most common use cases without being held hostage by some of the gnarlier edge cases.