From de754ec05b714c6b1b2556d3b0d0383a00b0a55f Mon Sep 17 00:00:00 2001 From: Eric Olkowski Date: Tue, 7 Nov 2023 14:46:16 -0500 Subject: [PATCH] chore(JumpLinks): updated a11y docs to match template --- .../accessibility/jump-links/jump-links.md | 94 ++++++++++++++----- 1 file changed, 72 insertions(+), 22 deletions(-) diff --git a/packages/documentation-site/patternfly-docs/content/accessibility/jump-links/jump-links.md b/packages/documentation-site/patternfly-docs/content/accessibility/jump-links/jump-links.md index cd8a09577a..31a0581ac0 100644 --- a/packages/documentation-site/patternfly-docs/content/accessibility/jump-links/jump-links.md +++ b/packages/documentation-site/patternfly-docs/content/accessibility/jump-links/jump-links.md @@ -3,32 +3,82 @@ id: Jump links section: components --- -**Jump links** provide a way to navigate through section headings on a page without scrolling. +import { Checkbox, List, ListItem } from '@patternfly/react-core'; -For **Keyboard users** there are a number of considerations which must be made concerning tab order and focus management. -- Keyboard users should be able to navigate to and through the jump links using **Tab** and **Shift + Tab**. -- Keyboard users should also be able to select a jump link using **Enter**. -- The jump links should be before the associated sections in the DOM order so that the user can use the jump links to jump to the desired section. -- When a user selects a jump link, the browser focus should move into the associated section so that the navigable elements in that associated section -can be navigated to next without having to move focus through all the rest of the jump links and page. +## Accessibility -Additionally, it should be noted that jump links are often used on pages with so much content that the page scrolls. It should be true that -**Up** and **Down** arrow keys should be able to scroll the content. +To implement accessible PatternFly **jump links**: -**Screen reader users** should be made aware that the jump links are interactable when focused, and which jump link is currently active using -`aria-current="location"` on the active jump link. +- Provide a unique and descriptive `aria-label` to the jump links component. +- Ensure a jump link item has the `aria-current="location"` attribute when it is selected. +- Ensure that the jump links toggle has an `aria-expanded` attribute that matches its expanded state. For example, a collapsed jump links toggle should have `aria-expanded="false"`. +- Provide a unique and descriptive `aria-label` to the jump links toggle if the jump links component is expandable. +- Ensure each jump link item has descriptive text content that conveys what the user will be jumping to upon selecting it, such as a section heading. -The following props/attributes have been added for you or are customizable in PatternFly: +## Testing -| React component | React prop | Which HTML element it appears on in markup | Explanation | -|-----------------|-----------------|----------------------------------------------|---------------------------------------------------------------| -| JumpLinks | aria-label | nav.pf-v5-c-jump-links aria-label | Labels the nav to reflect the current nav description. | -| JumpLinks | toggleAriaLabel | .pf-v5-c-jump-links__toggle > button aria-label | Accessible label for the expandable jump links toggle button. | +At a minimum, jump links should meet the following criteria: -**Note:** Whenever multiple navigation elements are present on a page, an aria-label is highly recommended. Screen reader users -navigating a page via an elements list or rotor menu will be unable to distinguish between the various navigation elements. Using an aria-label -in these cases allows the user to differentiate between the navigation elements without navigating to and interacting with each one individually -to determine its contents. The following image demonstrates the lack of information when aria-labels are not present: + + + The jump links component has a unique and descriptive aria-label.} description="This helps users differentiate the jump links from other navigation elements on the page." /> + + + Once a jump link item has been selected, it has the aria-current="location" attribute.} description="This will announce to users navigating via assistive technologies such as a screen reader that a jump link item has already been jumped to when navigating through the list of jump link items." /> + + + If the jump links component is expandable, the jump links toggle can be collapsed or expanded via keyboard by pressing Space or Enter.} /> + + + If the jump links component is expandable, it has an aria-expanded attribute that matches its current expanded state.} /> + + + If the jump links component is expandable, the jump links toggle has a unique and descriptive aria-label.} /> + + + + + + Tab navigates to the next jump link item or focusable element, and Shift + Tab navigates to the previous jump link item or focusable element.} /> + + + Only Enter should select a jump link item since it is an anchor element.} /> + + -An example of a rotor menu interface which demonstrates that each navigation element is -indistinguishable from the others without aria-labels. \ No newline at end of file +## React customization + +The following React props have been provided for more fine-tuned control over accessibility. + +| Prop | Applied to | Reason | +|---|---|---| +| `aria-label="[text that labels the jump links navigation]"` | `JumpLinks` | Adds an accessible name to the jump links' `nav` element for assistive technologies. This should generally be descriptive and unique, especially if there are multiple `nav` elements on the page. | +| `isExpanded` | `JumpLinks` | Sets the default `aria-expanded` attribute. **Required** if the jump links component should be expanded by default. | +| `toggleAriaLabel="[text that labels the expandable toggle]"` | `JumpLinks` | Adds an accessible name to the expandable toggle for assistive technologies. **Required** when the jump links component is expandable. | +| `children` | `JumpLinksItem` | The content of the jump links item. This content should be descriptive in order to convey what a user will be jumping to upon selecting it. | +| `isActive` | `JumpLinksItem` | Sets the `aria-current="location"` attribute on the jump links item. **Required** when the jump links item has been selected. | + +## HTML/CSS customization + +The following HTML attributes and PatternFly classes can be used for more fine-tuned control over accessibility. + +| Attribute or class | Applied to | Reason | +|---|---|---| +| `aria-label="[text that labels the jump links navigation]"` | `.pf-v5-c-jump-links` | Adds an accessible name to the jump links' `nav` element for assistive technologies. This should generally be descriptive and unique, especially if there are multiple `nav` elements on the page. | +| `aria-expanded="[true or false]"` | `.pf-v5-c-jump-links__toggle > button` | Indicates whether the jump links toggle is expanded (true) or collapsed (false) to assistive technologies. **Required** when the jump links component is expandable. | +| `aria-label="[text that labels the expandable toggle]"` | `.pf-v5-c-jump-links__toggle > button` | Adds an accessible name to the expandable toggle for assistive technologies. **Required** when the jump links component is expandable. | +| `aria-hidden="true"` | `.pf-v5-c-jump-links__toggle-icon > i` | Removes the expandable toggle icon from the accessibility tree, preventing assistive technologies from potentially announcing duplicate or unnecessary information without visually hiding it. **Required**. | +| `role="list"` | `.pf-v5-c-jump-links__list` | Indicates that the jump links list is a list element. **Required**.

This role is redundant since `.pf-v5-c-jump-links__list` is a `