reviewed epic 9 stories

2025-12-21 13:26:15 +02:00
parent 261a528578
commit 8431194c9a
11 changed files with 1651 additions and 251 deletions
@@ -3,6 +3,18 @@
 ## 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**,
@@ -10,10 +22,12 @@ So that **I can use it regardless of my abilities**.

 ## Acceptance Criteria

-### Color Contrast
- [ ] Body text: 4.5:1 minimum
- [ ] Large text: 3:1 minimum
- [ ] UI elements: 3:1 minimum
+### 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)
@@ -34,8 +48,27 @@ So that **I can use it regardless of my abilities**.
 - [ ] 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 {
@@ -80,10 +113,40 @@ So that **I can use it regardless of my abilities**.
 ```

 ### Testing Tools
- axe DevTools
- WAVE
- Lighthouse
- Screen reader (VoiceOver/NVDA)
+- **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
@@ -95,5 +158,17 @@ So that **I can use it regardless of my abilities**.
 - [ ] 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