Skip to content

Commit f343c7c

Browse files
thatblindgeyethatblindgeye
authored
chore(JumpLinks): updated a11y docs to match template (#3808)
1 parent b89e3eb commit f343c7c

File tree

1 file changed

+72
-22
lines changed

1 file changed

+72
-22
lines changed

‎packages/documentation-site/patternfly-docs/content/accessibility/jump-links/jump-links.md‎

Lines changed: 72 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -3,32 +3,82 @@ id: Jump links
33
section: components
44
---
55

6-
**Jump links** provide a way to navigate through section headings on a page without scrolling.
6+
import { Checkbox, List, ListItem } from '@patternfly/react-core';
77

8-
For **Keyboard users** there are a number of considerations which must be made concerning tab order and focus management.
9-
- Keyboard users should be able to navigate to and through the jump links using **Tab** and **Shift + Tab**.
10-
- Keyboard users should also be able to select a jump link using **Enter**.
11-
- 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.
12-
- 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
13-
can be navigated to next without having to move focus through all the rest of the jump links and page.
8+
## Accessibility
149

15-
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
16-
**Up** and **Down** arrow keys should be able to scroll the content.
10+
To implement accessible PatternFly **jump links**:
1711

18-
**Screen reader users** should be made aware that the jump links are interactable when focused, and which jump link is currently active using
19-
`aria-current="location"` on the active jump link.
12+
- Provide a unique and descriptive `aria-label` to the jump links component.
13+
- Ensure a jump link item has the `aria-current="location"` attribute when it is selected.
14+
- 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"`.
15+
- Provide a unique and descriptive `aria-label` to the jump links toggle if the jump links component is expandable.
16+
- 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.
2017

21-
The following props/attributes have been added for you or are customizable in PatternFly:
18+
## Testing
2219

23-
| React component | React prop | Which HTML element it appears on in markup | Explanation |
24-
|-----------------|-----------------|----------------------------------------------|---------------------------------------------------------------|
25-
| JumpLinks | aria-label | nav.pf-v5-c-jump-links aria-label | Labels the nav to reflect the current nav description. |
26-
| JumpLinks | toggleAriaLabel | .pf-v5-c-jump-links__toggle > button aria-label | Accessible label for the expandable jump links toggle button. |
20+
At a minimum, jump links should meet the following criteria:
2721

28-
**Note:** Whenever multiple navigation elements are present on a page, an aria-label is highly recommended. Screen reader users
29-
navigating a page via an elements list or rotor menu will be unable to distinguish between the various navigation elements. Using an aria-label
30-
in these cases allows the user to differentiate between the navigation elements without navigating to and interacting with each one individually
31-
to determine its contents. The following image demonstrates the lack of information when aria-labels are not present:
22+
<List isPlain>
23+
<ListItem>
24+
<Checkbox id="jumpLinks-a11y-checkbox-1" label={<span>The jump links component has a unique and descriptive <code className="ws-code">aria-label</code>.</span>} description="This helps users differentiate the jump links from other navigation elements on the page." />
25+
</ListItem>
26+
<ListItem>
27+
<Checkbox id="jumpLinks-a11y-checkbox-2" label={<span>Once a jump link item has been selected, it has the <code className="ws-code">aria-current="location"</code> attribute.</span>} 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." />
28+
</ListItem>
29+
<ListItem>
30+
<Checkbox id="jumpLinks-a11y-checkbox-3" label={<span>If the jump links component is expandable, the jump links toggle can be collapsed or expanded via keyboard by pressing <kbd>Space</kbd> or <kbd>Enter</kbd>.</span>} />
31+
</ListItem>
32+
<ListItem>
33+
<Checkbox id="jumpLinks-a11y-checkbox-4" label={<span>If the jump links component is expandable, it has an <code className="ws-code">aria-expanded</code> attribute that matches its current expanded state.</span>} />
34+
</ListItem>
35+
<ListItem>
36+
<Checkbox id="jumpLinks-a11y-checkbox-5" label={<span>If the jump links component is expandable, the jump links toggle has a unique and descriptive <code className="ws-code">aria-label</code>.</span>} />
37+
</ListItem>
38+
<ListItem>
39+
<Checkbox id="jumpLinks-a11y-checkbox-6" label="Each jump link item has descriptive text content that conveys where a user will be jumping to upon selecting it." description={`This will typically be the same text as a section header, but in general avoid vague text such as "this section".`} />
40+
</ListItem>
41+
<ListItem>
42+
<Checkbox id="jumpLinks-a11y-checkbox-7" label="Standard keyboard navigation can be used to navigate between jump link items or other focusable elements." description={<span><kbd>Tab</kbd> navigates to the next jump link item or focusable element, and <kbd>Shift</kbd> + <kbd>Tab</kbd> navigates to the previous jump link item or focusable element.</span>} />
43+
</ListItem>
44+
<ListItem>
45+
<Checkbox id="jumpLinks-a11y-checkbox-8" label="Standard keyboard interaction can be used to select a jump link item." description={<span>Only <kbd>Enter</kbd> should select a jump link item since it is an anchor element.</span>} />
46+
</ListItem>
47+
</List>
3248

33-
<img src="./rotor-menu.png" alt="An example of a rotor menu interface which demonstrates that each navigation element is
34-
indistinguishable from the others without aria-labels." />
49+
## React customization
50+
51+
The following React props have been provided for more fine-tuned control over accessibility.
52+
53+
| Prop | Applied to | Reason |
54+
|---|---|---|
55+
| `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. |
56+
| `isExpanded` | `JumpLinks` | Sets the default `aria-expanded` attribute. **Required** if the jump links component should be expanded by default. |
57+
| `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. |
58+
| `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. |
59+
| `isActive` | `JumpLinksItem` | Sets the `aria-current="location"` attribute on the jump links item. **Required** when the jump links item has been selected. |
60+
61+
## HTML/CSS customization
62+
63+
The following HTML attributes and PatternFly classes can be used for more fine-tuned control over accessibility.
64+
65+
| Attribute or class | Applied to | Reason |
66+
|---|---|---|
67+
| `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. |
68+
| `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. |
69+
| `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. |
70+
| `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**. |
71+
| `role="list"` | `.pf-v5-c-jump-links__list` | Indicates that the jump links list is a list element. **Required**.<br/><br/>This role is redundant since `.pf-v5-c-jump-links__list` is a `<ul>` element, but it is required for assistive technologies to announce the list properly. |
72+
| `aria-current="location"` | `.pf-v5-c-jump-links__item.pf-m-current` | Announces to users navigating via assistive technologies such as a screen reader that a jump link is selected. **Required** after a jump link item has been selected. |
73+
74+
## Additional considerations
75+
76+
Consumers must ensure they take any additional considerations when customizing jump links, using it in a way not described or recommended by PatternFly, or in various other specific use-cases not outlined elsewhere on this page.
77+
78+
### Unique nav labeling
79+
80+
Whenever multiple navigation elements are present on a page, an `aria-label` is highly recommended. Users navigating via assistive technologies such as a screen reader may be using an elements list or rotor menu to navigate the page, and will be unable to distinguish between the various navigation elements without a unique accessible name.
81+
82+
The following image demonstrates the lack of information presented in VoiceOver's rotor menu when an `aria-label` is not present nor unique:
83+
84+
<img src="./rotor-menu.png" alt="An example of VoiceOver's rotor menu interface which demonstrates that each navigation element is indistinguishable from the others without aria-labels." />

0 commit comments

Comments
 (0)