Runtime Accessibility Analysis

What is an Accessibility Timeline?

An Accessibility Timeline is a timestamped sequence of accessibility-relevant events captured during user interaction with a component. Think of it as a recording of everything that matters to assistive technology users: where focus moves, what gets announced, which states change, and when dialogs open or close.

Each timeline captures four categories of events:

• Focus transitions: where keyboard focus moves during interaction, including the role and accessible name of each focused element
• Announcements: text communicated to screen readers via aria-live regions, with politeness level (polite or assertive)
• State changes: ARIA state mutations like aria-expanded, aria-selected, and aria-checked toggling during interaction
• Dialog lifecycle: when dialogs open and close, whether they are modal, and whether focus management follows expected patterns

By capturing these events as a sequence, you can review exactly what happened during an interaction, compare timelines across builds to detect regressions, and identify patterns that indicate broken accessibility behavior.

How It Works

The Runtime Accessibility Engine follows a five-stage pipeline to generate timelines from component interactions:

Built-in Patterns

Speakable includes built-in interaction patterns for common ARIA widgets. These patterns encode the expected keyboard behavior for each widget type, so you can generate timelines without writing custom interaction sequences for every component.

Heuristic Warnings

Even without a comparison baseline, the Runtime Accessibility Engine automatically detects common accessibility anti-patterns and emits warnings. These heuristics run in real-time during timeline capture, flagging issues as they occur.

Interactive Demo

Compare working implementations against broken versions to see how accessibility regressions appear in the timeline. Toggle between variants to observe the difference in events and warnings.

Usage Examples

The runtime engine can be used programmatically, via the CLI, or through Storybook integration. Below are practical examples for each approach.

Programmatic API

Import the runtime module to create timeline generators, execute interaction patterns, and inspect the resulting accessibility events directly in your code.

import { runtime } from '@reticular/speakable';

// Create a timeline generator for your component
const generator = runtime.createTimelineGenerator({
  document: myDocument,
  componentName: 'ConfirmDialog',
});

// Use a built-in interaction pattern
const sequence = runtime.getBuiltinPattern('modal-dialog', {
  trigger: 'button.open-dialog',
});

// Capture the accessibility timeline
const timeline = await generator.capture(sequence);

// Inspect events
for (const event of timeline.events) {
  console.log(`${event.type}: ${event.target.accessibleName}`);
}

// Check for warnings
if (timeline.warnings.length > 0) {
  console.warn('Accessibility issues detected:');
  timeline.warnings.forEach(w => console.warn(` - ${w.payload.message}`));
}

CLI Usage

Run runtime analysis from the command line against any URL or a local Storybook instance. The CLI supports built-in interaction patterns, snapshot baselines, and CI mode for regression detection.

# Analyze a URL with default keyboard exploration
speakable runtime https://localhost:3000/settings

# Use a built-in interaction pattern
speakable runtime https://localhost:3000 --interaction modal-dialog

# Analyze Storybook components
speakable runtime http://localhost:6006 --storybook --story "Dialog*"

# Save baselines for regression detection
speakable runtime http://localhost:6006 --storybook --runtime-snapshot ./baselines

# CI mode: fail on regressions
speakable runtime http://localhost:6006 --storybook --runtime-snapshot ./baselines --runtime-ci

# Authenticate with a protected Storybook instance
speakable runtime https://storybook.internal.company.com --storybook \
  --storybook-auth-header "Bearer eyJhbGciOi..."

# Skip TLS verification for self-signed certificates
speakable runtime https://storybook.local --storybook --storybook-insecure

Storybook Integration

Speakable connects to a running Storybook instance, discovers stories matching your filter, and runs the runtime engine against each one. The pipeline produces an accessibility timeline per story that can be baselined and compared across builds.

Protected and Internal Storybook Instances

Since Speakable runs locally (on your machine or CI runner), it works naturally with VPN-protected Storybook instances. As long as the machine running Speakable can reach the Storybook URL, no special configuration is needed. For Storybook instances behind authentication, use the auth flags:

# Bearer token authentication
speakable runtime https://storybook.internal.company.com --storybook \
  --storybook-auth-header "Bearer your-token-here"

# Custom headers (cookies, API keys)
speakable runtime https://storybook.internal.company.com --storybook \
  --storybook-header "Cookie: session=abc123"

# Self-signed TLS certificates
speakable runtime https://storybook.local:6006 --storybook --storybook-insecure