docs(accessibility-testing): Updates content as part of content audit.

packages/documentation-site/patternfly-docs/content/developer-resources/accessibility-testing.md

@@ -3,83 +3,79 @@ id: Testing your accessibility
 section: accessibility
 ---
 
-## General testing
+# Testing your product's accessibility 
 
-Many accessibility issues can be found by doing a few simple checks: 
-
-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. 
-
-   - 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. 
-
-   - There are many tools you can use to validate your HTML, such as [W3C’s markup validation service](https://validator.w3.org/). 
-
-
-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.
-
-
-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.
+The following guide contains instructions and recommendations to comprehensively test your product's accessibility to identify accessibility issues and opportunities for improvement.  
 
+## General testing recommendations 
 
-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.
+Many accessibility issues can be found by doing a few simple checks: 
 
+### 1. Validate your HTML
 
-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))
+Good accessibility practices start with structural, semantic HTML. 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. 
 
+Screen reader software like Voice Over (VO), 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, announce how many items are in a list, and more. This makes semantic HTML essential. 
 
+There are many tools you can use to validate your HTML, such as [W3C’s markup validation service](https://validator.w3.org/). 
 
-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))
+### 2. Check for accessibility violations with an audit tool
 
+ If you are using PatternFly, 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. 
+
+ To use this script, a configuration file can be set to adapt our script to your 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.
 
 
-## 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). 
+### 3. Test keyboard accessibility
 
-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. 
+Because the keyboard is a key accessibility tool, it is necessary to ensure that the following requirements are met: 
 
-Here are a few aspects that can affect how screen readers communicate information:
+  - All functionality is keyboard accessible.
+  - Elements in the HTML and in the layout follow a logical order.
+  - Elements with focus are clearly visible.
 
-- **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, `<div>` and `<span>` are non-semantic elements because they don't describe their contents. Examples of semantic elements include `<form>` and `<table>`, 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.
+### 4. Test without styles
 
-- **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.
+Because screen readers cannot access style information, you should disable styles for your product and ensure that your information architecture is effective and that there are adequate text labels.
 
-- **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 `<button>`, and it doesn't have a label, the screen reader can only tell that it’s a button—it can't determine what the button does. Add a few more non-labeled buttons, and now all the screen reader sees are vague buttons with no understanding of what they do. For more information, see the labeling section.
+ The [WAVE browser extension from WebAIM](//wave.webaim.org/extension/) provides this feature if it isn't available in the browser you are using.
 
-- **Links**: Similar to buttons, links should always have a label for clarity. Without the label, users have no idea where the links point to. If you have the same label for multiple links, each link must point to the same URL. Links, buttons, and form controls should make sense out of context. If a user wants to look at all of the links available, they should be able to differentiate the available links. You shouldn’t have multiple “Click here” links.
+### 5. Test with a screen reader 
 
-- **Landmarks**: Landmarks help communicate the structure of a page by identifying regions. There are many types of landmarks, such as banners, navigation, main, and form. When there are more than one of the same role (for example, two navigation regions on the same page), these regions should be differentiated by an `aria-label`.
+You can use any screen reader that is available in your operating system. To test PatternFly, we target the following screen readers:
+  - 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))
 
-- **Dynamic content**: One of the biggest accessibility concerns with dynamic content is the need to notify users that the content has changed. Sighted users benefit from highlighting or drawing visual attention to the changes. Non-sighted users need to be notified in another way, such as loading a new page, sending the focus to the new content, or using ARIA live announcements.
+### 6. Check color contrast
 
-- **Unrelated notifications**: Notifications from the operating system outside of the web app can interrupt a user while interacting with a page (for example, "You received a new chat message."). Consider this possibility when designing and developing for screen readers, and keep any notification messaging concise to limit the interruption.
+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))
 
+## Accessibility testing checklist
 
-<br />
+We recommend referencing the following checklist as you assess your product's accessibility.
 
-### Checklist for testing
-These are some of the main areas we check for on the PatternFly team. We recommend that you check for these same areas in your applications, too. 
+These are some of the main areas we check for on the PatternFly team to ensure that components meet consistent accessibility standards, but, to check your complete implementation, we recommend checking these same areas in your products. 
 
-**General questions**
+### General criteria
 
 <label><input type="checkbox" /> VO Rotor Navigation can discover all information. </label><br/>
 <label><input type="checkbox" /> VO Shortcut Navigation can discover all information. </label><br/>
-<label><input type="checkbox" /> VO Cursor Navigation can discover all information (dependent on component and use case- easy way to navigate to component). </label><br/>
+<label><input type="checkbox" /> VO Cursor Navigation can discover all information (dependent on component and use case — there should be an easy way to navigate to the component). </label><br/>
 <label><input type="checkbox" /> Tabbed Keyboard Navigation can discover all information. </label>
