libra/docs/stories/story-9.10-accessibility-compliance.md

# Story 9.10: Accessibility Compliance

## Epic Reference
**Epic 9:** Design & Branding Implementation

## Dependencies
- **Story 9.1:** Color System Implementation (provides `gold`, `navy` Tailwind color classes used in focus styles)
- **Stories 9.4-9.7:** Component Styling (all styled components require accessibility review)
- **Story 9.8:** RTL/LTR Layout (accessibility must work in both directions)

## Scope
This story applies to **all pages and components**:
- Public pages (landing, posts, booking)
- Authentication pages (login, register, password reset)
- Client dashboard and all client-facing views
- Admin dashboard and all admin-facing views

## User Story
As a **user with disabilities**,
I want **the platform to be accessible**,
So that **I can use it regardless of my abilities**.

## Acceptance Criteria

### Color Contrast (WCAG AA Standard)
- [ ] Body text: 4.5:1 minimum contrast ratio
- [ ] Large text (18px+ bold or 24px+ regular): 3:1 minimum
- [ ] UI elements (buttons, form borders, icons): 3:1 minimum
- [ ] Verify gold (#D4AF37) on navy (#0A1F44) meets requirements
- [ ] Verify text colors on cream (#F9F7F4) backgrounds

### Focus Indicators
- [ ] Visible focus outline (gold)
- [ ] Not just color change

### Keyboard Navigation
- [ ] All interactive elements reachable
- [ ] Logical tab order
- [ ] Skip to main content link

### Screen Readers
- [ ] Proper heading hierarchy (h1 > h2 > h3)
- [ ] Alt text for images
- [ ] ARIA labels where needed
- [ ] Form labels associated

### Motion
- [ ] Respect prefers-reduced-motion
- [ ] No auto-playing animations

## Files to Modify

| File | Changes |
|------|---------|
| `resources/css/app.css` | Add global focus styles and reduced-motion media query |
| `resources/views/components/layouts/app.blade.php` | Add skip link and `<main id="main-content">` landmark |
| `resources/views/components/layouts/guest.blade.php` | Add skip link and main landmark for auth pages |
| `lang/en/accessibility.php` | Add translation: `'skip_to_content' => 'Skip to main content'` |
| `lang/ar/accessibility.php` | Add translation: `'skip_to_content' => 'تخطي إلى المحتوى الرئيسي'` |

### Components to Audit
- All Flux UI form components (verify label associations)
- All image usages (verify alt text present)
- Navigation components (verify logical tab order)
- Modal components (verify focus trapping)

## Technical Notes

### Global Accessibility Styles
Add to `resources/css/app.css`:

```css
/* Focus styles */
:focus-visible {
  @apply outline-2 outline-offset-2 outline-gold;
}

/* Skip link */
.skip-link {
  @apply sr-only focus:not-sr-only focus:absolute focus:top-4 focus:start-4
         focus:bg-gold focus:text-navy focus:px-4 focus:py-2 focus:rounded focus:z-50;
}

/* Reduced motion */
@media (prefers-reduced-motion: reduce) {
  *,
  *::before,
  *::after {
    animation-duration: 0.01ms !important;
    animation-iteration-count: 1 !important;
    transition-duration: 0.01ms !important;
  }
}
```

```blade
<!-- Skip link -->
<a href="#main-content" class="skip-link">
    {{ __('accessibility.skip_to_content') }}
</a>

<!-- Main content landmark -->
<main id="main-content" role="main">
    {{ $slot }}
</main>

<!-- Proper labeling -->
<label for="email">{{ __('form.email') }}</label>
<input id="email" type="email" aria-required="true" />

<!-- Image with alt text -->
<img src="{{ asset('images/logo.svg') }}" alt="{{ __('Libra Law Firm Logo') }}" />
```

### Testing Tools
- **axe DevTools** - Browser extension for automated accessibility testing
- **WAVE** - Web accessibility evaluation tool
- **Lighthouse** - Chrome DevTools accessibility audit (target: >90 score)
- **Screen reader** - VoiceOver (macOS) or NVDA (Windows) for manual testing

### Test Scenarios
1. **Keyboard Navigation Test:**
   - Tab through entire booking form without mouse
   - Verify all buttons, links, and inputs are reachable
   - Confirm focus order is logical (top-to-bottom, start-to-end)

2. **Skip Link Test:**
   - Press Tab on page load
   - Skip link should appear and be focusable
   - Activating skip link jumps to main content

3. **Screen Reader Test:**
   - Navigate landing page with VoiceOver/NVDA
   - Verify headings announced in correct order (h1 → h2 → h3)
   - Verify form labels read correctly
   - Verify images have meaningful alt text

4. **Color Contrast Test:**
   - Run Lighthouse on: `/`, `/login`, `/dashboard`, `/admin`
   - All pages must score >90 accessibility

5. **Reduced Motion Test:**
   - Enable "Reduce motion" in OS settings
   - Verify no animations play on page load or interactions

6. **RTL Accessibility Test:**
   - Switch to Arabic language
   - Verify skip link position (start = right in RTL)
   - Verify tab order follows RTL reading direction

## Definition of Done
- [ ] Color contrast passes
- [ ] Focus indicators visible
- [ ] Keyboard navigation works
- [ ] Screen reader friendly
- [ ] Reduced motion respected
- [ ] Skip link works
- [ ] Lighthouse accessibility > 90
- [ ] Tests pass

## References
- **PRD Section 7.1:** Brand Identity - Accessibility Compliance subsection
- **Epic 9:** `docs/epics/epic-9-design-branding.md` - Story 9.10 acceptance criteria
- **Story 9.1:** Color values defined (gold: #D4AF37, navy: #0A1F44)
- **WCAG 2.1 AA Guidelines:** https://www.w3.org/WAI/WCAG21/quickref/

## Estimation
**Complexity:** Medium | **Effort:** 4-5 hours

## Notes for Developer
- Flux UI components generally have good accessibility built-in; focus on custom components
- If Flux components don't meet contrast requirements, create custom CSS overrides
- The `!important` in reduced-motion CSS is intentional to override all animations
- Use `focus:start-4` (not `focus:left-4`) for RTL compatibility