98.8K+Download
Skip to the usage guide
screen-reader-testingby Seth Hobson

Screen Reader Testing Skill.

A Claude Code and Codex skill for design review: tests web apps with VoiceOver, NVDA, and JAWS screen readers.

  • Design Review & Accessibility
  • Review report
Download OpenDesignView usage guide
wshobson/agents · plugins/accessibility-compliance/skills/screen-reader-testing/SKILL.mdSKILL.md
--- name: screen-reader-testing description: 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. --- ## When to Use This Skill ## Core Concepts ## VoiceOver (macOS) ## VoiceOver Testing Checklist ## NVDA (Windows) ## NVDA Test Script
Front matter and section headings read from the upstream file on 2026-09-14 · 12,020 characters in full

01 What it does

What the screen-reader-testing Skill Does in Claude Code and Codex

Summary, workflow and outputs, all read from the skill's SKILL.md.

From the SKILL.mdRead 2026-09-14 · not a recorded run

In the Skill's Own Terms

Tests web applications with VoiceOver, NVDA, JAWS, TalkBack, and Narrator screen readers across macOS, Windows, iOS, and Android platforms. Validates screen reader compatibility, debugs assistive technology issues, and ensures proper ARIA implementations through hands-on testing with actual screen readers.

Covers navigation, forms, dynamic content announcements, focus management, and modal dialogs. Provides platform-specific commands, testing checklists, and code examples for common accessibility patterns. Emphasizes testing in different screen reader modes (browse, focus, application) and prioritizes semantic HTML with ARIA as supplemental enhancement.

What it produces

  • VoiceOver Testing Checklist covering page load, navigation, links, forms, dynamic content, and tables
  • NVDA Test Script with step-by-step instructions for initial load, landmarks, headings, forms, interactive elements, and dynamic content
  • HTML code examples showing accessible patterns and fixes for common issues like unlabeled buttons, unannounced dynamic content, and form errors
  • JavaScript code for focus management including modal dialogs, focus trapping, and tab interface keyboard navigation
See the example prompt ↗

How It Works

  1. 01
    Test with Major Screen Readers by Platform

    Use NVDA with Firefox on Windows (31% usage), VoiceOver with Safari on macOS and iOS (15% usage), JAWS with Chrome (40% usage), TalkBack on Android (10% usage), and Narrator with Edge (4% usage).

  2. 02
    Navigate Using Screen reader-specific Commands

    Execute commands like VO+Right Arrow for VoiceOver element navigation, H for NVDA heading jumps, Insert+F7 for JAWS link lists, and two-finger swipe for TalkBack scrolling.

  3. 03
    Test in Browse and Focus Modes

    Verify that screen readers switch correctly between browse mode for reading content and focus mode for interacting with form controls, watching for mode announcements.

  4. 04
    Validate Semantic Structure and ARIA

    Check that headings are discoverable via rotor or elements list, landmarks are properly labeled, live regions announce updates, and roles like dialog, tab, and progressbar are correctly implemented.

  5. 05
    Verify Focus Management and Keyboard Interaction

    Ensure focus moves to errors after form submission, modals trap focus correctly and return focus on close, and tab interfaces respond to arrow keys, Home, and End.

  6. 06
    Test Dynamic Content Announcements

    Trigger content updates and confirm that role="status" with aria-live="polite" announces changes after current speech, while role="alert" interrupts immediately.

02 Find your fit

When to Use the screen-reader-testing Skill

Use the screen-reader-testing skill in Claude Code or Codex when the job is design review of this kind. Fit and limits below are taken from the skill's own file.

Good Fit

  • Validating that a web application works correctly with screen reader software
  • Testing whether ARIA roles, states, and properties are implemented correctly
  • Debugging issues that affect users of assistive technologies
  • Ensuring form controls are accessible with proper labels and error announcements
  • Testing that dynamic content updates are announced to screen reader users

Know the Boundaries

  • Relying solely on visual inspection to validate accessibility
  • Testing only success paths without validating error states and edge cases
  • Skipping mobile screen reader testing on iOS and Android

03 Inside the skill

Rules the screen-reader-testing Skill Gives Claude Code and Codex

8 concrete instructions, defaults and limits the SKILL.md sets for the agent — the part of the file that changes the result.

  1. Test with Actual Screen Readers, Not Simulators

    Always test using real screen reader software (VoiceOver, NVDA, JAWS, TalkBack, Narrator) rather than simulation tools or emulators.

  2. Use Semantic HTML First, ARIA Is Supplemental

    Build interfaces with native HTML elements before adding ARIA attributes. ARIA enhances semantic HTML but does not replace it.

  3. Minimum Coverage: NVDA+Firefox, VoiceOver+Safari on macOS and iOS

    At minimum, test with NVDA paired with Firefox on Windows, VoiceOver with Safari on macOS, and VoiceOver with Safari on iOS before considering the application validated.

  4. Test in Both Browse and Focus Modes

    Verify the experience in browse mode (for reading content with arrow keys) and focus mode (for interacting with controls), as screen readers switch between them automatically or manually.

  5. Test keyboard-only Navigation Before Screen Reader Testing

    Complete keyboard-only testing first, as it forms the foundation for screen reader accessibility and catches interaction issues early.

  6. Verify Focus Management for single-page Applications

    Ensure focus is managed correctly when content changes dynamically, especially in SPAs where page transitions happen without full reloads.

  7. Never Test with Only One Screen Reader

    Testing with a single screen reader is insufficient. Different screen readers have different behaviors and usage patterns across platforms.

  8. Always Test Dynamic Content and Error States

    Do not skip testing content that updates dynamically or limit testing to the happy path. Dynamic content and error handling are the most common sources of accessibility issues.

