Skip to main content
Web Stories for WordPress is built with accessibility in mind, following WAI-ARIA standards and WCAG 2.1 guidelines to ensure stories are accessible to all users.

​
Overview

The plugin implements accessibility features including keyboard navigation, screen reader support, ARIA labels, focus management, and semantic HTML structure.

​
Keyboard Navigation

All story interactions are fully keyboard accessible:

Navigation Controls

  • Right Arrow / Space: Next page
  • Left Arrow: Previous page
  • Home: First page
  • End: Last page
  • Tab: Navigate interactive elements
  • Enter: Activate links and buttons
  • Escape: Close modals and attachments

​
Testing Keyboard Navigation

  1. Load a story in your browser
  2. Press Tab to focus on the story
  3. Use arrow keys to navigate between pages
  4. Press Tab to focus on interactive elements (links, buttons)
  5. Press Enter to activate focused elements
On macOS, you may need to enable full keyboard access in System Preferences for full keyboard navigation support in browsers.

​
Screen Reader Support

Web Stories are compatible with popular screen readers:

​
Supported Screen Readers

  • VoiceOver (macOS, iOS) - Built-in
  • NVDA (Windows) - Free download
  • JAWS (Windows) - Commercial
  • TalkBack (Android) - Built-in
  • ChromeVox (ChromeOS) - Built-in

​
ARIA Live Regions

The plugin uses ARIA live regions to announce dynamic content changes (from docs/accessibility-guidelines.md:9-17). 
const LiveRegionProvider = () => {
  const { announce } = useLiveRegion();
  
  // Announce page changes
  useEffect(() => {
    announce(`Page ${currentPage} of ${totalPages}`);
  }, [currentPage]);
};
Keep live region announcements concise and relevant. Overly verbose announcements can be disruptive to screen reader users.

​
ARIA Labels and Roles

All interactive elements include appropriate ARIA attributes: 
<!-- Navigation buttons -->
<button aria-label="Next page" role="button">
  <svg aria-hidden="true">...</svg>
</button>

<!-- Story pages -->
<amp-story-page id="page-1" aria-label="Page 1: Introduction">
  ...
</amp-story-page>

<!-- Interactive elements -->
<a href="..." aria-label="Learn more about product">
  View Details
</a>

​
Focus Management

The editor implements proper focus management:
  • Focus is trapped within modal dialogs
  • Focus returns to trigger element when modals close
  • Focus indicators are visible on all interactive elements
  • Focus order follows logical reading order
  • Skip links allow bypassing repetitive content

​
Alternative Text

​
Image Alt Text

All images in stories should include descriptive alt text:
  1. Select an image in the editor
  2. Click the Accessibility tab in the right panel
  3. Enter descriptive alt text
  4. Save your story
<amp-img
  src="product-image.jpg"
  alt="Red running shoes with white laces on wooden floor"
  width="720"
  height="1280"
  layout="responsive"
>
</amp-img>
  • Describe the image content and context
  • Keep descriptions concise (aim for under 125 characters)
  • Don’t start with “Image of” or “Picture of”
  • Include relevant text visible in images
  • For decorative images, use empty alt text alt=""
  • Avoid redundancy if caption provides same information

​
Video Captions

For videos in stories:
  1. Provide caption/subtitle files (WebVTT format)
  2. Upload captions in the video settings
  3. Enable captions by default for accessibility
<amp-video
  src="video.mp4"
  width="720"
  height="1280"
  layout="responsive"
  poster="poster.jpg"
>
  <track kind="captions" src="captions.vtt" srclang="en" label="English" default>
</amp-video>

​
Color and Contrast

​
WCAG Contrast Requirements

Text and interactive elements must meet WCAG 2.1 contrast ratios:
  • Normal text: Minimum 4.5:1 contrast ratio
  • Large text (18pt+): Minimum 3:1 contrast ratio
  • UI components: Minimum 3:1 contrast ratio

​
Checking Contrast

The story editor includes a built-in contrast checker:
  1. Select a text element
  2. View the color picker
  3. Check the contrast ratio indicator
  4. Adjust colors to meet WCAG AA or AAA standards
You can also use external tools:
Avoid using color alone to convey information. Supplement color with text, icons, or patterns to ensure information is accessible to colorblind users.

​
Text Sizing and Readability

​
Minimum Text Sizes

