July 26, 2022

Web Accessibility Fundamentals

Note: this article originally appeared in the Postlight engineering knowledge base.

Learning about accessibility (often abbreviated to just a11y) is an incremental process. It takes time and intentional practice to cultivate an inclusive mindset towards web development — and more effort to understand how to incorporate that mindset into the development of common UI design patterns.

A very common pain point for anyone who wants to learn more about web accessibility is that the most well-known, authoritative source on accessibility compliance — WCAG — is not easily readable. Each of its individual requirements read like boilerplate legal jargon.

The guidelines are (of course) meaningful. And for the purpose of establishing a shared accessibility standard, a good goal for projects is to meet (or exceed) WCAG 2.1 AA success criteria.

But please don't feel you need to read every single page of WCAG in one go. The following guidelines are intended to feel like a more readable, more supportive starting point.

Human-readable information on WCAG and what AA success criteria entails can also be found in the Web Content Accessibility Guidelines provided by WebAIM.

How to Get Started

Use HTML Elements Whenever Possible

The easiest way to establish a baseline of accessibility for a website or web application is to familiarize yourself with semantic html elements, which will always provide the best experience to disabled and even non-disabled users.

Some specific best practices include using tables for organizing tabular data instead of divs; using list elements (ul and li) for navigation; and using a native select element — which can be heavily customized — instead of a listbox or a third-party dropdown like React-select.

The MDN Web Docs provide a reference page for all HTML elements as well as in-depth guides on each individual element.

If you aren't entirely sure what markup might be appropriate for a particular design situation, websites such as CSS Tricks, Smashing Magazine, and the personal blogs of accessibility advocates — especially Adrian Roselli— can be particularly helpful resources.

Use ARIA Attributes Only When Necessary

ARIA (or Accessible Rich Internet Applications) is a collection of attributes that allow developers to convey additional information to individuals using assistive technology.

This is particularly useful in situations where the semantic value of an html element might not be enough to enable someone to make an informed decision. For example, when a button that says "Menu" doesn't allow someone to understand if the menu is already opened or closed.

Other situations where ARIA attributes can be profoundly helpful include: modals, complex tabbed interfaces, and error messaging.

When considering whether or not to use ARIA, please keep in mind that:

  • ARIA doesn't replace or add any new functionality to existing html elements. Its main role is to provide additional descriptive information. (Note: it can also be used to hide decorative elements!)
  • There are situations where lots and lots of additional, descriptive information may hinder, rather than help someone.
  • The phenomenon of ARIA decreasing, rather than improving, usability is especially true in situations where a non-semantic element (such as a div) is being used in place of a more menaingful element, such as a button.
  • Support for various aspects of ARIA can vary between browsers, and there can be bugs in certain implementations of it.

No ARIA is better than bad ARIA: so it's always a wise decision to err on using it sparingly, in situations where you feel confident you understand why adding ARIA attributes is necessary. Deque provides additional considerations on ARIA in their guide, ARIA Spec for the Uninitiated.

Not all ARIA attributes are equally supported by browsers or recommended by accessibility experts. You can learn more about how well-supported different ARIA attributes are in different forms of accessibility technology on the Acessibility Support website.

Learn to Use A Screenreader

Apple's screenreader software, Voiceover, is pre-installed on all Mac OS and on iOS devices and can be used to manually test how a website will be interpreted by blind and low-vision users.

If you are using a Mac keyboard with a Touch Bar, you can toggle Voiceover by pressing Touch ID three times while holding the Command key. If you are using a more conventional keyboard, you can also toggle it by pressing Command + F5.

While using Voiceover, keep in mind that rather than navigating pages one html element at a time, many screenreader users navigate websites by quickly scanning multiple navigational elements (including headings, links, and other interactive elements). This is part of why it's so important for html elements to provide useful, comprehensive information.

You can jump between navigational elements with Voiceover's rotor, which groups together similar navigational elements together into lists and can be activated by hitting Control + Option + U.

The a11y project provides additional information and resources for how to navigate websites in their guide, "Getting Started with Voiceover."

Add Automated A11y Tests To Your Project

There are many ways in which you can integrate automated accessibility testing into Postlight projects.

Jest-axe If you are already using Jest (a testing framework that is frequently used with React) you are already well-positioned to take advantage of an open-source library called Jest-axe.

Jest-axe is an open-source library that extends Jest with custom matchers provided by Deque's axe-core automated accessibility engine. Or put more simply, it makes it easier for Jest to catch accessibility issues. It also seamlessly integrates with React Testing Library and Enzyme, and provides its own types, for Typescript integration.

Since release, the library has been featured in the Kent C. Dobbs "Testing Javascript" course as well as a short talk at Australia's accessibility conference, A11y Camp, which includes many helpful tips for getting the most out of the library.

If you are not using Jest, the axe-core accessibility suite that Jest-axe is built on top of can be used on its own (although you will have to develop your own way to assert errors that come up as a result of a failed accessibility test).

Please note: Adding automated accessibility testing is estimated to catch only roughly 30% of a11y issues. Why 30 percent? The a11y collective has more answers, in "How reliable is automated accessibility testing"?

The axe Accessibility Linter extension for Vscode The axe accessibility linter is a free browser extension which checks code as you write it.

Storybook's a11y Addon The Storybook team maintains a first-party addon, storybook-addon-a11y that will display a11y warnings for individual states of each variant of a story.

Browser ToolsThe Accessibility Engine or aXe, is an accessibility browser extension built on top of the same axe-core library that powers Jest-axe.

Lighthouse, built by Google, includes accessibility warnings among other issues in its automated page audits. More information on the subset of accessibility issues that it tests for are detailed in the documentation.

The WAVE Browser Extension is an additional option maintained by Utah State University.

Follow Accessibility Advocates

This is a very small list of people, that will (and should) grow over time!

Read online accessibility resources

Explore Accessibility-Oriented UI Libraries

  • Adobe's React-Aria library focuses on providing React Hooks as UI primitives for developing accessible design systems
  • The Reach UI library, maintained by the React Training team focuses on providing reusable React components
Return