npm package: @mbeggiato/storybook-screen-reader
Description: A Screen Reader addon for Storybook that helps developers test the accessibility of their components without needing to install a real screen reader
Author: Marcel Beggiato
Latest version: 1.0.5

# 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.

[![Storybook Demo](https://raw.githubusercontent.com/storybooks/brand/master/badge/badge-storybook.svg)](https://storybook-screen-reader.netlify.app/?path=/story/example-page--logged-in)
[![NPM Version](https://img.shields.io/npm/v/@mbeggiato/storybook-screen-reader.svg)](https://www.npmjs.com/package/@mbeggiato/storybook-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

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

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

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

## 🛠️ Development

### Setup

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

### Build the addon

```bash
npm run build
```

### Run the demo

```bash
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 :)