libra/docs/stories/story-9.9-responsive-design-implementation.md

# Story 9.9: Responsive Design Implementation

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

## Dependencies
- **Story 9.1:** Color System Implementation (colors must be defined)
- **Story 9.2:** Typography System (fonts and hierarchy must be in place)
- **Story 9.4-9.6:** Component Styling (buttons, forms, cards must be styled)
- **Story 9.7:** Navigation & Footer Styling (navigation responsive behavior)
- **Story 9.8:** RTL/LTR Layout Perfection (responsive must work in both directions)

## References
- **PRD Section 7.4:** Responsive Breakpoints (`docs/prd.md#74-responsive-breakpoints`)
- **PRD Section 5.1:** Landing page responsive requirements
- **PRD Section 5.7-5.8:** Dashboard responsive requirements (admin/client)
- **Epic 9:** Full acceptance criteria (`docs/epics/epic-9-design-branding.md`)

## User Story
As a **user**,
I want **the platform to work perfectly on all device sizes**,
So that **I can use it on my phone, tablet, or desktop**.

## Scope

### Pages/Components Requiring Responsive Work
1. **Public Pages:**
   - Landing page (hero, about sections, booking form)
   - Posts/blog listing and detail pages
   - Login page
   - Terms of Service / Privacy Policy pages

2. **Client Dashboard:**
   - Overview/stats cards
   - Consultations list and detail views
   - Case timelines view
   - Booking form with calendar
   - Profile view

3. **Admin Dashboard:**
   - Statistics cards and charts
   - User management tables
   - Booking management views
   - Timeline management
   - Posts management
   - Working hours configuration
   - Settings pages

4. **Shared Components:**
   - Navigation bar (already handled in 9.7, verify integration)
   - Footer
   - Modal dialogs
   - Form components
   - Tables
   - Cards

## Acceptance Criteria

### Breakpoints (per PRD Section 7.4)
- [ ] Mobile: < 576px (single column, stacked layouts)
- [ ] Tablet: 576px - 991px (two columns where appropriate)
- [ ] Desktop: 992px - 1199px (full layouts with sidebars)
- [ ] Large Desktop: >= 1200px (max-width container: 1200px)

### Mobile Optimizations (< 576px)
- [ ] Touch-friendly targets minimum 44px height/width for all interactive elements
- [ ] Font sizes remain readable (minimum 16px for body text to prevent iOS zoom)
- [ ] Single column layouts for all content sections
- [ ] Collapsible/accordion sections for long content
- [ ] Navigation collapses to hamburger menu
- [ ] Forms stack labels above inputs
- [ ] Cards display full-width

### Tablet Optimizations (576px - 991px)
- [ ] Two-column grid layouts where appropriate (dashboard stats, post listings)
- [ ] Sidebar collapsible via toggle (not permanently visible)
- [ ] Tables may show reduced columns or scroll horizontally
- [ ] Calendar shows week view or scrollable month

### Desktop Optimizations (992px+)
- [ ] Full layouts with persistent sidebars
- [ ] Multi-column grids (3-4 columns for dashboard stats)
- [ ] Tables show all columns
- [ ] Calendar shows full month view
- [ ] Max container width: 1200px centered

### Specific Feature Requirements
- [ ] **Forms:** All forms (booking, login, user management) fully usable on mobile with proper input sizing
- [ ] **Calendar:** Booking calendar functional on mobile (touch-friendly date selection, scrollable)
- [ ] **Tables:** All data tables have horizontal scroll wrapper, pinned first column if needed
- [ ] **No horizontal scroll:** Page-level horizontal scroll must never occur on any viewport
- [ ] **Modals:** Modal dialogs responsive (full-screen on mobile, centered on desktop)
- [ ] **Charts:** Dashboard charts resize appropriately or stack on mobile

### RTL Considerations
- [ ] All responsive layouts tested in both LTR (English) and RTL (Arabic)
- [ ] Sidebar collapses from correct side (start-0 not left-0)
- [ ] Horizontal scroll direction correct for RTL

## Technical Notes

### Technology Stack
- **Tailwind CSS 4:** Using CSS-first configuration with `@theme` directive
- **Flux UI Free:** Leverage built-in responsive behavior for available components
- **Alpine.js:** For mobile menu toggles and collapsible sections (included with Livewire)

### Key Files to Modify

```
resources/css/app.css                    # Responsive utility classes
resources/views/components/layouts/      # Layout templates
  - app.blade.php                        # Main layout wrapper
  - guest.blade.php                      # Public pages layout
resources/views/livewire/
  - Various dashboard components         # Component-specific responsive styles
resources/views/components/
  - card.blade.php                       # Card responsive variants
  - table.blade.php                      # Table wrapper component
```

### Tailwind 4 Responsive Approach

Use mobile-first with Tailwind's responsive prefixes:

