# Keyboard Navigation Guide

ThrillWiki is designed to be fully accessible via keyboard. This guide documents all keyboard shortcuts and navigation patterns.

## Global Shortcuts

| Key | Action |
|-----|--------|
| Tab | Move focus forward |
| Shift + Tab | Move focus backward |
| Enter | Activate focused element |
| Space | Activate buttons/checkboxes |
| Escape | Close modals/dropdowns |

## Navigation Menu

| Key | Action |
|-----|--------|
| Tab | Focus menu button |
| Enter/Space | Open menu |
| Arrow Down | Next menu item |
| Arrow Up | Previous menu item |
| Escape | Close menu |
| Home | First menu item |
| End | Last menu item |

## Search

| Key | Action |
|-----|--------|
| Tab | Focus search input |
| Type | Start searching (debounced 300ms) |
| Arrow Down | Navigate to next result |
| Arrow Up | Navigate to previous result (or back to input) |
| Enter | Select current result (navigate to link) |
| Escape | Close results and blur input |
| Home | Jump to first result |
| End | Jump to last result |

## Modals

| Key | Action |
|-----|--------|
| Tab | Next focusable element (trapped within modal) |
| Shift + Tab | Previous focusable element (trapped within modal) |
| Escape | Close modal |
| Home | Jump to first focusable element |
| End | Jump to last focusable element |

## Forms

| Key | Action |
|-----|--------|
| Tab | Move to next field |
| Shift + Tab | Move to previous field |
| Enter | Submit form (when focused on submit button) |
| Space | Toggle checkbox/radio button |
| Arrow Down/Up | Navigate select options |
| Escape | Close select dropdown |

## Dropdowns (User Menu, Browse Menu)

| Key | Action |
|-----|--------|
| Enter/Space | Toggle dropdown open/closed |
| Escape | Close dropdown |
| Arrow Down | Navigate to next item |
| Arrow Up | Navigate to previous item |
| Tab | Move through items (or exit dropdown) |

## Mobile Menu

| Key | Action |
|-----|--------|
| Enter/Space | Open mobile menu |
| Escape | Close mobile menu |
| Tab | Navigate through menu items |

## Theme Toggle

| Key | Action |
|-----|--------|
| Enter/Space | Toggle between light and dark mode |

## Implementation Notes

### Focus Management
- All interactive elements must be reachable via keyboard
- Focus order follows logical reading order (top to bottom, left to right)
- Focus is trapped within modals when open
- Focus returns to trigger element when modal/dropdown closes

### Focus Indicators
- All focusable elements have visible focus indicators
- Focus ring: 2px solid primary color with 2px offset
- Enhanced visibility in high contrast mode
- Custom focus styles for complex components

### ARIA Attributes
- `aria-expanded`: Indicates dropdown/menu open state
- `aria-haspopup`: Indicates element triggers a popup
- `aria-label`: Provides accessible name for icon-only buttons
- `aria-modal`: Indicates modal dialog
- `aria-controls`: Links trigger to controlled element
- `aria-describedby`: Links element to description
- `aria-live`: Announces dynamic content changes

### Skip Links
- Skip to main content link available (hidden until focused)
- Appears at top of page when Tab is pressed first

## Testing Keyboard Navigation

### Manual Testing Checklist
1. Navigate entire site using only keyboard
2. Verify all interactive elements are reachable with Tab
3. Verify Enter/Space activates all buttons and links
4. Verify Escape closes all modals and dropdowns
5. Verify focus indicators are visible
6. Verify focus order is logical
7. Verify focus is trapped in modals
8. Verify focus returns to trigger after closing modals

### Automated Testing
Run accessibility tests:
```bash
python manage.py test backend.tests.accessibility
```

## Browser Compatibility

Keyboard navigation is tested on:
- Chrome (latest)
- Firefox (latest)
- Safari (latest)
- Edge (latest)

Note: Some keyboard shortcuts may conflict with browser shortcuts. In those cases, browser shortcuts take precedence.
