thrillwiki_django_no_react/docs/accessibility/screen-reader-testing.md

Screen Reader Testing Checklist

This document provides a comprehensive checklist for testing ThrillWiki with screen readers to ensure WCAG 2.1 AA compliance.

Recommended Screen Readers

Screen Reader	Platform	Cost	Notes
NVDA	Windows	Free	Most widely used free option
JAWS	Windows	Commercial	Industry standard
VoiceOver	macOS/iOS	Built-in	Activate with Cmd+F5
TalkBack	Android	Built-in	Enable in Accessibility settings
Narrator	Windows	Built-in	Basic testing

Test Scenarios

Navigation

• Skip to main content link works and is announced
• All navigation items are announced with their role
• Current page is indicated (aria-current="page")
• Dropdown menus announce as "button, collapsed" when closed
• Dropdown menus announce as "button, expanded" when open
• Menu items announce with role="menuitem"
• Breadcrumbs are announced as navigation landmark

Search

• Search input is announced with label "Search parks and rides"
• Search results count is announced when results appear
• Each result is announced with its content
• Arrow key navigation announces current selection
• "No results found" is announced when applicable

Forms

• All form fields have associated labels announced
• Required fields announce "required"
• Error messages are announced immediately when form validates
• Success messages are announced after form submission
• Help text is associated and announced with fields
• Field types are announced (text input, checkbox, select, etc.)

Interactive Components

• Buttons announce their purpose/label
• Icon-only buttons announce their aria-label
• Links announce destination or purpose
• Modals announce their title when opened
• Modal content is announced as dialog
• Closing modal announces return to previous context
• Theme toggle announces current state (pressed/not pressed)

Dynamic Content

• Search results are announced via aria-live region
• Filter changes announce result count
• Status updates (success, error) are announced
• Loading states are announced ("Loading...")
• HTMX content swaps announce via live regions

Images

• All meaningful images have descriptive alt text
• Decorative images are hidden (alt="" or aria-hidden)
• Complex images have long descriptions available
• Avatar images include user's name in alt text

Tables (if applicable)

• Tables have proper headers (th elements)
• Table caption or aria-label describes table purpose
• Data cells associate with headers

Headings

• Page has exactly one h1
• Heading hierarchy is logical (h1 > h2 > h3)
• No skipped heading levels
• Headings describe section content

Testing Commands

NVDA (Windows)

Command	Action
Insert + Down Arrow	Read next item
Insert + Up Arrow	Read previous item
Insert + Space	Read current item
Insert + F7	Elements list (links, headings, landmarks)
H	Next heading
Shift + H	Previous heading
K	Next link
F	Next form field
D	Next landmark
Insert + Ctrl + N	Read notifications

VoiceOver (macOS)

Command	Action
VO + Right Arrow	Next item
VO + Left Arrow	Previous item
VO + U	Rotor (elements list)
VO + A	Read all from current position
VO + Cmd + H	Next heading
VO + Cmd + J	Next form control
VO + Cmd + L	Next link

Note: VO = Control + Option

VoiceOver (iOS)

Gesture	Action
Swipe Right	Next item
Swipe Left	Previous item
Double Tap	Activate item
Two-finger Swipe Up	Read all from current position
Rotor (two-finger twist)	Change navigation mode

JAWS (Windows)

Command	Action
Down Arrow	Next item
Up Arrow	Previous item
Insert + F5	Forms list
Insert + F6	Headings list
Insert + F7	Links list
H	Next heading
F	Next form field
T	Next table
R	Next region/landmark

TalkBack (Android)

Gesture	Action
Swipe Right	Next item
Swipe Left	Previous item
Double Tap	Activate item
Swipe Up then Down	Navigation settings

Common Issues to Watch For

Problematic Patterns

1. Missing labels: Form fields without associated labels
2. Duplicate IDs: Multiple elements with same ID breaks aria-describedby
3. Empty buttons: Buttons with no text or aria-label
4. Inaccessible modals: Focus not trapped, no escape to close
5. Auto-playing media: Audio/video that plays automatically
6. Timeout without warning: Sessions expiring without notice
7. Moving focus unexpectedly: Focus jumping after interactions
8. Color-only information: Status conveyed only by color

Good Patterns

1. Clear labels: Every form field has descriptive label
2. Error prevention: Clear instructions, validation before submit
3. Focus management: Logical order, visible indicators, trapped in modals
4. Consistent navigation: Same navigation pattern on all pages
5. Multiple ways: Multiple paths to same content
6. Descriptive links: Link text describes destination (not "click here")

Reporting Issues

When reporting accessibility issues, include:

1. Screen reader and version used
2. Browser and version
3. Page URL
4. Steps to reproduce
5. Expected behavior
6. Actual behavior (what was announced)
7. WCAG success criterion violated

WCAG 2.1 AA Quick Reference

Level A (Must Have)

• 1.1.1 Non-text Content (alt text)
• 1.3.1 Info and Relationships (semantic HTML)
• 2.1.1 Keyboard (all functionality via keyboard)
• 2.4.1 Bypass Blocks (skip links)
• 4.1.2 Name, Role, Value (ARIA)

Level AA (Should Have)

• 1.4.3 Contrast (Minimum) (4.5:1 ratio)
• 1.4.4 Resize Text (200% zoom)
• 2.4.6 Headings and Labels (descriptive)
• 2.4.7 Focus Visible (visible focus indicator)
• 3.2.3 Consistent Navigation
• 3.2.4 Consistent Identification

Resources

• WCAG 2.1 Guidelines
• WebAIM Screen Reader Survey
• NVDA User Guide
• VoiceOver User Guide
• JAWS Quick Start