Storybook Screen Reader Addon

A screen reader simulation addon for Storybook that helps developers test accessibility during component development. It uses industry-standard libraries to provide accurate accessible name computation and role announcements.

Features

• 🎯 W3C AccName Spec - Uses dom-accessibility-api for accurate accessible name computation
• 🏷️ ARIA Role Detection - Uses aria-query for proper role mapping
• 🔊 Voice Reader - Uses Web Speech API to announce focused elements
• 📝 Text Reader - Displays announcements in the addon panel
• 🎯 Focus Tracking - Automatically tracks focus changes (Tab, arrow keys, clicks)
• 📢 Live Regions - Announces aria-live region updates
• 🌐 Deep Shadow DOM Support - Traverses into shadow roots to find the actual focused element (like real screen readers)
• 🎨 Spectrum Web Components UI - Built with Lit + SWC for the addon panel
• 🔄 Story Navigation - Automatically resets when switching between stories

---

Comparison: This Plugin vs macOS VoiceOver

Feature	This Plugin	VoiceOver (macOS)	Notes
Accessible Name Computation	✅ W3C AccName spec	✅ Native	We use dom-accessibility-api which implements the full W3C spec
Accessible Description	✅ aria-describedby	✅ Native	Full support via dom-accessibility-api
ARIA Roles	✅ 40+ roles	✅ All roles	We use aria-query for accurate role detection
Focus Tracking	✅ focusin event	✅ Native	Tracks Tab, Shift+Tab, clicks
Shadow DOM Traversal	✅ Deep active element	✅ Native	Finds actual focused element inside shadow roots
Arrow Key Navigation	✅ aria-activedescendant	✅ Native	For menus, listboxes, trees
Live Regions	✅ aria-live	✅ Native	Announces dynamic content changes
Form States	✅ required, invalid, readonly	✅ Native	Comprehensive form feedback
Button States	✅ pressed, expanded	✅ Native	Toggle buttons, accordions
List Position	✅ "Item X of Y"	✅ Native	Lists, tabs, options
Table Navigation	⚠️ Basic	✅ Full	We announce row/column counts
Checkbox States	✅ checked, mixed, unchecked	✅ Native	Tri-state support
Slider Values	✅ value, min, max, valuetext	✅ Native	Full range announcements
Virtual Buffer Mode	❌ Not supported	✅ Native	NVDA/JAWS feature, not VoiceOver
Reading All Content	❌ Focus-only	✅ Browse mode	We only announce focused elements
OS Integration	❌ Browser only	✅ System-wide	VoiceOver works across all apps
Braille Output	❌ Not supported	✅ Native	Hardware requirement

What We Implement

Category	Supported Features
Roles	button, link, checkbox, radio, switch, textbox, searchbox, combobox, listbox, slider, spinbutton, heading, img, listitem, option, menuitem, tab, tabpanel, navigation, main, banner, contentinfo, complementary, region, article, form, search, dialog, alertdialog, alert, status, log, progressbar, meter, tooltip, tree, treeitem, grid, table, menu, menubar, toolbar, group, separator
States	checked, pressed, expanded, selected, invalid, required, readonly, disabled
Properties	aria-label, aria-labelledby, aria-describedby, aria-valuenow, aria-valuemin, aria-valuemax, aria-valuetext, aria-level, aria-activedescendant, aria-modal
Live Regions	aria-live (polite/assertive), role="alert", role="status", role="log"

---

Accuracy & Trust Level

Use Case	Reliability	Recommendation
Quick dev feedback	✅ High	Great for catching obvious issues
ARIA role verification	✅ High	Accurate role mapping via aria-query
Accessible name testing	✅ High	W3C spec via dom-accessibility-api
Focus order testing	✅ High	Reliable focus tracking
Live region testing	✅ Medium	Basic support, may miss edge cases
Full WCAG compliance	⚠️ Medium	Use with real screen readers
Production sign-off	❌ Low	Always test with VoiceOver/NVDA

