# 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](https://www.w3.org/TR/WCAG21/)
- [WebAIM Screen Reader Survey](https://webaim.org/projects/screenreadersurvey9/)
- [NVDA User Guide](https://www.nvaccess.org/files/nvda/documentation/userGuide.html)
- [VoiceOver User Guide](https://support.apple.com/guide/voiceover/welcome/mac)
- [JAWS Quick Start](https://www.freedomscientific.com/products/software/jaws/)