screen-reader-testing
Tools and workflow for testing web accessibility across multiple screen readers.
Install
mkdir -p .claude/skills/screen-reader-testing && curl -L -o skill.zip "https://agentskills.codes/api/skills/download/5195" && unzip -o skill.zip -d .claude/skills/screen-reader-testing && rm skill.zipInstalls to .claude/skills/screen-reader-testing
Activation
This is the description your AI agent reads to decide when to run this skill — the better it matches your request, the more reliably it fires.
Test web applications with screen readers including VoiceOver, NVDA, and JAWS. Use when validating screen reader compatibility, debugging accessibility issues, or ensuring assistive technology support.Key capabilities
- →Validate screen reader compatibility
- →Debug ARIA implementations
- →Test form accessibility
- →Verify keyboard navigation
How it works
It provides a structured testing guide for using major screen readers like VoiceOver, NVDA, and JAWS to verify web accessibility.
Inputs & outputs
When to use screen-reader-testing
- →Verifying screen reader compatibility
- →Debugging ARIA accessibility issues
- →Testing dynamic content announcements
- →Ensuring keyboard navigation accessibility
About this skill
Screen Reader Testing
Practical guide to testing web applications with screen readers for comprehensive accessibility validation.
When to Use This Skill
- Validating screen reader compatibility
- Testing ARIA implementations
- Debugging assistive technology issues
- Verifying form accessibility
- Testing dynamic content announcements
- Ensuring navigation accessibility
Core Concepts
1. Major Screen Readers
| Screen Reader | Platform | Browser | Usage |
|---|---|---|---|
| VoiceOver | macOS/iOS | Safari | ~15% |
| NVDA | Windows | Firefox/Chrome | ~31% |
| JAWS | Windows | Chrome/IE | ~40% |
| TalkBack | Android | Chrome | ~10% |
| Narrator | Windows | Edge | ~4% |
2. Testing Priority
Minimum Coverage:
1. NVDA + Firefox (Windows)
2. VoiceOver + Safari (macOS)
3. VoiceOver + Safari (iOS)
Comprehensive Coverage:
+ JAWS + Chrome (Windows)
+ TalkBack + Chrome (Android)
+ Narrator + Edge (Windows)
3. Screen Reader Modes
| Mode | Purpose | When Used |
|---|---|---|
| Browse/Virtual | Read content | Default reading |
| Focus/Forms | Interact with controls | Filling forms |
| Application | Custom widgets | ARIA applications |
Before testing on macOS, read VoiceOver setup, commands, and checklists.
For the required iOS Safari coverage, read VoiceOver touch setup and gestures.
Before testing with NVDA, read NVDA setup, modes, commands, and test scripts.
Before testing with JAWS or TalkBack, read platform setup and commands.
Common Test Scenarios
1. Modal Dialog
<!-- Accessible modal structure -->
<div
role="dialog"
aria-modal="true"
aria-labelledby="dialog-title"
aria-describedby="dialog-desc"
>
<h2 id="dialog-title">Confirm Delete</h2>
<p id="dialog-desc">This action cannot be undone.</p>
<button>Cancel</button>
<button>Delete</button>
</div>
// Focus management
function openModal(modal) {
// Store last focused element
lastFocus = document.activeElement;
// Move focus to modal
modal.querySelector("h2").focus();
// Trap focus
modal.addEventListener("keydown", trapFocus);
}
function closeModal(modal) {
// Return focus
lastFocus.focus();
}
function trapFocus(e) {
if (e.key === "Tab") {
const focusable = modal.querySelectorAll(
'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])',
);
const first = focusable[0];
const last = focusable[focusable.length - 1];
if (e.shiftKey && document.activeElement === first) {
last.focus();
e.preventDefault();
} else if (!e.shiftKey && document.activeElement === last) {
first.focus();
e.preventDefault();
}
}
if (e.key === "Escape") {
closeModal(modal);
}
}
2. Live Regions
<!-- Status messages (polite) -->
<div role="status" aria-live="polite" aria-atomic="true">
<!-- Content updates will be announced after current speech -->
</div>
<!-- Alerts (assertive) -->
<div role="alert" aria-live="assertive">
<!-- Content updates interrupt current speech -->
</div>
<!-- Progress updates -->
<div
role="progressbar"
aria-valuenow="75"
aria-valuemin="0"
aria-valuemax="100"
aria-label="Upload progress"
></div>
<!-- Log (additions only) -->
<div role="log" aria-live="polite" aria-relevant="additions">
<!-- New messages announced, removals not -->
</div>
3. Tab Interface
<div role="tablist" aria-label="Product information">
<button role="tab" id="tab-1" aria-selected="true" aria-controls="panel-1">
Description
</button>
<button
role="tab"
id="tab-2"
aria-selected="false"
aria-controls="panel-2"
tabindex="-1"
>
Reviews
</button>
</div>
<div role="tabpanel" id="panel-1" aria-labelledby="tab-1">
Product description content...
</div>
<div role="tabpanel" id="panel-2" aria-labelledby="tab-2" hidden>
Reviews content...
</div>
// Tab keyboard navigation
tablist.addEventListener("keydown", (e) => {
const tabs = [...tablist.querySelectorAll('[role="tab"]')];
const index = tabs.indexOf(document.activeElement);
let newIndex;
switch (e.key) {
case "ArrowRight":
newIndex = (index + 1) % tabs.length;
break;
case "ArrowLeft":
newIndex = (index - 1 + tabs.length) % tabs.length;
break;
case "Home":
newIndex = 0;
break;
case "End":
newIndex = tabs.length - 1;
break;
default:
return;
}
tabs[newIndex].focus();
activateTab(tabs[newIndex]);
e.preventDefault();
});
Debugging Tips
// Log what screen reader sees
function logAccessibleName(element) {
const computed = window.getComputedStyle(element);
console.log({
role: element.getAttribute("role") || element.tagName,
name:
element.getAttribute("aria-label") ||
element.getAttribute("aria-labelledby") ||
element.textContent,
state: {
expanded: element.getAttribute("aria-expanded"),
selected: element.getAttribute("aria-selected"),
checked: element.getAttribute("aria-checked"),
disabled: element.disabled,
},
visible: computed.display !== "none" && computed.visibility !== "hidden",
});
}
Best Practices
Do's
- Test with actual screen readers - Not just simulators
- Use semantic HTML first - ARIA is supplemental
- Test in browse and focus modes - Different experiences
- Verify focus management - Especially for SPAs
- Test keyboard only first - Foundation for SR testing
Don'ts
- Don't assume one SR is enough - Test multiple
- Don't ignore mobile - Growing user base
- Don't test only happy path - Test error states
- Don't skip dynamic content - Most common issues
- Don't rely on visual testing - Different experience
When not to use it
- →Automated-only accessibility testing
- →Non-web applications
Limitations
- →Requires manual interaction with screen readers
How it compares
It emphasizes manual testing with actual assistive technology rather than relying solely on automated checkers.
Compared to similar skills
screen-reader-testing side by side with the closest alternatives in the catalog.
| Skill | Installs | Updated | Safety | Difficulty |
|---|---|---|---|---|
| screen-reader-testing (this skill) | 1 | 8mo | No flags | Intermediate |
| ui-ux-expert-skill | 91 | 1y | Review | Advanced |
| playwright-mcp | 33 | 10mo | No flags | Intermediate |
| accessibility | 42 | 8mo | Review | Intermediate |
Try saying
Example prompts that trigger this skill in your AI assistant.
More by wshobson
View all by wshobson →You might also like
ui-ux-expert-skill
fercracix33
Technical workflow for implementing accessible React user interfaces with shadcn/ui, Tailwind CSS, and TanStack Query. Includes 6-phase process with mandatory Style Guide compliance, Context7 best practices consultation, Chrome DevTools validation, and WCAG 2.1 AA accessibility standards. Use after Test Agent, Implementer, and Supabase agents complete their work.
playwright-mcp
sfc-gh-dflippo
Browser testing, web scraping, and UI validation using Playwright MCP. Use this skill when you need to test Streamlit apps, validate web interfaces, test responsive design, check accessibility, or automate browser interactions through MCP tools.
accessibility
tech-leads-club
Audit and improve web accessibility following WCAG 2.1 guidelines. Use when asked to "improve accessibility", "a11y audit", "WCAG compliance", "screen reader support", "keyboard navigation", or "make accessible".
ios-simulator-skill
conorluddy
21 production-ready scripts for iOS app testing, building, and automation. Provides semantic UI navigation, build automation, accessibility testing, and simulator lifecycle management. Optimized for AI agents with minimal token output.
wcag-audit-patterns
wshobson
Conduct WCAG 2.2 accessibility audits with automated testing, manual verification, and remediation guidance. Use when auditing websites for accessibility, fixing WCAG violations, or implementing accessible design patterns.
web-quality-audit
davila7
Comprehensive web quality audit covering performance, accessibility, SEO, and best practices. Use when asked to "audit my site", "review web quality", "run lighthouse audit", "check page quality", or "optimize my website".