Screenreader Support for Oceans Guide#411
Conversation
There was a problem hiding this comment.
Pull request overview
This PR implements initial screenreader compatibility for the Oceans Guide component by adding ARIA attributes, keyboard navigation support, and focus management to make the guide accessible to users with screenreaders like VoiceOver.
Changes:
- Added keyboard event handling to enable navigation with Space and Enter keys
- Implemented focus management that automatically focuses the guide dialog when it appears
- Added ARIA attributes (aria-label, aria-labelledby, aria-live, aria-hidden) to improve screenreader announcements
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| <div style={styles.guideTypingText}> | ||
|
|
||
| {/* Visually hidden aria-live region for screen readers */} | ||
| <div style={{position: 'absolute', left: '-9999px', width: '1px', height: '1px', overflow: 'hidden'}} aria-live="polite"> |
There was a problem hiding this comment.
The visually hidden div uses inline styles for screen reader-only content. While functional, this pattern is fragile and should be extracted to a reusable style constant or utility class to ensure consistency across the application and make it easier to maintain.
There was a problem hiding this comment.
Understood- this is in a small repo and if I reuse it within there I can refactor to a utility class
| > | ||
| <div | ||
| ref={this.guideDialogRef} | ||
| aria-labelledby="guide-heading" |
There was a problem hiding this comment.
The guide dialog uses aria-labelledby='guide-heading' but this element only exists when currentGuide.style === 'Info'. For other guide styles, the aria-labelledby will reference a non-existent element, which could confuse screenreaders. Consider using aria-label with appropriate text for non-Info guides, or conditionally setting aria-labelledby only when the heading exists.
| aria-labelledby="guide-heading" | |
| aria-labelledby={currentGuide.style === 'Info' ? 'guide-heading' : undefined} |
There was a problem hiding this comment.
If we don't have a guide providing info, we don't need a label here. Plus, I tried adding a conditional aria-label and it took over precedence
hannahbergam
changed the title
2 participants
This is a step toward screenreader compatibility for Oceans. While the buttons are not all intuitive yet (sometimes you have to keyboard nav backwards to get to continue), at least the guide is reading out loud when I have VoiceOver turned on.
I was able to download the repo instead of working in a github codespace and use a symlink to connect the two repositories. I had to mess with the package.json file to get the two compatible, but am not pushing those changes here.
The final commit makes the focus-visible outline match that of the buttons instead of using the web default blue and white.
Jira:
https://codedotorg.atlassian.net/browse/SL-1529
Future Updates:
Before, there was no voiceover action of the guide at all:
Screen.Recording.2026-01-27.at.2.08.22.PM.mov
After:
Screen.Recording.2026-01-27.at.1.53.03.PM.mov