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:

/* 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

/* 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:

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