Recommended Testing Workflow

1. 🛠️  Development    →  Use this plugin (instant feedback)
2. 🔍  Code Review    →  Use axe-core / Storybook a11y addon  
3. ✅  QA Testing     →  Use REAL VoiceOver / NVDA
4. 👥  User Testing   →  Involve actual screen reader users

---

Installation

npm install storybook-screen-reader

or

yarn add storybook-screen-reader

Setup

Add the addon to your .storybook/main.js:

module.exports = {
  addons: [
    // ... other addons
    'storybook-screen-reader',
  ],
};

Usage

1. Open Storybook and navigate to any story
2. Click the "Screen Reader" tab in the addons panel
3. Enable Voice Reader and/or Text Reader
4. Navigate through your component:
   • Tab / Shift+Tab - Move between focusable elements
   • Arrow keys - Navigate within menus, listboxes, etc.
   • Click - Focus any element

The addon will announce each focused element with its role, name, and state.

Announcement Examples

Element	Announcement
Button	"Button, Submit. Press Space or Enter to activate."
Toggle Button	"Button, Dark mode, pressed. Press Space or Enter to activate."
Link	"Link, Learn more. Press Enter to follow."
Checkbox	"Checkbox, Accept terms, not checked. Press Space to toggle."
Radio	"Radio button, Option A, selected."
Switch	"Switch, Notifications, on. Press Space to toggle."
Text Field	"Text field, Email, required. Empty."
Invalid Field	"Text field, Password, required, invalid entry. Contains: ****"
Slider	"Slider, Volume. Value: 75. Range: 0 to 100."
Heading	"Heading level 2, Welcome"
Tab	"Tab, Settings, selected. 2 of 4."
List Item	"Home. List item 1 of 5."
Menu Item	"Menu item, Copy"
Dialog	"Modal Dialog, Confirm deletion"
Alert	"Alert: Your session will expire in 5 minutes"
Progress	"Progress bar, Uploading. 45 percent"
Table	"Table, User data. 10 rows, 4 columns."

---

Technical Details

Libraries Used

Library	Purpose
dom-accessibility-api	W3C Accessible Name and Description computation
aria-query	ARIA role definitions and element-to-role mapping
lit	Web component framework for addon panel
@spectrum-web-components	Adobe Spectrum design system components

Architecture

┌─────────────────────────────────────────────────────────────┐
│                    Storybook Manager                         │
│  ┌─────────────────────────────────────────────────────┐   │
│  │  screen-reader-panel (Lit + SWC)                     │   │
│  │  └── Toggle switches for voice/text output          │   │
│  └─────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    Storybook Preview (iframe)                │
│  ┌─────────────────────────────────────────────────────┐   │
│  │  ScreenReader class                                  │   │
│  │  ├── Focus tracking (focusin event)                 │   │
│  │  ├── ARIA attribute monitoring (MutationObserver)   │   │
│  │  ├── Live region monitoring (MutationObserver)      │   │
│  │  ├── Name computation (dom-accessibility-api)       │   │
│  │  ├── Role detection (aria-query)                    │   │
│  │  └── Speech synthesis (Web Speech API)              │   │
│  └─────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘

---

Limitations

This addon is a development aid, not a replacement for testing with real screen readers:

What We Can't Do	Why
Access OS Accessibility Tree	Browser security restrictions
Virtual/Browse mode	VoiceOver reads all content, we only track focus
Braille output	Hardware requirement
System-wide announcements	Browser sandbox
100% VoiceOver parity	Different underlying technology

Always test with actual assistive technology before shipping:

• VoiceOver (macOS/iOS)
• NVDA (Windows, free)
• JAWS (Windows)
• TalkBack (Android)

---

Compatibility

• Storybook 8.x
• React, Vue, Angular, Web Components, HTML
• Works with Shadow DOM

Contributing

Issues and PRs welcome! GitHub Repository

Credits

Originally created by Víctor Lara. Updated and maintained by Tarun Tomar.

License

MIT