102.7K+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

A guide to checking interfaces with real screen readers, including VoiceOver, NVDA, JAWS, TalkBack and Narrator. It provides platform-specific commands and checks for semantics, forms, focus and dynamic announcements. The skill file itself does not operate every reader or certify accessibility; the selected software and an operator or suitable test environment are still required.

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

  • A test plan for the selected reader, browser and platform combinations
  • Observed findings for labels, focus, keyboard flows, errors and dynamic announcements
  • Targeted semantic or ARIA fixes with explicit retest requirements
See the example prompt ↗

How It Works

  1. 01
    Test with Major Screen Readers by Platform

    Choose reader/browser combinations for your users. The captured guide includes NVDA with Firefox, VoiceOver with Safari, JAWS with Chrome, TalkBack on Android and Narrator with Edge. Its usage percentages are not verified current market-share data.

  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

What to Provide

  • Pages and interactions to testProvide the URL or runnable app, key tasks, expected labels and announcements, and success, loading and error states.
  • Reader and platform accessIdentify available devices, browsers and installed screen readers, and who can operate them. Report untested combinations instead of inferring a pass from source inspection.

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.

Editorial example based on the reviewed source; not an executed task or an upstream quotation.

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
  • Record reader, browser, platform and observed behavior. Mark any combination that was not actually tested.

OpenDesign provides a local workspace for coding agents. Check the installed version for skill availability and setup; this source review does not verify bundled skills or include external tools and services.

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