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 (, ,
  )
• 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:

@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

# 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
• ARIA Authoring Practices
• MDN Accessibility
• Axe DevTools Documentation