Recently I’ve been working to make a client’s site accessible (a.k.a, a11y) and passing accessibility audit.

Our goal is to reach Level AA compliance. At the first glance, the WAI-ARIA best practices are pretty thorough and cover most aspects that UI implementers need, including attributes, keyboard interactions.

Even if some requirements are quirky, they have been laid out by experts already. It is a matter of following the specs and write javascript code to implement all the behaviors.

If you are having the similar thoughts, this post is for you.

I’m going to talk about all the gotchas. So hold on to your hat.

Gotcha #1: A11y is strict about HTML semantics

Most sites are for sighted users. Most sites HTML / CSS / JS contains the ugly hacks, poorly structured HTML attributes, or doesn’t follow HTML semantics at all. As long as the site is rendered visually, they get past QA and business.

And modern browsers are lenient about these poorly structured HTML code.

As a result, this leaves lots of room for hacks, e.g.,

  • Loose, or even incorrectly structured, HTML documents
  • CSS effects that promote certain effects, or hacks around the visual components
  • Visual behaviors that natural to sighted users without too much explanations, but difficult for screen reader users (e.g., hover-and-expand navigation menus)
  • Normal web dev rarely use a lot of HTML attributes, e.g., aria-label.
  • Most dev take the browser focus for granted, and rarely spend time to understand how browsers manage the focus
  • Not using the tag semantics correctly.
  • We use too much <div> to wrap any components without caring about its semantic.
  • We use div or <a> to build a button, without using the <button /> tag itself.

Modern web dev practice is quite loose on HTMl semantics.

However, screen reader software are less advanced than browsers in parsing poorly structured HTML codes. Actually, I would say most screen readers rely on HTML / JS code that strictly adhere to ARIA specs.

For that reason, screen readers struggle in most existing sites, which render them inaccessible for user with disabilities.

Gotcha #2: A11y space is in flux

In one of the projects, I took the effort to implement ARIA v1.1 combobox because that’s the recommended spec accepted by all screen reader vendors. It turns out to be false, at least for combobox.

As of writing, ARIA v1.2 is still Working Draft. However, the spec was 100% complete. In the change log notes, v1.2 combobox reverts v1.1 specs to address many implementation issues. The screen readers seem to go ahead and support v1.2 better than v1.1.

Gotcha #3: Testing in multiple environments takes lots of effort

I need to test in the following envs:

  • VoiceOver + Safari + Mac OS X
  • JAWS + Chrome + Windows
  • NVDA + Firefox + Windows

Generally, there could be bugs with screen reader software itself (Some versions of NVDA + Firefox combo may break). When testing, it took efforts to figure out it’s our implementation problem, or the environment.

Gotcha #4: A11y spec is not exhaustive

For web accessibility, we have rather detailed ARIA spec. But there are many possible combinations of HTML attributes, and not all of the behaviours are documented down. Even for our a11y auditor, when virtual cursor movement failed, they may recommend adding tabindex="-1" attributes to work around it, but it may not be the ultimate fix.

This issue is exacerbated by the following issues

Gotcha #5: Screen reader software implementations vary in subtle ways.

JAWS and VoiceOver are both proprietary, so a lot of behaviors are not 100% specified, esp. involving the virtual cursors. We had to test it on all environments to make sure it covers all a11y issues.

Generally VoiceOver is substantially different from the other two.

Gotcha #6: Screen reader virtual cursors are tricky to work with.

To make the best experience for screen reader users, it is important to make sure virtual cursors (or virtual focus) work. And this is different from the existing Web development practices.

Virtual focus is different from browser focus, which is relatively well understood and manipulated by Javascript.

But virtual cursors are less understood. One big gotcha is screen readers intercepts Space / Enter / Arrow keys, and won’t pass them to the webpage / Javascript. Here’s a good article about this

This ties back to previous issues regarding screen reader implementation.

To get virtual focus working, there is no other good ways except:

  • Follow ARIA specs strictly and set the aria-* attributes correctly

Gotcha #7: Screen readers have different modes

This is another screen reader quirks. Generally, there are browse and focus mode. The main impacts are on the keyboard interactions. Different modes may intercept your keyboard input and not pass to the webpage / Javascript.

One example is, when you set role="application" , it instructs screen readers to hand over to the browser and web application to handle mouse, keyboard, or touch interaction.

Gotcha #8: ARIA reference implementations are not gold

When implementing the combobox, I followed ARIA v1.1 spec. Specially, we copied the reference implementation from the official ARIA site. It failed our auditor’s tests, and we had to add more implementation.

So use the reference implementation as a start, and expect to add more tweaks. They are not gold, unfortunately.

Email Newsletter

I write about code and entrepreneurship. Sign up and get my updates straight to your inbox!

Junji Zhi

Senior Software Engineer.