-- However, if content should be hidden from a screen reader, for instance, if it’s offscreen or just presentational, make sure that content is set to aria-hidden=”true”.  <br/>
+- Unless content should be hidden from a screen reader (such as offscreen or presentational information) make sure that content is set to aria-hidden=”true”.  <br/>
 
-<label><input type="checkbox" /> Is it understandable and usable? </label><br/>
-  - <label><input type="checkbox" /> When you navigate to an item by keyboard or by screen reader, you can easily understand and use the item. </label><br/>
+<label><input type="checkbox" /> Items are understandable and usable. </label><br/>
+  - <label><input type="checkbox" /> When you navigate to an item by keyboard or by screen reader, you should be able to easily understand and use the item. </label><br/>
   - <label><input type="checkbox" /> The flow of information makes sense when navigating. Screen readers navigate the page in DOM order. If you used CSS to visually reposition elements, they might be announced in a nonsensical sequence. Instead, if you need something to appear earlier in the page, try to physically move it earlier in the DOM.</label>
 
-**Accessibility points** <br />
+### Accessibility points
+
 <label><input type="checkbox" /> **Structure:** The visual information architecture should map to the various rotor menus that exist by default. </label><br />
 - <label><input type="checkbox" /> **Check rotor:** Are there good headings, landmarks, links, form controls, and other elements? Do they make sense, and are they descriptive without overloading information? </label><br />
   - <label><input type="checkbox" /> Headings: Check that heading levels convey structure/content and do not skip. 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. </label><br />
@@ -90,16 +86,15 @@ These are some of the main areas we check for on the PatternFly team. We recomme
 
 
 <label><input type="checkbox" /> **Labels:**</label>
-- <label><input type="checkbox" /> **Links:** Labels should be unique unless they have the same url. They should be descriptive/informative.</label>
+- <label><input type="checkbox" /> **Links:** Labels should be unique unless they have the same URL. They should be descriptive and informative.</label>
 - <label><input type="checkbox" /> **Buttons and form controls:**</label>
-  - Go through form controls and check if they all have labels. (Remember that there is a difference between being accessible and having a good, accessible experience. Clear, descriptive labels help create a better experience.)
-  - **Expandable buttons:** There should be some indication that it has the expandable control.
-- <label><input type="checkbox" /> **Form inputs:** These inputs should have some label even if it's not visible.</label>
-- <label><input type="checkbox" /> **Icons**: Where you don’t visibly see text there should still be some kind of text for screen reader.</label>
-- <label><input type="checkbox" /> **Images**: Check all images for proper alt text. 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, e.g., `alt=””`.</label>
-- <label><input type="checkbox" /> **Landmarks:** Landmark regions should have labels when there is more than one type of landmark and they are not the same (navigation, main, form, etc.).
+  - Confirm that all form controls have effective labels. (Remember that there is a difference between being accessible and having a *good*, accessible experience. Clear, descriptive labels help create a better experience.)
+  - **Expandable buttons:** There should be some indication that a button has the expandable control.
+- <label><input type="checkbox" /> **Form inputs:** These inputs should have a label — even if it's not visible.</label>
+- <label><input type="checkbox" /> **Icons**: Even if you don’t visibly see text, there should still be some kind of text for screen readers.</label>
+- <label><input type="checkbox" /> **Images**: Check all images for proper alt text. 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=””`.</label>
+- <label><input type="checkbox" /> **Landmarks:** Landmark regions should have labels when there is more than one type of landmark and they are not the same (such as navigation, main, form, etc.).
 Section element shouldn’t be used unless it has a label.</label>
-- <label><input type="checkbox" /> **Tables**: Can you tell what the table is and what’s in it? (https://webaim.org/techniques/tables/)</label>
-- <label><input type="checkbox" /> **Aria**: If there is visible text then there doesn’t need to be an `aria-label`. (Aria aids in description to screen reader users. It doesn’t have to reiterate or override what might already be there so you should check that your aria is useful.)</label>
-  - It’s important to understand that ARIA can only affect the _semantics_ of an element; it has no effect on the _behavior_ of the element. 
-  - For example, while you can make an element hidden to screen readers with `aria-hidden=”true”`, that does not change the focus behavior for that element. 
+- <label><input type="checkbox" /> **Tables**: Can you tell what the table is and what’s in it? [WebAIM has additional guidance on this.](https://webaim.org/techniques/tables/)</label>
+- <label><input type="checkbox" /> **Aria**: If there is visible text then there doesn’t need to be an `aria-label`. Aria provides more descriptive details to screen reader users. It doesn’t have to reiterate or override what might already be there so you should check that your aria is useful.</label>
+  - It’s important to understand that ARIA can only affect the _semantics_ of an element; it has no effect on the _behavior_ of the element. For example, while you can hide an element from screen readers with `aria-hidden=”true”`, that does not change the focus behavior for that element.