Follow these guidelines for readable text:
  • Body text: Minimum 16px (1em)
  • Small text: Minimum 14px (0.875em)
  • Headings: Scale appropriately from body text
  • Line height: 1.4-1.6 for body text
  • Line length: 50-75 characters optimal

​
Font Choices

Choose accessible fonts:
  • Use sans-serif fonts for body text
  • Avoid overly decorative or script fonts
  • Ensure sufficient letter spacing
  • Don’t rely on font weight alone for emphasis
  • Test readability on mobile devices

​
Animation and Motion

​
Respecting User Preferences

The plugin respects the prefers-reduced-motion media query: 
@media (prefers-reduced-motion: reduce) {
  .story-animation {
    animation: none;
    transition: none;
  }
}
Users who enable “Reduce motion” in their system settings will see:
  • Simplified page transitions
  • Reduced animation effects
  • No auto-playing animations
  • Static alternative to animated content

​
Animation Best Practices

  • No flashing content faster than 3 times per second
  • Avoid large areas of rapid color changes
  • Limit parallax and auto-scrolling effects
  • Provide pause controls for auto-playing content

​
Testing for Accessibility

The project follows comprehensive accessibility testing practices (from docs/accessibility-testing.md).

​
Automated Testing

​
Unit Tests with jest-axe

import { axe, toHaveNoViolations } from 'jest-axe';

expect.extend(toHaveNoViolations);

describe('StoryComponent', () => {
  it('should have no accessibility violations', async () => {
    const { container } = render(<StoryComponent />);
    const results = await axe(container);
    expect(results).toHaveNoViolations();
  });
});

​
Integration Tests

it('should render with no accessibility issues', async () => {
    fixture = new Fixture();
    await fixture.render();
    await expectAsync(fixture.editor.canvas).toHaveNoViolations();
});

​
Manual Testing

  1. Press Cmd + F5 to enable VoiceOver
  2. Press Control + Option + Right Arrow to navigate
  3. Press Control + Option + Space to interact
  4. Press Control to stop verbalization
  5. Press Control + Option + U to open rotor
Verify:
  • All content is announced correctly
  • Interactive elements are clearly identified
  • Navigation structure makes sense
  • Images have meaningful alt text
  1. Launch NVDA
  2. Press NVDA + Down Arrow to navigate
  3. Press NVDA + H to skip to headings
  4. Press NVDA + B to skip to buttons
  5. Press Control to stop verbalization
See NVDA shortcuts for complete list.
  1. Use only keyboard (no mouse)
  2. Tab through all interactive elements
  3. Verify visible focus indicators
  4. Test all keyboard shortcuts
  5. Ensure logical tab order
  6. Verify no keyboard traps

​
Browser DevTools

Chrome DevTools includes accessibility features:
  1. Open DevTools (F12)
  2. Go to Elements tab
  3. Open Accessibility pane
  4. Inspect accessibility tree
  5. Check ARIA attributes
  6. Run Lighthouse accessibility audit

​
Browser Extensions

​
Accessibility Checklist

Before publishing stories, verify:
  • All images have descriptive alt text
  • Videos include captions or transcripts
  • Text meets minimum contrast ratios (4.5:1)
  • Interactive elements are keyboard accessible
  • Focus indicators are visible
  • Content is readable with screen readers
  • No flashing content >3 times per second
  • Animations respect prefers-reduced-motion
  • Forms include proper labels
  • Error messages are descriptive and helpful
  • Heading structure is logical
  • Links have descriptive text (avoid “click here”)

​
Common Accessibility Issues

Problem: Images without alt attributesSolution: Add descriptive alt text to all images, or use empty alt (alt="") for purely decorative images.
Problem: Text is difficult to read against backgroundSolution: Increase contrast to meet WCAG AA standards (4.5:1 for normal text). Use the built-in contrast checker.
Problem: Users can’t escape modal dialogs with keyboardSolution: Ensure Escape key closes modals and focus returns to trigger element.
Problem: No visual indication of focused elementSolution: Ensure all interactive elements have visible focus styles. Don’t use outline: none without providing alternative.
Problem: Links with generic text like “Click here” or “Read more”Solution: Use descriptive link text that makes sense out of context. Add aria-label for additional context if needed.

​
Accessibility Resources

​
Guidelines and Standards

​
Testing Tools

​
Learning Resources

Accessibility is an ongoing process, not a one-time checklist. Continuously test and improve your stories to ensure they remain accessible to all users.

Build docs developers (and LLMs) love

Get started for freeTalk to us