Testing your accessibility

Testing your product's accessibility

This guide contains instructions and recommendations that you can use to robustly test your product's accessibility, in order to identify accessibility issues and opportunities for improvement.

Keep in mind that this guide will not cover every scenario.

Standard testing procedures

Many accessibility issues can be found by doing a few standard checks.

Validate your HTML

Good accessibility practices start with structural, semantic HTML. When a screen reader (or any sort of assistive technology) scans a web page, it gets information about the Document Object Model (DOM), or the HTML structure of the page. No styles or JavaScript will be read by a screen reader.

Screen readers (like Voice Over (VO), NVDA, or JAWS) don't just turn text into speech. They also use information in the HTML to list all of the headings on a page, give extra navigation controls to data tables, announce how many items are in a list, and more. This makes semantic HTML essential.

You can use an HTML validation tool to test your product, such as W3C’s markup validation service.

Check for accessibility violations with an audit tool

When using PatternFly, we recommend checking for accessibility violations locally via aXe: The Accessibility Engine (using aXe DevTools, the Chrome extension, or the Firefox extension). If you want to test prior to deployment, you can integrate aXe with Cypress.

Bulk testing with the patternfly-ally script

We offer the patternfly-a11y script for bulk testing, which reports any aXe accessibility violations from a set of pages. You can adapt this script to your needs by creating a configuration file that includes authentication, waits for specific items to finish loading (like a loading spinner), or addresses other items relevant to your use case. As a report, this script will deliver an accessibility report via surge.

Before using this script, your UI should be built in the CI workflow. Once built, create a job to run the script against that build. The script assumes that a web server is running and serving your product somewhere that the script can reach (for example, in localhost:8000).

Test keyboard accessibility

The keyboard is an essential accessibility tool, so it is necessary to ensure that the following requirements are met:

  • All functionality is keyboard accessible.
  • Elements in the HTML and in the layout follow a logical order.
  • Elements with focus are clearly visible.

Test without styles

Screen readers cannot access style information, so you should disable styles for your product to test that your information architecture is effective and that elements have adequate text labels.

The WAVE browser extension from WebAIM allows you to disable styles if this isn't available in the browser you are using.

Test with a screen reader

You can test with any screen reader that is available in your operating system. In PatternFly, we target:

Check color contrast

Your UI's colors should pass the following contrast checks to ensure that users across the vision spectrum can understand your product:

Accessibility testing checklist

To keep track of your testing efforts, we recommend referencing the following checklist.

This checklist includes some of the main areas that the PatternFly team checks for to ensure that a UI meets consistent accessibility standards. To evaluate your specific implementation, we recommend checking these same areas in your product.

Broad accessibility criteria

For example, a keyboard shortcut that navigates between all headings on a page should discover all intended headings.
Some assistive technologies will have their own means of navigation and focus management. For example, VoiceOver uses a 'VO' key plus right or left arrow keys to navigate a page. This may be different from conventional keyboard navigation.
If content should be hidden from other assistive technology like a screen reader, aria-hidden="true" should be passed instead.

Assistive technology (like screen readers) navigate the page in DOM order. If you use CSS to visually reposition elements, they may be announced in a nonsensical sequence. If you need something to appear earlier in the page, try to physically move it earlier in the DOM instead.

Structural accessibility criteria

A common practice is to use a single h1 for the primary headline or logo on a page, h2s for designating major sections, and h3s for supporting sections.

  • All form controls have clear and descriptive labels.
  • Expandable buttons display the expandable control and utilize aria-expanded to indicate that a button is expandable. aria-expanded should always have a boolean value if a button is meant to be expandable.
  • The exception to this practice is when images are primarily for presentation purposes and are not essential pieces of content. To signify that an image should be skipped by a screen reader, set the value of the alt attribute to an empty string: alt=""

    View source on GitHub