dwmkerr / dwmkerr/effective-shell
[A11Y] [Low] AsciinemaPlayer component accessibility improvements
- Dominant language
- JavaScript
- Stars
- 780
- Forks
- 93
- Avg merge
- 1d 7h
- Merged PRs (30d)
- 3
Description
## Accessibility Issue: AsciinemaPlayer component accessibility improvements
**WCAG Level:** A
**Severity:** Low
**Category:** Media Accessibility / Dynamic Content
### Issue Description
The AsciinemaPlayer component embeds terminal recordings but may lack proper accessibility features for screen reader users and keyboard navigation. The component creates a div that holds the player but doesn't provide:
1. An accessible label for the player container
2. Fallback content for users who cannot view the recording
3. Keyboard instructions for controlling playback
### User Impact
- **Affected Users:** Screen reader users, keyboard-only users, users who cannot view animations
- **Severity:** Users may not understand the content of terminal recordings
### Violations Found
#### File: `src/components/AsciinemaPlayer/AsciinemaPlayer.tsx`
**Lines:** 38-44
```tsx
return (
{
() => {
// ...
return
}
}
)
```
**Issue:**
1. The player container div has no accessible label
2. No fallback content when player is unavailable
3. No description of what the recording demonstrates
---
### Recommended Fix
```tsx
type AsciinemaPlayerProps = {
src: string;
style: React.CSSProperties;
title?: string; // Add accessible title
description?: string; // Add accessible description
// ... other props
};
const AsciinemaPlayer: React.FC = ({
src,
style,
title,
description,
...asciinemaOptions
}) => {
return (
{description || "Terminal recording - content available in browser"}
}
>
{
() => {
if (!ExecutionEnvironment.canUseDOM) {
return (
ASCII Cinema Player Unavailable
);
}
const AsciinemaPlayerLibrary = require('asciinema-player');
const ref = useRef(null);
useEffect(() => {
const currentRef = ref.current;
AsciinemaPlayerLibrary.create(src, currentRef, asciinemaOptions);
}, [src]);
return (
{description && (
{description}
)}
);
}
}
)
};
```
**Changes Made:**
1. Added `title` and `description` props for accessibility
2. Added `role="img"` and `aria-label` to the container
3. Improved fallback content for SSR/no-JS scenarios
4. Added `aria-describedby` for longer descriptions
### Usage Example
```tsx
```
### Testing Instructions
1. Enable a screen reader
2. Navigate to a page with an AsciinemaPlayer component
3. Verify the screen reader announces the title/purpose of the recording
4. Test keyboard navigation within the player
5. Disable JavaScript and verify fallback content appears
### Resources
- [WCAG 1.1.1 Non-text Content](https://www.w3.org/WAI/WCAG21/Understanding/non-text-content.html)
- [MDN: aria-label](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label)
- [Asciinema accessibility](https://github.com/asciinema/asciinema-player/issues)
### Acceptance Criteria
- [ ] AsciinemaPlayer has accessible title prop
- [ ] Fallback content provided for non-JS environments
- [ ] Screen reader announces recording purpose
- [ ] Keyboard controls documented or accessible
- [ ] Manual testing with screen reader completed
---
Contributor guide
Assessment
This issue has not been assessed yet.