Your Accessibility Claims Are Wrong, Unless…

Antique black and white photo of a man in dark suit and stovepipe hat pushing a wooden cart full of bottles, their labels illegible.

Now that it is a market differentiator to talk about accessibility in projects, that’s all many do — talk about it. In a sea of pop-dev noise, “accessibility” can be claimed with little risk someone will challenge it. If someone does, the response is often a fine balance between silence and accusations.

I offer some approaches you can and should take before you set expectations about the accessibility of your thing — code or article or talk or whatever.


I am breaking this up into content creators and their backers. Content creators may write articles, make demos, deliver talks, host podcasts, and plenty more. Their backers may be tech companies, dev sites, industry events, or even browser makers.

For Content Creators

If you are discussing or creating a new pattern or library or technology or talk or article or whatever:

  1. Don’t assert anything about how it works with assistive technology.
  2. Don’t assert anything about its accessibility.

Be honest and say that you don’t know. It’s ok not to know, so admit it freely. Reader beware and all that.

For Organizations Backing Those Content Creators

If you are backing that content creator:

  1. Get them (paid) support, training, or an expert to test with or coach them on assistive technology.
  2. Ensure your your content creators are frank about the (lack of) accessibility considerations and make it a visible and standard clause in everything they create.

Otherwise you risk leaving them hanging when they publish problematic content, making them feel like they are standing alone in the cold. Never mind how that affects your brand.


Unless you (or the designated editors) ask a few questions:

  1. Assistive technology (AT) questions:
    • Are you a daily user of AT?
    • Are you involving daily users of AT?
    • Do you already use AT for testing?
    • Do you know how to use the AT?
    • Do you have a daily user of AT involved?
    • Are you aware there is AT besides screen readers?
    • Do you consider system settings to be AT?
  2. Accessibility questions:
    • Do you mean WCAG (and if so, which SCs)?
    • Do you mean ADA?
    • Do you mean Section 504?
    • Do you mean Section 508?
    • Do you mean ACAA?
    • Do you mean CVAA?
    • Do you mean ACA?
    • Do you mean AODA?
    • Do you mean EN 301 549?
    • Do you mean “works with a specific AT”?
    • Do you mean usable by everyone regardless of ability?

For the AT questions, the more “no”s you had the less likely you should make any assertions about how your thing works in AT.

For the accessibility definition questions, readers may believe the thing you wrote conforms with all those laws or guidelines (and many more). Also, one of those was a red herring that I hope you caught as soon as you saw it.


For more information on what it means for something to be accessible, head over to the W3C’s Web Accessibility Initiative and dive in. For the red herring I referenced, it was the ADA.

For AT, I am going to focus on screen readers since it is where I see the most alarmingly wrong information from “expert” developers promoting their thing. Consider that ARIA is useful only for screen readers and ARIA mis-use is a multiplier of bad for screen reader users.

Screen Readers

Get some screen readers. Plural. Ideally you will cover JAWS, NVDA, VoiceOver on macOS, TalkBack, and VoiceOver on iOS. Don’t use solely VoiceOver; it is more opinionated and does not always reflect what the majority of screen reader users experience.

Keyboard shortcuts are necessary to use a desktop screen reader well (don’t rely on hitting the Tab key over and over). For mobile screen readers, learn the gestures versus swiping right repeatedly. Keep in mind mobile screen reader users often use keyboards too.

Note I did not touch on pairing with Braille displays (that was a pun). As you go down that path there will be more to learn, including how content may be truncated to fit a Braille display.

Added 28 November 2022: Sara Soueidan has posted an excerpt from her forthcoming Practical Accessibility course that goes into far more detail than I do above, including for macOS users who do not have a Windows machine (though you should get your boss/client to just buy you one, they are cheap): Setting up a screen reader testing environment on your computer

Other AT

There is plenty of other assistive technology. The booring keyboard is the most common one, though it does not always look like the one mounted to your laptop (or have the same number of keys).

Do you know how Space and Enter behave differently when pressing a native <button>? If not, then probably test those scenarios for your fancy custom button widget.

Centre for Accessibility Australia has a nifty resource for using the accessibility features built into your OS or device. Read through it. Try them all out. Try them out on your thing. Ask users of those settings to try your thing. Lather, rinse, repeat.

Best Practices

Validate your stuff. I know that is trickier with custom elements and fancy frameworks, but just using the W3C HTML Nu Checker could keep you from easy mistakes like typos.

Remember that if you start building features for assorted user preferences, everything related to accessibility still applies. For example, if you make a dark mode it still has to honor WCAG contrast minimums.

Other system settings aren’t necessarily AT, but not honoring them can be disabling for many. For example, Windows High Contrast Mode (AKA Contrast Themes or forced-colors mode). You don’t choose the colors, the users do from a limited palette. Which you should not override. But for which you may need to account in what elements you choose.

Show Your Work

Don’t assert the thing works in screen readers (for example) and leave it at that. Tell me which screen readers (plural). Tell me which versions of those screen readers on which operating systems with which browsers and which versions of those browsers.

Tell me how you tested it, which commands, which interaction mode (sticking with screen readers here), what was announced, where they differed.

Better yet, make a video. A human captioned video. That does not autoplay. Showing AT with standard commands. And no mouse (still using screen readers as my example). Most screen readers have a speech viewer or log which is a good start. Beware that those logs often do not fully represent what is announced.

For an extreme example of both approaches, see the Results section in my post Accessible Description Exposure. It includes announcements, how I navigated, videos, and even screen shots of the elements lists. This way users have steps to recreate it.

Though that may be overkill for most. You could get by with something like, “Only VoiceOver on macOS announced the thing; JAWS, NVDA, and TalkBack ignored it no matter how I navigated.” Obviously include details on your testing kit somewhere so folks understand which versions of which screen readers with which browsers.

Do not rely on the output of the accessibility inspector in your browser dev tools. What is exposed there may be different than what is exposed in the OS accessibility APIs and thus exposed to users.

And, for the love of His Noodly Appendage, do not use “a11y” in your long-form writing. Write it out.


To try to distill this into the main takeaways:

Each day articles and talks and demos are shoved into our timelines, making us feel like we are falling behind. If you want to make a thing, maybe these resources can help calm that feeling by boosting your work quality in ways most do not properly consider — the accessibility of it.



This Article was mentioned on


This Article was mentioned on


And while you are there, don’t conflate “accessibility” with “screen reader”. The latter is just a subset of a much larger issue, which often gets ignored.
I’ve had just yesterday that I reported an accessibility problem and the answer was “mind telling us which screenreader you are using?”. The problem was to do with their colours making a bit of text extremely hard to read for people with low vision, and it somehow managing to override the custom CSS I use, so not sure how they even thought about a screenreader.

Uilebheist; . Permalink

Thanks for the link to the VoiceOver command charts. i am starting with VoiceOver because it’s already on my devices as i begin this journey


Yes! “Don’t assert the thing works in screen readers (for example) and leave it at that. Tell me which screen readers (plural). Tell me which versions of those screen readers on which operating systems with which browsers and which versions of those browsers.”

I am currently looking over an audit for a client done by Bureau of Internet Accessibility and it’s shocking that there is no mention of technology used for testing. I’m worried that they’re just trying to sell us an overlay or something.

In response to Josh Dreier. Reply

Generally the contract, scope, and/or test plan for a WCAG review will list the technologies used. They are not as relevant in the results except to call out specific quirks or bugs that only appear in that technology.

That being said, if you have a vibe they may be pushing you to an overlay then be aware that Bureau of Internet Accessibility is owned by AudioEye and AudioEye is an overlay vendor.

Leave a Comment or Response

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>