Skip to content

Commit d278fc1

Browse files
cdransfcdransf
authored
feat(screen-reader-testing-docs): adds documentation on screen reader testing (#5979)
* feat(screen-reader-testing-docs): adds documentation on screen reader testing * fix(screen-reader-testing-docs): update EAA and AODA links * fix(screen-reader-testing-docs): add note about VoiceOver browse/focus contrast
1 parent 2cf0796 commit d278fc1

File tree

4 files changed

+288
-17
lines changed

4 files changed

+288
-17
lines changed

‎CONTRIBUTOR-DOCS/02_style-guide/01_css/05_anti-patterns.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@
2121
- [Why This Happens](#why-this-happens)
2222
- [Why This Is a Problem](#why-this-is-a-problem)
2323
- [✅ Correct Approach](#-correct-approach)
24-
- [3. Re-implementing Variants with Extra Classes in `render()`](#3-re-implementing-variants-with-extra-classes-in-render)
24+
- [3. Excess Variant Classes in `render()`](#3-excess-variant-classes-in-render)
2525
- [❌ Anti-Pattern](#-anti-pattern)
2626
- [Why This Happens](#why-this-happens)
2727
- [Why This Is a Problem](#why-this-is-a-problem)

‎CONTRIBUTOR-DOCS/04_accessibility_guides/04_screen_reader_testing.md‎

Lines changed: 252 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,4 +6,256 @@
66

77
# Screen reader testing
88

9+
<!-- Generated TOC - DO NOT EDIT -->
10+
11+
<details open>
12+
<summary><strong>In this doc</strong></summary>
13+
14+
- [Screen reader testing](#screen-reader-testing)
15+
- [Overview](#overview)
16+
- [Why test with screen readers](#why-test-with-screen-readers)
17+
- [Goals of screen reader testing](#goals-of-screen-reader-testing)
18+
- [Relationship to keyboard accessibility](#relationship-to-keyboard-accessibility)
19+
- [Common screen reader and browser pairings](#common-screen-reader-and-browser-pairings)
20+
- [Desktop pairings](#desktop-pairings)
21+
- [Mobile pairings](#mobile-pairings)
22+
- [Screen reader modes](#screen-reader-modes)
23+
- [Browse mode (document/scan mode)](#browse-mode-documentscan-mode)
24+
- [Focus mode (forms/application/input mode)](#focus-mode-formsapplicationinput-mode)
25+
- [Table mode](#table-mode)
26+
- [Keyboard shortcuts](#keyboard-shortcuts)
27+
- [VoiceOver (macOS)](#voiceover-macos)
28+
- [NVDA (Windows)](#nvda-windows)
29+
- [JAWS (Windows)](#jaws-windows)
30+
- [Additional resources](#additional-resources)
31+
- [Testing workflow](#testing-workflow)
32+
33+
</details>
34+
935
<!-- Document content (editable) -->
36+
37+
## Overview
38+
39+
Screen reader testing is essential for verifying that Spectrum Web Components provide an equivalent experience for users who rely on assistive technology. This guide covers the fundamentals of screen reader testing, including browser pairings, interaction modes, and keyboard shortcuts.
40+
41+
## Why test with screen readers
42+
43+
Screen readers convert visual content into synthesized speech or braille output, enabling users who are blind or have low vision to navigate and interact with web content. Testing with screen readers helps ensure that:
44+
45+
- All content is perceivable through audio or braille
46+
- Interactive elements are operable with assistive technology
47+
- The purpose and state of components is communicated clearly
48+
- Users can complete tasks efficiently
49+
50+
### Goals of screen reader testing
51+
52+
When testing components with screen readers, focus on these key outcomes:
53+
54+
1. **Equivalent experience**: Users should be able to accomplish the same tasks as users who can see the screen, and sighted screen reader users should not have conflicting or confusing information from the visible content and the screen reader
55+
2. **Task completion**: All interactive workflows should be completable
56+
3. **Meaningful information**: Content should be announced in a logical order with appropriate context
57+
4. **Efficient navigation**: Users should be able to navigate quickly using headings, landmarks, and other semantic structures
58+
59+
### Relationship to keyboard accessibility
60+
61+
Screen reader testing builds on [keyboard testing](03_keyboard_testing.md). Before testing with a screen reader:
62+
63+
1. Verify all interactive elements are keyboard accessible
64+
2. Confirm focus order is logical
65+
3. Ensure focus indicators are visible
66+
67+
Screen readers add an additional layer of testing by verifying that keyboard interactions are properly announced and that non-interactive content is also accessible.
68+
69+
## Common screen reader and browser pairings
70+
71+
Screen readers work best with specific browsers. Use these recommended pairings for the most accurate testing results.
72+
73+
### Desktop pairings
74+
75+
| Platform | Screen reader | Browser | Notes |
76+
|----------|---------------|---------|---------------------------------------------------|
77+
| macOS | VoiceOver | Safari | Built-in; best compatibility with Safari |
78+
| Windows | NVDA | Firefox | Free and open-source; excellent standards support |
79+
| Windows | NVDA | Chrome | Good alternative pairing |
80+
| Windows | JAWS | Chrome | Commercial; widely used in enterprise |
81+
| Windows | JAWS | Edge | Good compatibility |
82+
| Windows | Narrator | Edge | Built-in; improving rapidly |
83+
| Linux | Orca | Firefox | Built-in to GNOME desktop |
84+
85+
### Mobile pairings
86+
87+
| Platform | Screen reader | Browser | Notes |
88+
|----------|---------------|---------|------------------------------------------------|
89+
| iOS | VoiceOver | Safari | Built-in; only supported browser engine on iOS |
90+
| Android | TalkBack | Chrome | Built-in; best compatibility with Chrome |
91+
92+
**Recommended minimum testing:** Test with at least VoiceOver/Safari (macOS) and NVDA/Firefox (Windows) to cover the most common usage patterns.
93+
94+
## Screen reader modes
95+
96+
Screen readers operate in different modes that affect how users interact with content. Understanding these modes is crucial for testing components correctly.
97+
98+
### Browse mode (document/scan mode)
99+
100+
Browse mode (called "Scan mode" in Narrator, "Document mode" in some screen readers) is for reading and navigating content.
101+
102+
**Characteristics:**
103+
104+
- Linear reading through page content using arrow keys
105+
- Quick navigation shortcuts (e.g., <kbd>H</kbd> for headings, <kbd>K</kbd> for links)
106+
- Can read non-focusable text content
107+
- Virtual cursor moves through the accessibility tree
108+
109+
**Common navigation shortcuts in browse mode:**
110+
111+
| Action | VoiceOver | NVDA | JAWS |
112+
|------------------|----------------------------------------------------------------------|---------------------------------|---------------------------------|
113+
| Next heading | <kbd>VO</kbd> + <kbd>Command</kbd> + <kbd>H</kbd> | <kbd>H</kbd> | <kbd>H</kbd> |
114+
| Previous heading | <kbd>VO</kbd> + <kbd>Command</kbd> + <kbd>Shift</kbd> + <kbd>H</kbd> | <kbd>Shift</kbd> + <kbd>H</kbd> | <kbd>Shift</kbd> + <kbd>H</kbd> |
115+
| Next link | <kbd>VO</kbd> + <kbd>Command</kbd> + <kbd>L</kbd> | <kbd>K</kbd> | <kbd>Tab</kbd> |
116+
| Next button | <kbd>VO</kbd> + <kbd>Command</kbd> + <kbd>J</kbd> | <kbd>B</kbd> | <kbd>B</kbd> |
117+
| Next form field | <kbd>VO</kbd> + <kbd>Command</kbd> + <kbd>J</kbd> | <kbd>F</kbd> | <kbd>F</kbd> |
118+
| Next landmark | <kbd>VO</kbd> + <kbd>Command</kbd> + <kbd>L</kbd> | <kbd>D</kbd> | <kbd>R</kbd> |
119+
120+
**Note:** <kbd>VO</kbd> refers to the VoiceOver modifier keys, typically <kbd>Control</kbd> + <kbd>Option</kbd>.
121+
122+
### Focus mode (forms/application/input mode)
123+
124+
Focus mode is for interacting with form controls and custom widgets. In this mode, keystrokes are passed directly to the focused element rather than being interpreted as navigation commands.
125+
126+
**Characteristics:**
127+
128+
- Direct keyboard input to interactive elements
129+
- Arrow keys control the element, not the virtual cursor
130+
- Automatically entered when focusing certain controls (auto forms mode)
131+
- Required for interacting with custom widgets using `role="application"` or `role="listbox"`
132+
133+
**Entering and exiting focus mode:**
134+
135+
| Action | NVDA | JAWS |
136+
|------------------|---------------------------------------------------------|-------------------------------------------|
137+
| Enter focus mode | <kbd>NVDA</kbd> + <kbd>Space</kbd> or automatic | <kbd>Enter</kbd> on control or automatic |
138+
| Exit focus mode | <kbd>Escape</kbd> or <kbd>NVDA</kbd> + <kbd>Space</kbd> | <kbd>Numpad +</kbd> or <kbd>Escape</kbd> |
139+
140+
**Note:** VoiceOver does not use the browse/focus mode paradigm. Instead, it uses **Quick Nav** (toggled with <kbd>Left Arrow</kbd> + <kbd>Right Arrow</kbd> pressed simultaneously) to enable single-key navigation, and the **Interact model** (<kbd>VO</kbd> + <kbd>Shift</kbd> + <kbd>Down Arrow</kbd> to drill into elements, <kbd>VO</kbd> + <kbd>Shift</kbd> + <kbd>Up Arrow</kbd> to move back up). VoiceOver handles form controls more seamlessly without requiring an explicit mode switch.
141+
142+
**Auto forms mode:** JAWS and NVDA automatically switch to focus mode when landing on certain form controls. JAWS can be configured to use "Auto Forms Mode" which automatically switches modes based on the focused element.
143+
144+
**Associated information:** In focus mode, screen readers announce associated information such as:
145+
146+
- Labels (from `<label>`, `aria-label`, or `aria-labelledby`)
147+
- Descriptions (from `aria-describedby`)
148+
- Required state (from `required` or `aria-required`)
149+
- Invalid state (from `aria-invalid`)
150+
151+
> **Important:** In focus mode, only interactive elements and their associated labels/descriptions are announced. If content is not a label or description for a focusable element, it will not be read. For non-interactive content, screen reader users must switch to Browse mode. This is expected behavior, not a bug — ensure you test both modes when evaluating component accessibility.
152+
153+
### Table mode
154+
155+
Table mode provides specialized navigation within data tables.
156+
157+
**Characteristics:**
158+
159+
- Cell-by-cell navigation using arrow keys
160+
- Automatic announcement of row and column headers
161+
- Context about position within the table
162+
163+
**Common table navigation shortcuts:**
164+
165+
| Action | VoiceOver | NVDA | JAWS |
166+
|--------------------|----------------------------------------|-----------------------------------------------------------|-----------------------------------------------------------|
167+
| Next cell right | <kbd>VO</kbd> + <kbd>Right Arrow</kbd> | <kbd>Ctrl</kbd> + <kbd>Alt</kbd> + <kbd>Right Arrow</kbd> | <kbd>Ctrl</kbd> + <kbd>Alt</kbd> + <kbd>Right Arrow</kbd> |
168+
| Next cell down | <kbd>VO</kbd> + <kbd>Down Arrow</kbd> | <kbd>Ctrl</kbd> + <kbd>Alt</kbd> + <kbd>Down Arrow</kbd> | <kbd>Ctrl</kbd> + <kbd>Alt</kbd> + <kbd>Down Arrow</kbd> |
169+
| Previous cell left | <kbd>VO</kbd> + <kbd>Left Arrow</kbd> | <kbd>Ctrl</kbd> + <kbd>Alt</kbd> + <kbd>Left Arrow</kbd> | <kbd>Ctrl</kbd> + <kbd>Alt</kbd> + <kbd>Left Arrow</kbd> |
170+
| Previous cell up | <kbd>VO</kbd> + <kbd>Up Arrow</kbd> | <kbd>Ctrl</kbd> + <kbd>Alt</kbd> + <kbd>Up Arrow</kbd> | <kbd>Ctrl</kbd> + <kbd>Alt</kbd> + <kbd>Up Arrow</kbd> |
171+
172+
## Keyboard shortcuts
173+
174+
Each screen reader has its own set of keyboard shortcuts. Below are essential shortcuts for testing.
175+
176+
### VoiceOver (macOS)
177+
178+
**Starting and stopping:**
179+
180+
| Action | Shortcut |
181+
|-------------------------|----------------------------------------|
182+
| Turn VoiceOver on/off | <kbd>Command</kbd> + <kbd>F5</kbd> |
183+
| VoiceOver modifier (VO) | <kbd>Control</kbd> + <kbd>Option</kbd> |
184+
185+
**Navigation:**
186+
187+
| Action | Shortcut |
188+
|-----------------------|------------------------------------------------------------|
189+
| Read next item | <kbd>VO</kbd> + <kbd>Right Arrow</kbd> |
190+
| Read previous item | <kbd>VO</kbd> + <kbd>Left Arrow</kbd> |
191+
| Interact with element | <kbd>VO</kbd> + <kbd>Shift</kbd> + <kbd>Down Arrow</kbd> |
192+
| Stop interacting | <kbd>VO</kbd> + <kbd>Shift</kbd> + <kbd>Up Arrow</kbd> |
193+
| Activate element | <kbd>VO</kbd> + <kbd>Space</kbd> |
194+
| Open rotor | <kbd>VO</kbd> + <kbd>U</kbd> |
195+
196+
### NVDA (Windows)
197+
198+
**Starting and stopping:**
199+
200+
| Action | Shortcut |
201+
|---------------|----------------------------------------------------------|
202+
| Start NVDA | <kbd>Ctrl</kbd> + <kbd>Alt</kbd> + <kbd>N</kbd> |
203+
| Stop NVDA | <kbd>NVDA</kbd> + <kbd>Q</kbd> |
204+
| NVDA modifier(Insert/CapsLock) | <kbd>Insert</kbd> or <kbd>Caps Lock</kbd> (configurable) |
205+
206+
**Navigation:**
207+
208+
| Action | Shortcut |
209+
|--------------------------|-----------------------------------------|
210+
| Read next item | <kbd>Down Arrow</kbd> (browse mode) |
211+
| Read previous item | <kbd>Up Arrow</kbd> (browse mode) |
212+
| Toggle browse/focus mode | <kbd>NVDA</kbd> + <kbd>Space</kbd> |
213+
| Read from cursor | <kbd>NVDA</kbd> + <kbd>Down Arrow</kbd> |
214+
| Stop reading | <kbd>Ctrl</kbd> |
215+
| Elements list | <kbd>NVDA</kbd> + <kbd>F7</kbd> |
216+
217+
### JAWS (Windows)
218+
219+
**Starting and stopping:**
220+
221+
| Action | Shortcut |
222+
|---------------|------------------------------------|
223+
| Start JAWS | Launch from Start menu |
224+
| Quit JAWS | <kbd>Insert</kbd> + <kbd>F4</kbd> |
225+
| JAWS modifier | <kbd>Insert</kbd> |
226+
227+
**Navigation:**
228+
229+
| Action | Shortcut |
230+
|-----------------------|-------------------------------------------|
231+
| Read next item | <kbd>Down Arrow</kbd> (browse mode) |
232+
| Read previous item | <kbd>Up Arrow</kbd> (browse mode) |
233+
| Toggle virtual cursor | <kbd>Insert</kbd> + <kbd>Z</kbd> |
234+
| Read from cursor | <kbd>Insert</kbd> + <kbd>Down Arrow</kbd> |
235+
| Stop reading | <kbd>Ctrl</kbd> |
236+
| Links list | <kbd>Insert</kbd> + <kbd>F7</kbd> |
237+
238+
### Additional resources
239+
240+
For comprehensive keyboard shortcut references, see:
241+
242+
- [Deque University Screen Reader Keyboard Shortcuts](https://dequeuniversity.com/screenreaders/) — printable cheatsheets for all major screen readers
243+
- [WebAIM Screen Reader User Survey](https://webaim.org/projects/screenreadersurvey/) — usage statistics and preferences
244+
- [VoiceOver User Guide (Apple)](https://support.apple.com/guide/voiceover/welcome/mac)
245+
- [NVDA User Guide](https://www.nvaccess.org/files/nvda/documentation/userGuide.html)
246+
- [JAWS Documentation (Freedom Scientific)](https://support.freedomscientific.com/Products/Blindness/JAWS)
247+
248+
## Testing workflow
249+
250+
Follow this workflow when testing components with screen readers:
251+
252+
1. **Start with keyboard testing**: Verify keyboard accessibility first
253+
2. **Enable the screen reader**: Use the recommended browser pairing
254+
3. **Navigate to the component**: Use heading or landmark navigation
255+
4. **Test in browse mode**: Verify content is announced correctly
256+
5. **Test in focus mode**: Interact with controls and verify announcements
257+
6. **Test state changes**: Verify dynamic updates are announced (e.g., expanded/collapsed, selected, error states)
258+
7. **Complete user tasks**: Verify entire workflows are achievable
259+
8. **Document issues**: Note any missing announcements, confusing order, or blocked interactions
260+
261+
For more testing resources and tools, see [Accessibility resources](06_accessibility_resources.md).

0 commit comments

Comments
 (0)