```css
/* In resources/css/app.css - add to @theme if needed */

/* Mobile-first grid example */
.dashboard-grid {
  @apply grid gap-4;
  @apply grid-cols-1;      /* Mobile: single column */
  @apply sm:grid-cols-2;   /* Tablet: 2 columns */
  @apply lg:grid-cols-3;   /* Desktop: 3 columns */
  @apply xl:grid-cols-4;   /* Large: 4 columns */
}

/* Touch-friendly targets */
.touch-target {
  @apply min-h-[44px] min-w-[44px];
}

/* Responsive table wrapper */
.table-responsive {
  @apply overflow-x-auto -mx-4 px-4;
  @apply sm:mx-0 sm:px-0;  /* Remove negative margin on larger screens */
}

/* Collapsible sidebar - uses logical properties for RTL */
@media (max-width: 991px) {
  .sidebar {
    @apply fixed inset-y-0 start-0 w-64;
    @apply transform -translate-x-full transition-transform duration-200;
    @apply z-40 bg-navy-900;
  }
  .sidebar.open {
    @apply translate-x-0;
  }
  /* RTL: sidebar comes from right */
  [dir="rtl"] .sidebar {
    @apply end-0 start-auto translate-x-full;
  }
  [dir="rtl"] .sidebar.open {
    @apply translate-x-0;
  }
}
```

### Flux UI Responsive Behavior
- Flux UI components have built-in responsive behavior
- `<flux:modal>` automatically handles responsive sizing
- `<flux:dropdown>` positions correctly on mobile
- Override with Tailwind classes when Flux defaults insufficient

### Preventing Horizontal Scroll
```css
/* Add to base styles */
html, body {
  @apply overflow-x-hidden;
}

/* Ensure images/media don't overflow */
img, video, iframe {
  @apply max-w-full h-auto;
}
```

## Testing Strategy

### Testing Approach
1. **Browser DevTools:** Primary method for rapid iteration
2. **Real Devices:** Final verification on actual phones/tablets
3. **Both Languages:** Test each breakpoint in English (LTR) AND Arabic (RTL)

### Test Devices/Viewports
| Device | Width | Type |
|--------|-------|------|
| iPhone SE | 375px | Mobile |
| iPhone 14 | 390px | Mobile |
| iPhone 14 Pro Max | 430px | Mobile (large) |
| iPad | 768px | Tablet |
| iPad Pro | 1024px | Tablet (large) |
| Desktop | 1280px | Desktop |
| Large Desktop | 1920px | Large Desktop |

### Key Test Scenarios

**Mobile (375px - English & Arabic):**
- [ ] Navigate from landing page to login
- [ ] Complete full booking flow (select date, fill form, submit)
- [ ] View consultation list and detail
- [ ] View case timeline
- [ ] Open and close mobile navigation menu
- [ ] Submit a form with validation errors
- [ ] Scroll through long table (user list)

**Tablet (768px - English & Arabic):**
- [ ] Toggle sidebar open/closed
- [ ] View dashboard with 2-column stat cards
- [ ] Use calendar in booking flow
- [ ] Manage users in table view

**Desktop (1280px - English & Arabic):**
- [ ] Verify sidebar is persistent
- [ ] Dashboard shows 3-4 column grids
- [ ] Full table columns visible
- [ ] Calendar shows month view

### Automated Testing (Optional)
Consider Pest browser tests for critical flows:
```php
it('booking form works on mobile', function () {
    $this->browse(function ($browser) {
        $browser->resize(375, 667)
            ->visit('/booking')
            ->assertVisible('.booking-form')
            ->type('summary', 'Test consultation')
            ->press('Submit')
            ->assertSee('Request submitted');
    });
});
```

## Definition of Done
- [ ] All pages render correctly at mobile breakpoint (375px) in both LTR and RTL
- [ ] All pages render correctly at tablet breakpoint (768px) in both LTR and RTL
- [ ] All pages render correctly at desktop breakpoint (1280px) in both LTR and RTL
- [ ] No horizontal page scroll at any viewport width from 320px to 1920px
- [ ] All interactive elements meet 44px minimum touch target
- [ ] Booking form with calendar fully functional on mobile
- [ ] All data tables horizontally scrollable without breaking layout
- [ ] Mobile navigation menu opens/closes smoothly
- [ ] Sidebar collapses correctly on tablet (from correct side for RTL)
- [ ] Modal dialogs display correctly on all breakpoints
- [ ] Code formatted with `vendor/bin/pint --dirty`
- [ ] Manual testing completed on at least one real mobile device

## Out of Scope
- Native mobile app development
- Print stylesheets
- Email template responsiveness (covered in separate story)
- Performance optimization (separate concern)

## Estimation
**Complexity:** High | **Effort:** 5-6 hours

## Notes for Developer
- Start with mobile layouts, then progressively enhance for larger screens
- Use Tailwind's responsive prefixes (`sm:`, `md:`, `lg:`, `xl:`) consistently
- Prefer logical properties (`start-`, `end-`, `ms-`, `me-`) over directional (`left-`, `right-`, `ml-`, `mr-`) for RTL compatibility
- Test frequently in browser DevTools during development
- If a component from Flux UI doesn't behave responsively as expected, check Flux docs first before overriding