Advanced Guide

Why Accessibility Audits Pass But Users Still Struggle

Rule-based tools like Axe and Lighthouse check for WCAG violations — missing alt text, low contrast, missing form labels. But passing those checks doesn't mean the experience is good. These examples all pass automated audits yet produce confusing screen reader output.

<div class="card" onclick="navigate('/post/123')">
  <img src="thumb.jpg" alt="Blog post thumbnail" />
  <h3>Understanding ARIA</h3>
  <p>A deep dive into ARIA attributes...</p>
</div>

Understanding ARIA
A deep dive into ARIA attributes...

<button>Delete</button>
<div class="tooltip" role="tooltip" id="tip1">
  This action cannot be undone
</div>

Delete, button

<div role="tablist">
  <button role="tab" aria-selected="true">Tab 1</button>
  <button role="tab">Tab 2</button>
  <button role="tab">Tab 3</button>
</div>

Tab 1, tab, selected
Tab 2, tab
Tab 3, tab

<button>
  <span class="icon">&#xE87C;</span>
  <span class="label">Favorite</span>
</button>

 Favorite, button

<h3>Shipping speed</h3>
<label><input type="radio" name="ship" /> Standard</label>
<label><input type="radio" name="ship" /> Express</label>
<label><input type="radio" name="ship" /> Overnight</label>

Shipping speed, heading level 3
Standard, radio button, not checked
Express, radio button, not checked
Overnight, radio button, not checked

Debugging Accessibility Like a User Hears It

Step-by-step breakdowns of real accessibility bugs — diagnosed using Speakable output the same way you'd use browser DevTools to debug a visual bug.

<div class="modal-overlay" style="display:block">
  <div class="modal">
    <h2>Confirm deletion</h2>
    <p>Are you sure you want to delete this item?</p>
    <button>Cancel</button>
    <button>Delete</button>
  </div>
</div>

Confirm deletion
Are you sure you want to delete this item?
Cancel, button
Delete, button

<div class="modal-overlay" style="display:block">
  <div class="modal" role="dialog" aria-modal="true"
    aria-labelledby="modal-title">
    <h2 id="modal-title">Confirm deletion</h2>
    <p>Are you sure you want to delete this item?</p>
    <button>Cancel</button>
    <button>Delete</button>
  </div>
</div>

Confirm deletion, dialog
  Confirm deletion, heading level 2
  Are you sure you want to delete this item?
  Cancel, button
  Delete, button

<div class="search-results">
  <span class="count">24 results found</span>
  <ul>
    <li><a href="/r/1">Result one</a></li>
    <!-- ... -->
  </ul>
</div>

24 results found
list
  Result one, link

<div class="search-results">
  <span class="count" role="status" aria-live="polite"
    aria-atomic="true">24 results found</span>
  <ul>
    <li><a href="/r/1">Result one</a></li>
    <!-- ... -->
  </ul>
</div>

24 results found
list
  Result one, link

<table>
  <tr>
    <td><strong>Name</strong></td>
    <td><strong>Email</strong></td>
    <td><strong>Role</strong></td>
  </tr>
  <tr>
    <td>Alice</td>
    <td>alice@co.com</td>
    <td>Admin</td>
  </tr>
</table>

table
  row
    Name
    Email
    Role
  row
    Alice
    alice@co.com
    Admin

<table>
  <tr>
    <th>Name</th>
    <th>Email</th>
    <th>Role</th>
  </tr>
  <tr>
    <td>Alice</td>
    <td>alice@co.com</td>
    <td>Admin</td>
  </tr>
</table>

table
  row
    Name, column header
    Email, column header
    Role, column header
  row
    Alice
    alice@co.com
    Admin

Manual Screen Reader Testing vs Speakable

Both approaches have a place. Here's an honest comparison of when each makes sense.

Using Speakable in Your Development Workflow

Speakable fits at multiple points in the development lifecycle. Here's where it adds the most value.

Local Development

Run Speakable against your component HTML during development for instant feedback. No screen reader setup, no context switching.

# Quick check while developing
speakable src/components/Modal.html -s all -f text

# Focus on a specific element
speakable page.html --selector ".checkout-form" -f audit

Storybook Integration

Add a script that extracts rendered HTML from Storybook stories and runs Speakable against each one. This gives you per-component accessibility output alongside your visual stories.

#!/bin/bash
# Build Storybook static output
npx storybook build -o storybook-static

