diff --git a/packages/documentation-site/patternfly-docs/content/developer-resources/accessibility-testing.md b/packages/documentation-site/patternfly-docs/content/developer-resources/accessibility-testing.md index 9f923719ef..860f128c01 100644 --- a/packages/documentation-site/patternfly-docs/content/developer-resources/accessibility-testing.md +++ b/packages/documentation-site/patternfly-docs/content/developer-resources/accessibility-testing.md @@ -2,104 +2,111 @@ id: Testing your accessibility section: accessibility --- +import { Checkbox } from '@patternfly/react-core'; -## General testing +# Testing your product's accessibility -Many accessibility issues can be found by doing a few simple checks: +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. -1. **Validate your HTML.** Structural, semantic HTML is the key starting point toward good accessibility practices. When a screen reader (or any sort of assistive device) 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. +**Keep in mind that this guide will not cover every scenario.** - - Screen reader software like Voice Over, NVDA, or JAWS doesn’t just turn text into speech. It can use information in the HTML to list all of the headings on a page, give extra navigation controls to data tables, or announce how many items are in a list, among other things. This makes semantic HTML essential. +## Standard testing procedures - - There are many tools you can use to validate your HTML, such as [W3C’s markup validation service](https://validator.w3.org/). +Many accessibility issues can be found by doing a few standard checks. +### Validate your HTML -2. **Use an accessibility audit tool to check for violations.** If you are using PatternFly in your project, we recommend using [aXe: The Accessibility Engine](//www.deque.com/axe/) to check for accessibility violations locally. To make it even easier for you, we've created the [patternfly-a11y script](https://github.com/patternfly/patternfly-a11y) which reports any axe accessibility violations from a set of pages. A configuration file can be set to customize to specific needs like authentication, waiting for any specific items to finish loading (like a loading spinner), etc. When used as a report, it will give an output [similar to this example](http://a11y-os.surge.sh/). The UI should be built first in the CI workflow and then a job created to run the a11y script against that build. The a11y script assumes that there is a webserver running somewhere that is serving up the pages, i.e. in localhost:8000, that it can reach. If you want to test a step before deployment, you could follow the path of integrating axe with cypress. If you are contributing to PatternFly, refer to our [README.md](//github.com/patternfly/patternfly/blob/main/README.md#testing-for-accessibility) on how to run this tool. +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. -3. **Test keyboard accessibility, and check that these 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. +You can use an HTML validation tool to test your product, such as [W3C’s markup validation service](https://validator.w3.org/). +### Check for accessibility violations with an audit tool -4. **Disable styles**, then test the information architecture and presence of adequate text labels. The [WAVE browser extension from WebAIM](//wave.webaim.org/extension/) provides this feature if it isn't available in the browser you are using. +When using PatternFly, we recommend checking for accessibility violations locally via aXe: The Accessibility Engine (using [aXe DevTools](https://www.deque.com/axe/devtools/), the [Chrome extension](https://chrome.google.com/webstore/detail/axe-devtools-web-accessib/lhdoppojpmngadmnindnejefpokejbdd), or the [Firefox extension](https://addons.mozilla.org/en-US/firefox/addon/axe-devtools/)). If you want to test prior to deployment, you can integrate aXe with [Cypress](https://www.cypress.io/). + +#### Bulk testing with the patternfly-ally script +We offer the [patternfly-a11y script](https://github.com/patternfly/patternfly-a11y) 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](http://a11y-os.surge.sh/). -5. **Test with any screen reader available in your operating system.** We target these screen readers to test PatternFly: - - JAWS with Chrome, Windows ([JAWS keyboard shortcuts](//dequeuniversity.com/screenreaders/jaws-keyboard-shortcuts)) - - Voiceover with Safari, Mac ([Voiceover keyboard shortcuts](//dequeuniversity.com/screenreaders/voiceover-keyboard-shortcuts)) - - NVDA with Firefox, Windows ([NVDA keyboard shortcuts](//dequeuniversity.com/screenreaders/nvda-keyboard-shortcuts)) +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: -6. **Check color contrast for the following:** - - Text color against background color ([Understanding WCAG 1.4.3](//www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html)) - - Text color against link color ([Technique G183](//www.w3.org/TR/WCAG20-TECHS/G183.html)) - - Visible boundaries of buttons and form elements against adjacent background color ([Understanding WCAG 1.4.11](//www.w3.org/WAI/WCAG21/Understanding/non-text-contrast.html)) +- 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](/wave.webaim.org/extension/) allows you to disable styles if this isn't available in the browser you are using. +### Test with a screen reader -## Screen readers -Just as front-end developers use their browser to see how their changes look, you should use a screen reader to see how your accessibility looks (we use Voice Over). +You can test with any screen reader that is available in your operating system. In PatternFly, we target: + - [JAWS](https://www.freedomscientific.com/products/software/jaws/) with Chrome, Windows ([JAWS keyboard shortcuts](//dequeuniversity.com/screenreaders/jaws-keyboard-shortcuts)). + - [VoiceOver](https://support.apple.com/guide/voiceover/welcome/mac) with Safari, Mac ([VoiceOver keyboard shortcuts](//dequeuniversity.com/screenreaders/voiceover-keyboard-shortcuts)). + - [NVDA](https://www.nvaccess.org/download/) with Firefox, Windows ([NVDA keyboard shortcuts](//dequeuniversity.com/screenreaders/nvda-keyboard-shortcuts)). -Generally, screen readers access the DOM (Document Object Model), and they use browser APIs (Application Programming Interfaces) to get the information they need. In this way, a screen reader knows what to say when a set of list items begins and ends, and it typically announces, in advance, how many items are in the list. A screen reader can also traverse a page using heading navigation to speak the heading level. +### 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: + - Text color against background color ([Understanding WCAG 1.4.3](//www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html)) + - Text color against link color ([Technique G183](//www.w3.org/TR/WCAG20-TECHS/G183.html)) + - Visible boundaries of buttons and form elements against adjacent background color ([Understanding WCAG 1.4.11](//www.w3.org/WAI/WCAG21/Understanding/non-text-contrast.html)) -Here are a few aspects that can affect how screen readers communicate information: +## Accessibility testing checklist -- **Semantic HTML**: Semantics refers to the meaning of a piece of code. A semantic element clearly describes its meaning to both the browser and the developer. For example, `