tfm_ainventory/frontend/docs/ACCESSIBILITY_TESTING.md

# Accessibility Testing Guide

## Keyboard Navigation Testing

Test these flows without using the mouse. Use only Tab, Shift+Tab, Enter, Space, and Arrow keys.

### Test Flow 1: Bottom Navigation
1. Load the application
2. Press Tab repeatedly to highlight each nav button
3. Verify focus ring is visible on each button (blue outline)
4. Press Enter to navigate to each section
5. Verify you can navigate back with Shift+Tab

**Expected Result:** All 5 buttons (Home, Inventory, Logs, Admin, Logout) are reachable via Tab. Focus is always visible.

### Test Flow 2: Scanner Component
1. Navigate to home page
2. Press Tab to reach zoom button (if available)
3. Press Tab to reach "Try Again" button
4. Verify focus states are clear
5. Press Enter on buttons to activate them

**Expected Result:** All buttons show focus ring before activation.

### Test Flow 3: Modal Dialogs
1. Trigger ItemComparisonModal or ConfirmationModal
2. Press Tab through all buttons
3. Verify focus doesn't trap (can escape with Tab/Escape)
4. Close modal with Escape key
5. Focus should return to trigger button

**Expected Result:** Modals don't create keyboard traps. All buttons are tab-reachable.

### Test Flow 4: Form Inputs
1. Navigate to AIOnboarding upload form
2. Press Tab through all form fields
3. Verify focus ring appears on all inputs
4. Type in each field to verify they're functional
5. Press Tab to next field

**Expected Result:** All input fields are reachable and usable via keyboard.

---

## Accessibility Audit Checklist

### Level 1: Critical (Must Fix)
- [ ] All buttons have focus indicators (focus:ring-2)
- [ ] All clickable elements have cursor-pointer
- [ ] All form inputs have associated labels
- [ ] All images have descriptive alt text
- [ ] No keyboard traps (tab can always move forward/backward)
- [ ] Focus order follows visual order (left→right, top→bottom)

### Level 2: Major (Should Fix)
- [ ] Icon-only buttons have aria-label
- [ ] Modal dialogs manage focus
- [ ] Error messages are associated with form fields
- [ ] Color is not the only indicator (text + color)
- [ ] Touch targets are 44×44px minimum
- [ ] Text contrast is 4.5:1 minimum (WCAG AA)

### Level 3: Minor (Nice to Have)
- [ ] Skip links for keyboard users
- [ ] Landmark elements (<main>, <nav>, <aside>)
- [ ] Heading hierarchy is logical
- [ ] Links are distinguishable from text
- [ ] Form validation is helpful and clear
- [ ] Loading states have ARIA live regions

---

## Screen Reader Testing

### Using MacOS VoiceOver
1. Enable: System Preferences > Accessibility > VoiceOver
2. Keyboard: Control + Option (VO)
3. Commands:
   - VO + Right Arrow: next element
   - VO + Left Arrow: previous element
   - VO + Space: activate
   - VO + U: rotor (navigate by headings)

### Using Windows Narrator
1. Enable: Settings > Accessibility > Narrator
2. Keyboard: Windows + Control + Enter
3. Read entire page: Narrator Key + Down Arrow

### Testing Checklist
- [ ] All text content is readable
- [ ] Images have descriptive alt text
- [ ] Form labels are announced
- [ ] Buttons are announced with purpose
- [ ] List structure is announced
- [ ] Focus order is logical

---

## Color Contrast Testing

Use Axe DevTools or WCAG Contrast Checker browser extension.

### Minimum Standards
- Normal text: 4.5:1 contrast ratio (WCAG AA)
- Large text (18pt+): 3:1 contrast ratio
- UI components: 3:1 contrast ratio

### Test These Combinations
- [ ] White text on dark backgrounds
- [ ] Slate-300 on slate-900/50
- [ ] Primary blue on dark backgrounds
- [ ] Error red on dark backgrounds
- [ ] Disabled text (opacity-50)