04 Put it to work

Install screen-reader-testing in Claude Code or Codex

One npx skills add command, then a first task in your agent and a checklist for the result.

Add screen-reader-testing to Claude Code, Codex or Your Agent

Run in your project; the installer asks which agent to add it to.

Terminal
npx skills add https://github.com/wshobson/agents --skill screen-reader-testing

Generic skills CLI form for plugins/accessibility-compliance/skills/screen-reader-testing/SKILL.md; the repository may document its own path.

Give the Skill a First Design Review Task

Written in the skill's own terms; replace the bracketed parts with your material.

Starter prompt
Test the [checkout form] on [staging.example.com] with NVDA and VoiceOver to verify that all field labels are announced, required field indicators are read correctly, validation errors are communicated when the form is submitted with invalid data, and focus moves to the first error. Also confirm that the loading state during payment processing is announced and the success confirmation is read by the screen reader.

Source: written from the SKILL.md in the skill's own terms.

Check the First Result

What the SKILL.md itself says a correct result looks like:

  • Verify page title is announced when the page loads
  • Confirm all headings are discoverable using the rotor (VoiceOver) or elements list (NVDA, JAWS)
  • Check that labels are read together with their associated input fields
  • Ensure error messages are announced when forms are submitted with invalid data
  • Verify that focus is trapped correctly inside modal dialogs and cannot escape

In OpenDesign import screen-reader-testing from its SKILL.md link: Plugins → Add → Skill → Import from link, then pick it in the top bar.

Download OpenDesignRead the quickstart

05 Open source, traceable

Source, License and Verification

Where this page's facts come from, and when they were last checked.

Author
Seth Hobson
Repository
github.com/wshobson/agents Branch main
Skill file
plugins/accessibility-compliance/skills/screen-reader-testing/SKILL.md Content checksum recorded at verification; commit 4236bb9
License
MIT From LICENSE.
Repository stars
39,635 GitHub snapshot taken 2026-09-14 for the whole wshobson/agents repository, which contains 18 skills in this catalog. Not a rating or usage count for screen-reader-testing.
Verified by OpenDesign
2026-09-14 Source file, path, license text and star count were checked. Not bundled in OpenDesign main (checked 2026-08-28); a live run has not been recorded on this page.

Inside the SKILL.md

  1. When to Use This SkillLists scenarios like validating compatibility, testing ARIA, debugging assistive tech, and verifying forms and navigation
  2. Core ConceptsCovers major screen readers by platform and usage, minimum testing priority, and browse vs focus vs application modes
  3. VoiceOver (macOS)Setup instructions, essential commands with modifier keys, rotor navigation, testing checklist, and common HTML/ARIA issue fixes
  4. NVDA (Windows)Setup and commands, heading and landmark navigation, browse vs focus mode switching, and step-by-step test script
  5. JAWS (Windows)Essential commands including virtual cursor, quick keys for element types, forms mode, and table navigation shortcuts
  6. TalkBack (Android)Setup toggle, touch gestures for navigation and activation, and reading control granularity options
  7. Common Test ScenariosAccessible patterns with code for modal dialogs with focus trapping, live regions, and tab interfaces with keyboard support
  8. Debugging TipsJavaScript function to log accessible name, role, state, and visibility of elements as screen readers perceive them
  9. Best PracticesDo's and don'ts covering actual testing, semantic HTML priority, mode testing, focus management, and avoiding single-SR validation
The Skill's Own Description
“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.”

Front-matter description from SKILL.md. The full file is about 12,020 characters. Read the full file on GitHub.

Screen Reader Testing

Run screen-reader-testing on a Real Design Review Task.

Download OpenDesign, import screen-reader-testing from its SKILL.md link, paste the prompt above, and read the plan before the result.

Download OpenDesignBrowse all skills
Terminal
npx skills add https://github.com/wshobson/agents --skill screen-reader-testing

OpenDesign Desktop

One design system. Every output unmistakably your brand

Inside the full Vibe Design Workspace, use the same brand rules across websites, slide decks, interactive prototypes, dashboards, images, and HTML video. Connect Codex, Claude Code, Cursor, and other coding agents already on your computer, then create locally for free.

  • Web, slides, prototypes, dashboards, images, and video
  • 140+ design systems, plus the full template and skill library
  • Connect local Codex and 21+ coding agents · Free to use
Download free

Available for macOS and Windows