# Run Speakable against each story's iframe HTML
for file in storybook-static/iframe.html; do
  echo "=== $file ==="
  speakable "$file" --selector "#storybook-root" -s all -f text
done

PR Checks

Surface announcement changes directly in pull requests. When a PR changes screen reader output, the diff makes it visible to reviewers.

name: A11y PR Check
on: pull_request

jobs:
  announcement-diff:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - run: npm ci

      # Get the base branch HTML
      - run: git show origin/${GITHUB_BASE_REF}:dist/index.html > /tmp/base.html

      # Diff against current
      - name: Check for announcement changes
        run: |
          OUTPUT=$(npx @reticular/speakable dist/index.html --diff /tmp/base.html -f text 2>&1) || true
          if [ -n "$OUTPUT" ]; then
            echo "## Screen Reader Output Changes" >> $GITHUB_STEP_SUMMARY
            echo '```' >> $GITHUB_STEP_SUMMARY
            echo "$OUTPUT" >> $GITHUB_STEP_SUMMARY
            echo '```' >> $GITHUB_STEP_SUMMARY
          fi

Snapshot Testing

Treat screen reader output like a visual snapshot. Store the expected output and fail tests when it changes unexpectedly.

import { execSync } from 'child_process';
import { readFileSync } from 'fs';

describe('Accessibility snapshots', () => {
  it('button component announces correctly', () => {
    const output = execSync(
      'npx @reticular/speakable src/Button.html -s nvda -f text'
    ).toString().trim();

    expect(output).toMatchInlineSnapshot(`
      "Submit, button"
    `);
  });

  it('navigation announces with landmark', () => {
    const output = execSync(
      'npx @reticular/speakable src/Nav.html -s voiceover -f text'
    ).toString().trim();

    expect(output).toMatchInlineSnapshot(`
      "navigation, Main
        Home, link
        About, link
        Contact, link"
    `);
  });
});

How Screen Readers Actually Interpret Your UI

Key behaviors that affect what users hear — and that often surprise developers.

<button aria-label="Close" title="Close dialog">
  ✕
</button>

Close, button

Close, button

<div aria-hidden="true">
  <button>Important action</button>
  <a href="/help">Help</a>
</div>

(nothing announced)

(nothing announced)

<button role="link">Read more</button>

Read more, link

Read more, link

<!-- Decorative (hidden from SR) -->
<img src="divider.svg" alt="" />

<!-- Missing alt (problematic) -->
<img src="chart.png" />

(decorative: nothing)
(missing: graphic)

(decorative: nothing)
(missing: image)

<nav aria-label="Primary">
  <a href="/">Home</a>
</nav>
<main>
  <h1>Content</h1>
</main>
<nav aria-label="Footer">
  <a href="/terms">Terms</a>
</nav>

Primary, navigation landmark
  Home, link
main landmark
  Content, heading level 1
Footer, navigation landmark
  Terms, link

navigation, Primary
  Home, link
main
  heading level 1, Content
navigation, Footer
  Terms, link

<h2>Getting Started</h2>
<button>Submit</button>

Getting Started, heading level 2
Submit, button

heading level 2, Getting Started
Submit, button

<!-- Native disabled (not focusable) -->
<button disabled>Submit</button>

<!-- ARIA disabled (still focusable) -->
<button aria-disabled="true">Submit</button>

Submit, button, unavailable
Submit, button, unavailable

Submit, button, dimmed
Submit, button, dimmed

How Accurate Is Speakable?

Speakable produces heuristic output based on the ARIA specification and documented screen reader behavior. Here's what that means in practice.

How output is derived

Speakable parses HTML into a DOM, walks the tree to compute accessible names (following the W3C accessible name computation algorithm), maps roles (explicit ARIA roles first, then implicit HTML roles), extracts states, and renders the result through screen reader-specific formatters that apply each reader's documented announcement patterns.

Known limitations

• Static HTML only — no JavaScript execution, no dynamic content, no live regions
• No CSS visibility computation (relies on ARIA and HTML semantics for hidden detection)
• Screen reader heuristics vary by version — Speakable targets current stable releases
• Some screen readers have undocumented behaviors that differ from the ARIA spec
• Complex widget patterns (combobox, treegrid) may have simplified output
• Browser-specific rendering differences are not modeled

Cross-reader differences

NVDA, JAWS, and VoiceOver each have distinct announcement patterns. Speakable models these differences:

What this means for you