### Current Verified Combinations
✓ `text-white` on `bg-slate-950`
✓ `text-slate-300` on `bg-slate-900/50`
✓ `text-primary` (#3B82F6) on dark
✓ `text-rose-500` on dark
✓ `text-slate-600` on light backgrounds

---

## Reduced Motion Testing

### iOS/MacOS
1. Settings > Accessibility > Display & Text Size
2. Toggle: Reduce motion
3. Test the app - animations should stop or be minimal

### Windows
1. Settings > Accessibility > Display
2. Toggle: Show animations

### CSS Check
All animations should respect `prefers-reduced-motion`:

```css
@media (prefers-reduced-motion: reduce) {
  * {
    animation: none !important;
    transition: none !important;
  }
}
```

**Current Status:** NOT YET IMPLEMENTED - add this to `globals.css`

---

## Light Mode Contrast

If light mode is ever implemented, verify:

- [ ] All text meets 4.5:1 contrast on light backgrounds
- [ ] Interactive elements are clearly visible
- [ ] Focus rings are visible on light backgrounds
- [ ] No white text on light backgrounds
- [ ] Borders are visible (not white on white)

---

## Mobile Accessibility

### Touch Target Size
All clickable elements must be at least 44×44px.

**Check:**
- [ ] BottomNav buttons: 44px min height
- [ ] Scanner buttons: all 44×44px or larger
- [ ] Modal buttons: all 44×44px or larger
- [ ] Form inputs: 44px min height

### Touch Accuracy
Test on real mobile devices:
- [ ] No overlapping touch targets
- [ ] Buttons are easily tappable
- [ ] Enough spacing between actions
- [ ] Mobile keyboard doesn't hide critical content

---

## Tools for Testing

### Browser Extensions
- **Axe DevTools** (Chrome, Firefox, Edge)
  - Automated accessibility scanning
  - Issue severity ranking
  - Best practices
  
- **WAVE** (Chrome, Firefox)
  - Visual feedback overlay
  - Color contrast checker
  - Form field analysis

- **Lighthouse** (Chrome DevTools)
  - Built-in audits
  - Performance + accessibility
  - Run: DevTools > Lighthouse

### Command Line
```bash
# ESLint with jsx-a11y plugin (if configured)
npm run lint -- --plugin jsx-a11y

# Axe-core CLI
npx @axe-core/cli https://your-site.com
```

### Manual Testing
- Keyboard only navigation (no mouse)
- Screen reader (NVDA, JAWS, VoiceOver)
- High contrast mode
- Zoom to 200%
- Mobile device testing

---

## Reporting Issues

When you find an accessibility issue, report it with:

1. **Component:** Which component is affected?
2. **Issue Type:** keyboard, screen reader, contrast, focus, etc.
3. **Steps to Reproduce:** How to find the problem
4. **Expected:** What should happen?
5. **Actual:** What currently happens?
6. **Severity:** P0 (blocker), P1 (major), P2 (minor), P3 (enhancement)

Example:
```
Component: ItemComparisonModal
Issue Type: Keyboard navigation
Steps: Open modal, press Tab, try to reach "Skip" button
Expected: "Skip" button should be reachable via Tab
Actual: Focus skips past the button
Severity: P1
```

---

## Compliance Goals

This project aims for **WCAG 2.1 Level AA** compliance:

| Criterion | Status | Details |
|-----------|--------|---------|
| 1.4.3 Contrast (Minimum) | ✓ | 4.5:1 for normal text |
| 2.1.1 Keyboard | ✓ | All functionality keyboard accessible |
| 2.4.3 Focus Order | ✓ | Logical, follows DOM order |
| 2.4.7 Focus Visible | ✓ | Visible focus ring on all elements |
| 3.2.4 Consistent Identification | ✓ | Consistent button/link patterns |
| 4.1.2 Name, Role, Value | ✓ | Proper ARIA and semantics |
| 4.1.3 Status Messages | ⚠ | Partial - toast notifications |

---

## Next Steps

1. **Implement prefers-reduced-motion** in `globals.css`
2. **Add ARIA live regions** for async updates (toast messages)
3. **Test with real users** (keyboard only, screen reader users)
4. **Run Lighthouse audits** monthly
5. **Update this guide** as standards evolve

---

## Resources

- [WCAG 2.1 Guidelines](https://www.w3.org/WAI/WCAG21/quickref/)
- [ARIA Authoring Practices](https://www.w3.org/WAI/ARIA/apg/)
- [MDN Accessibility](https://developer.mozilla.org/en-US/docs/Web/Accessibility)
- [Axe DevTools Documentation](https://www.deque.com/axe/devtools/)