Storybook Screen Reader Addon

A Screen Reader addon for Storybook that helps developers test the accessibility of their components without needing to install a real screen reader.

✨ Features

• Page title announcements when document loads
• Heading navigation with correct level announcement
• Landmark navigation (main, nav, header, footer, section, article)
• List support with item count and position
• Link announcements with accessible names and external link detection
• Button announcements with states (pressed/not pressed, enabled/disabled)
• Image handling with alt text reading or "graphic" fallback
• Form input support with labels and input types (text, checkbox, radio, etc.)
• Form control states (checked/unchecked, required/optional, disabled)
• Focus change announcements during tab navigation
• Logical reading order following DOM structure
• Element-type navigation with keyboard shortcuts
• Quick navigation by specific element types
• Continuous reading mode for all elements
• Interactive element states with proper feedback

🎯 Navigation

• H/Shift+H: Navigate between headings
• D/Shift+D: Navigate between landmarks (main, nav, header, footer)
• K/Shift+K: Navigate between links
• B/Shift+B: Navigate between buttons
• F/Shift+F: Navigate between form elements
• Tab: Normal browser navigation
• Alt+Tab: Screen reader navigation (all elements)
• Escape: Return to normal mode

🔊 Voice Output

• Headings with level: "Heading level 1, Homepage"
• Links with context: "Learn more, link, external"
• Buttons with status: "Save, button, pressed"
• Form fields: "Username, edit text, required"
• Images: Alt text is read aloud, decorative images ignored
• Lists: "List, 5 items" → "Item 1 of 5"

⚡ Interactive Elements

• Detects disabled elements ("unavailable")
• Shows form status (required, checked/unchecked)
• Supports ARIA labels and roles
• Respects empty alt texts for decorative images

🚀 Usage

1. Enable the addon in Storybook
2. Open the Screen Reader panel
3. Turn on "Voice Reader" or "Text Reader"
4. Navigate with keyboard:
   • H for headings
   • K for links
   • B for buttons
   • Tab for normal navigation

📦 Installation

npm install -D @mbeggiato/storybook-screen-reader@latest

Add the addon to .storybook/main.js:

module.exports = {
  addons: ["@mbeggiato/storybook-screen-reader"],
};

🛠️ Development

Setup

git clone https://github.com/MBeggiato/addon-screen-reader.git
cd addon-screen-reader
npm install

Build the addon

npm run build

Run the demo

cd demo
npm install
npm run storybook

The demo will be available at http://localhost:6006

Development workflow

1. Make changes to the addon source code
2. Run npm run build to build the addon
3. The demo automatically picks up the changes
4. Test your changes in the demo Storybook

❌ Not Implemented

• ARIA Live Regions (dynamic content)
• Table navigation
• Character/word/line navigation
• Verbosity settings
• Fieldset/legend groupings

🎯 Target Audience

Perfect for developers who:

• Want to quickly find accessibility issues
• Cannot install screen reader software
• Work in Storybook environments
• Want to integrate accessibility into their development process

📊 Feature Coverage

20 of 27 standard screen reader features implemented (74%)

⚠️ Note: This addon does not replace testing with real screen readers (NVDA, JAWS, VoiceOver), but complements them as a practical development tool.

💬 Feedback

All feedback is welcome! Create an issue in the repository and we'll get back to you ASAP.

🤝 Contributing

Want to contribute? Great!

Create a issue or just go ahead and create a pr for your feature :)