Claude Code Screen Reader Testing Workflow

Building accessible web applications requires more than just following WCAG guidelines. You need to verify that your content actually works with assistive technologies. Screen reader testing is a critical part of this process, and Claude Code can help streamline your workflow.

Why Screen Reader Testing Matters

Automated accessibility tools catch about 30-40% of accessibility issues. The remaining issues—like confusing heading structures, unclear link text, or missing form labels—require human testing with actual screen readers. Popular options include NVDA (Windows), VoiceOver (macOS), and JAWS (Windows).

Testing manually is time-consuming. Integrating screen reader testing into your regular development workflow helps catch issues early and reduces the effort required for remediation.

Setting Up Your Testing Environment

Before automating, establish a consistent testing environment. Here’s a practical setup for macOS developers:

# Enable VoiceOver from terminal
open -a VoiceOver

# Or use the keyboard shortcut: Cmd + F5

For cross-platform testing, consider using virtual machines with Windows and NVDA installed. Tools like VirtualBox or Parallels make this manageable.

Configuring NVDA for Consistent Results

When testing with NVDA on Windows, use these settings for repeatable test outcomes:

• Speech viewer: Enabled — displays announced text on-screen for verification
• Punctuation level: All — ensures complete announcements during testing
• Input composition: Disabled — produces more predictable behavior
• Table headers: Report all — verifies data table accessibility

Key NVDA navigation commands to document alongside your test cases: Tab/Shift+Tab for form fields, arrow keys for content, Enter to activate links and buttons, Escape to close dialogs.

Automating Screen Reader Checks with Claude

While you cannot fully automate screen reader testing (human judgment is still required), Claude Code can help in several ways:

1. Generate Testing Scripts

Use Claude to create manual testing scripts that document exactly what to check:

Create a VoiceOver testing checklist for a login form that includes:
- Form field labels
- Error message announcements
- Button focus order
- ARIA attributes

2. Analyze HTML for Accessibility Issues

Paste your component HTML and ask Claude to identify potential screen reader problems:

<!-- Ask Claude to review this markup -->
<div class="button" onclick="submitForm()">Submit</div>

Claude will flag issues like missing button semantics, lack of focus management, and missing accessible names.

3. Validate ARIA Implementation

The frontend-design skill includes accessibility patterns. When working on complex components, activate it:

/frontend-design

Then describe your component. The skill helps ensure proper ARIA roles, states, and properties are implemented correctly.

Practical Workflow Integration

Here’s how to integrate screen reader testing into your development process:

Step 1: Code Review Phase

When reviewing pull requests, use the tdd skill to ensure tests include accessibility cases:

/tdd

Then ask Claude to generate accessibility test cases alongside functional tests:

Generate test cases for this form component that include:
- Keyboard navigation
- Screen reader announcements
- Focus management

Step 2: Pre-Commit Validation

Add a simple pre-commit check using html-validate or axe-cli:

# Install axe-cli
npm install -g @axe-core/cli

# Run accessibility audit
axe http://localhost:3000 --timeout 10000

This catches low-hanging fruit before human testing.

For Windows-based CI environments running NVDA-compatible checks:

name: Accessibility Tests
on: [pull_request]
jobs:
  a11y-test:
    runs-on: windows-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run axe accessibility tests
        run: npx axe-cli http://localhost:3000
      - name: Validate HTML structure
        run: npm run test:a11y-html

Step 3: Document Findings

Use the supermemory skill to track accessibility issues across your project:

/supermemory

Then log screen reader findings with steps to reproduce:

Issue: VoiceOver doesn't announce error message
Component: LoginForm
Steps: Submit empty form
Expected: "Username is required" announced
Actual: Silence
Priority: High

Common Screen Reader Issues to Check

Focus on these high-impact areas during testing:

1. Images without alt text — Screen readers skip or read filename
2. Form fields without labels — Users cannot understand input purpose
3. Heading hierarchy — Skipping levels (h1 to h3) confuses navigation
4. Link text clarity — “Click here” or “Read more” lacks context
5. Dynamic content announcements — ARIA live regions missing for updates
6. Keyboard trap — Users cannot exit modal or dialog

When NVDA encounters a keyboard trap, users have no way to continue navigating. Implement focus trapping correctly in modals:

function trapFocus(element) {
  const focusableElements = element.querySelectorAll(
    'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
  );
  const firstElement = focusableElements[0];
  const lastElement = focusableElements[focusableElements.length - 1];

  element.addEventListener('keydown', (e) => {
    if (e.key === 'Tab') {
      if (e.shiftKey && document.activeElement === firstElement) {
        e.preventDefault();
        lastElement.focus();
      } else if (!e.shiftKey && document.activeElement === lastElement) {
        e.preventDefault();
        firstElement.focus();
      }
    }
  });
}

For NVDA-specific test scenarios, verify that announcements match expectations — for example, a login form should announce “Username, edit, required” when tabbing to the first field, “Password, password edit, required” for the password field, and “Sign in, button” for the submit button.

Testing Specific Components

Modal Dialogs

<!-- Test this pattern -->
<div role="dialog" aria-modal="true" aria-labelledby="modal-title">
  <h2 id="modal-title">Confirm Delete</h2>
  <p>Are you sure?</p>
  <button>Cancel</button>
  <button>Delete</button>
</div>

Check: Focus moves into modal on open, trapped within modal, returns to trigger on close.

Form Validation

<input 
  type="email" 
  id="email"
  aria-describedby="email-error"
  aria-invalid="true"
>
<span id="email-error" role="alert">Invalid email format</span>

Check: Error announced when field loses focus, error message read, input state communicated.

Dynamic Lists

<ul aria-live="polite" aria-atomic="false">
  <!-- List items added/removed dynamically -->
</ul>

Check: New items announced, count communicated, updates don’t interrupt unexpectedly.

Tools That Complement Manual Testing

Beyond direct screen reader testing, these tools support your workflow:

• axe DevTools — Browser extension for automated checks
• WAVE — Web accessibility evaluation tool
• Accessibility Insights — Microsoft’s testing platform
• Color Contrast Analyzers — Verify text visibility

The pdf skill can help if you’re documenting accessibility reports—generate properly formatted PDFs of your testing results.

Measuring Progress

Track accessibility improvements over time:

• Log issue count per component
• Record time required for remediation
• Note recurring patterns
• Measure keyboard-only navigation speed

This data helps justify accessibility investment to stakeholders and identifies training needs.

Conclusion

Screen reader testing requires human involvement, but Claude Code reduces friction throughout the process. Use it to generate testing scripts, analyze markup, validate ARIA patterns, and document findings. Combined with automated tools and a structured workflow, you can achieve robust accessibility without slowing development.

The key is consistency—test regularly, document findings, and iterate. Each cycle improves both your product and your team’s accessibility expertise.

Related Reading

• Claude Code WCAG Accessibility Audit Workflow
• Claude Code Axe Accessibility Testing Guide
• Claude Code Color Contrast Checking Workflow
• Claude Skills Guides Hub

Built by theluckystrike — More at zovo.one