From c35ccf7acf442703c2083cdb2d28e043cacf3d3d Mon Sep 17 00:00:00 2001 From: Erin Donehoo <105813956+edonehoo@users.noreply.github.com> Date: Mon, 15 Jan 2024 10:26:18 -0500 Subject: [PATCH] docs(accessibility-testing): Updates content as part of content audit. (#3776) * docs(accessibility-testing): Updates content as part of content audit. * Apply suggestions from code review Co-authored-by: Eric Olkowski <70952936+thatblindgeye@users.noreply.github.com> * Apply suggestions from code review * Content tweaks in progress. * Works on checkboxes. * Resolves merge conflict. * Update packages/documentation-site/patternfly-docs/content/developer-resources/accessibility-testing.md * Update packages/documentation-site/patternfly-docs/content/developer-resources/accessibility-testing.md Co-authored-by: Eric Olkowski <70952936+thatblindgeye@users.noreply.github.com> * Update packages/documentation-site/patternfly-docs/content/developer-resources/accessibility-testing.md Co-authored-by: Eric Olkowski <70952936+thatblindgeye@users.noreply.github.com> * Content alterations. * Content changes from review feedback. * Updates to buttons point. * Grammar and typo updates. * Update packages/documentation-site/patternfly-docs/content/developer-resources/accessibility-testing.md Co-authored-by: Eric Olkowski <70952936+thatblindgeye@users.noreply.github.com> * Merging. --------- Co-authored-by: Eric Olkowski <70952936+thatblindgeye@users.noreply.github.com> --- .../accessibility-testing.md | 135 +++++++++--------- 1 file changed, 71 insertions(+), 64 deletions(-) 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, `
` and `` are non-semantic elements because they don't describe their contents. Examples of semantic elements include `
` and ``, which clearly define their contents. Screen readers expect semantic HTML when traversing the DOM, so non-semantic elements that aren't customized to be made accessible are highly likely to be inaccessible. Aria and other accessible attributes are meant to extend the functionality and meaning of native semantics, but at the core, your HTML should be semantic. +To keep track of your testing efforts, we recommend referencing the following checklist. -- **Headings**: A visual user can scan a page and fairly quickly understand its information architecture. Visually impaired users have other methods of achieving this. One common method is using heading levels to determine the flow of information. Headings that vary in size simply based on design and not functionality will likely confuse these users. A clear flow of sequential heading sizes based on headings and subheadings is significantly clearer to all users. +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. -- **Accessible names for all elements**: When an element doesn't have visual text or when further explanation is necessary, a screen reader will not know what an item is or does. For example, if you have an icon `