2.5: Responsive Layout & Cross-Browser Compatibility

[steilerDev]

User Story

As a user, I want the application to work well on my tablet and phone as well as my desktop, so that I can check project progress from the construction site.

Parent Epic

EPIC-02: Application Shell & Infrastructure (#2)

Priority

Must Have

Dependencies

• Story 2.4: Client-Side Routing & Application Shell Layout (2.4: Client-Side Routing & Application Shell Layout #27)

Acceptance Criteria

• 1. The application shell layout adapts to three breakpoints: mobile (<768px), tablet (768-1024px), desktop (>1024px)
• 2. On mobile, the sidebar navigation collapses into a hamburger menu
• 3. On tablet, the sidebar can be toggled open/closed
• 4. On desktop, the sidebar is always visible
• 5. Touch targets (buttons, links) are at least 44x44px on mobile/tablet
• 6. Text remains readable without horizontal scrolling on all breakpoints
• 7. The app renders correctly in the latest versions of Chrome, Firefox, Safari, and Edge

Notes

• Requirements Section 3.2 specifies responsive design with desktop and tablet support, mobile-friendly
• Requirements Section 3.4 specifies touch-friendly interface on mobile devices
• CSS Modules are used for styling -- breakpoint mixins or CSS custom properties should establish the responsive foundation
• This story builds on the shell layout from Story 2.4 and makes it responsive

[steilerDev]

[uat-validator]

UAT Scenarios: Responsive Layout & Cross-Browser Compatibility (Issue #29)

Preconditions

• Application is built and running
• Story 2.4: Client-Side Routing & Application Shell Layout #27 (Client-Side Routing & Application Shell Layout) is complete
• Testing browsers installed: Chrome, Firefox, Safari (macOS/iOS), Edge
• Browser DevTools or responsive design mode available for viewport resizing

---

Scenario 1: Desktop Layout Shows Persistent Sidebar

Acceptance Criteria: 1, 4

• Given: User opens the application in a desktop browser
• When: User resizes the browser window to 1280px width (desktop breakpoint >1024px)
• Then:
  • The sidebar is fully visible on the left side of the screen
  • The sidebar does NOT have a close button or toggle icon
  • The main content area occupies the remaining horizontal space
  • Navigation links are fully visible with labels
• Verification Method: Manual

---

Scenario 2: Desktop Layout - Sidebar Remains Visible During Navigation

Acceptance Criteria: 4

• Given: User is on a desktop viewport (1280px width)
• When: User navigates from Dashboard → Work Items → Budget → Timeline
• Then:
  • The sidebar remains fully visible throughout all page transitions
  • No collapse/expand animation occurs
• Verification Method: Manual

---

Scenario 3: Tablet Layout Allows Sidebar Toggle

Acceptance Criteria: 1, 3

• Given: User opens the application
• When: User resizes the browser window to 900px width (tablet breakpoint 768-1024px)
• Then:
  • A hamburger menu icon (☰) or toggle button is visible in the header or top-left corner
  • The sidebar may be visible by default or collapsed (either is acceptable)
  • User can click the toggle button to open/close the sidebar
• Verification Method: Manual

---

Scenario 4: Tablet Layout - Toggle Button Opens Sidebar

Acceptance Criteria: 3

• Given: User is on a tablet viewport (900px width) with the sidebar closed
• When: User clicks the hamburger/toggle button
• Then:
  • The sidebar slides in or appears with an animation
  • The sidebar overlays or pushes the main content area
  • Navigation links are fully visible
  • The toggle button changes icon (to ✕ or ☰ depending on design)
• Verification Method: Manual

---

Scenario 5: Tablet Layout - Toggle Button Closes Sidebar

Acceptance Criteria: 3

• Given: User is on a tablet viewport (900px width) with the sidebar open
• When: User clicks the toggle button again
• Then:
  • The sidebar slides out or disappears with an animation
  • The main content area expands to full width
• Verification Method: Manual

---

Scenario 6: Tablet Layout - Clicking Outside Sidebar Closes It (Optional Enhancement)

Acceptance Criteria: 3

• Given: User is on a tablet viewport with the sidebar open (overlay style)
• When: User clicks on the main content area (outside the sidebar)
• Then:
  • The sidebar closes automatically
  • The main content area is fully interactive
• Verification Method: Manual
• Note: This is a nice-to-have; explicit toggle button is sufficient.

---

Scenario 7: Mobile Layout Shows Hamburger Menu

Acceptance Criteria: 1, 2

• Given: User opens the application on a mobile device or resizes browser to 375px width (mobile breakpoint <768px)
• When: User observes the initial page load
• Then:
  • The sidebar is NOT visible by default
  • A hamburger menu icon (☰) is prominently displayed in the header or top-left corner
  • The main content area occupies full width
• Verification Method: Manual

---

Scenario 8: Mobile Layout - Opening Hamburger Menu Shows Full-Screen Navigation

Acceptance Criteria: 2

• Given: User is on a mobile viewport (375px width) with the sidebar closed
• When: User taps the hamburger menu icon
• Then:
  • The navigation sidebar slides in from the left (or appears as a full-screen overlay)
  • All navigation links (Dashboard, Work Items, Budget, Timeline, Household Items, Documents) are visible
  • The hamburger icon changes to a close icon (✕)
• Verification Method: Manual

---

Scenario 9: Mobile Layout - Closing Navigation Returns to Content

Acceptance Criteria: 2

• Given: User has opened the mobile navigation menu
• When: User taps the close icon (✕)
• Then:
  • The navigation menu slides out or disappears
  • The main content area is fully visible
  • The close icon changes back to the hamburger icon (☰)
• Verification Method: Manual

---

Scenario 10: Mobile Layout - Selecting Nav Item Closes Menu

Acceptance Criteria: 2

• Given: User has opened the mobile navigation menu
• When: User taps "Work Items" in the navigation
• Then:
  • The Work Items page loads
  • The navigation menu automatically closes
  • The main content area is fully visible
• Verification Method: Manual

---

Scenario 11: Touch Targets Are Adequately Sized on Mobile

Acceptance Criteria: 5

• Given: User is on a mobile viewport (375px width)
• When: User opens the navigation menu and observes the navigation links
• Then:
  • Each navigation link is at least 44px tall
  • Each link has adequate horizontal spacing (minimum 44px width or full-width with padding)
  • User can easily tap each link without accidentally hitting adjacent links
• Verification Method: Manual (measure in DevTools)

---

Scenario 12: Touch Targets Are Adequately Sized on Tablet

Acceptance Criteria: 5

• Given: User is on a tablet viewport (900px width)
• When: User opens the sidebar and observes navigation links and the toggle button
• Then:
  • The toggle button is at least 44x44px
  • Navigation links are at least 44px tall
• Verification Method: Manual (measure in DevTools)

---

Scenario 13: No Horizontal Scrolling on Mobile

Acceptance Criteria: 6

• Given: User is on a mobile viewport (375px width)
• When: User navigates to each page (Dashboard, Work Items, Budget, Timeline, Household Items, Documents)
• Then:
  • No horizontal scrollbar appears
  • All text and content fit within the 375px width
  • Text wraps or scales appropriately
• Verification Method: Manual

---

Scenario 14: No Horizontal Scrolling on Tablet

Acceptance Criteria: 6

• Given: User is on a tablet viewport (900px width)
• When: User navigates through all pages
• Then:
  • No horizontal scrollbar appears
  • Content adapts to the viewport width
• Verification Method: Manual

---

Scenario 15: No Horizontal Scrolling on Desktop

Acceptance Criteria: 6

• Given: User is on a desktop viewport (1280px width)
• When: User navigates through all pages
• Then:
  • No unintended horizontal scrollbar appears
  • Layout is stable and fits the viewport
• Verification Method: Manual

---

Scenario 16: Application Renders Correctly in Chrome

Acceptance Criteria: 7

• Given: User opens the application in the latest version of Google Chrome (desktop or mobile)
• When: User navigates through all pages and interacts with navigation
• Then:
  • All styles render correctly (no missing styles or broken layout)
  • Navigation animations are smooth
  • No console errors appear
• Verification Method: Manual

---

Scenario 17: Application Renders Correctly in Firefox

Acceptance Criteria: 7

• Given: User opens the application in the latest version of Mozilla Firefox (desktop or mobile)
• When: User navigates through all pages and interacts with navigation
• Then:
  • All styles render correctly
  • Layout is identical to Chrome (within acceptable browser differences)
  • No console errors appear
• Verification Method: Manual

---

Scenario 18: Application Renders Correctly in Safari

Acceptance Criteria: 7

• Given: User opens the application in the latest version of Safari (macOS or iOS)
• When: User navigates through all pages and interacts with navigation
• Then:
  • All styles render correctly
  • Touch interactions work on iOS (tap to open/close menu, tap links)
  • No console errors appear
• Verification Method: Manual

---

Scenario 19: Application Renders Correctly in Edge

Acceptance Criteria: 7

• Given: User opens the application in the latest version of Microsoft Edge
• When: User navigates through all pages and interacts with navigation
• Then:
  • All styles render correctly
  • Layout matches Chrome/Firefox behavior
  • No console errors appear
• Verification Method: Manual

---

Edge Cases

Edge Case 1: Resizing from Desktop to Mobile Mid-Session

• Given: User is on a desktop viewport (1280px) with the sidebar visible
• When: User resizes the browser window to 375px width (mobile)
• Then:
  • The sidebar automatically collapses into a hamburger menu
  • The layout adapts smoothly without breaking
  • User can open the hamburger menu to access navigation
• Verification Method: Manual

Edge Case 2: Resizing from Mobile to Desktop Mid-Session

• Given: User is on a mobile viewport (375px) with the navigation menu closed
• When: User resizes the browser window to 1280px width (desktop)
• Then:
  • The sidebar automatically expands and becomes persistent
  • The hamburger menu icon disappears
  • The layout adapts smoothly
• Verification Method: Manual

Edge Case 3: Landscape Orientation on Mobile (e.g., 667x375px)

• Given: User rotates a mobile device to landscape orientation (e.g., iPhone in landscape)
• When: User views the application
• Then:
  • The layout remains functional
  • The hamburger menu is still accessible
  • Content fits without horizontal scrolling
• Verification Method: Manual

Edge Case 4: Very Small Mobile Viewport (320px)

• Given: User resizes the browser to 320px width (iPhone SE size)
• When: User navigates through the application
• Then:
  • The layout remains functional
  • Text is readable (minimum 14-16px font size)
  • Touch targets are still at least 44px (may stack vertically if needed)
  • No horizontal scrolling occurs
• Verification Method: Manual

Edge Case 5: Very Large Desktop Viewport (2560px)

• Given: User opens the application on a large desktop monitor (2560px width)
• When: User observes the layout
• Then:
  • The sidebar remains a reasonable width (not excessively wide)
  • The main content area is centered or has a max-width (optional but recommended)
  • The layout does not look broken or overly stretched
• Verification Method: Manual

Edge Case 6: Tablet Viewport at Exact Breakpoint (768px)

• Given: User resizes the browser to exactly 768px width (breakpoint boundary)
• When: User observes the layout
• Then:
  • The layout applies either mobile or tablet styles consistently
  • No layout shift or flicker occurs at the breakpoint
• Verification Method: Manual

Edge Case 7: Browser Zoom In (150%)

• Given: User is on a desktop viewport
• When: User zooms in to 150% (Ctrl/Cmd +)
• Then:
  • The layout remains functional and adapts (may switch to tablet or mobile breakpoint)
  • Text remains readable
  • Touch targets scale appropriately
• Verification Method: Manual

Edge Case 8: Browser Zoom Out (75%)

• Given: User is on a desktop viewport
• When: User zooms out to 75% (Ctrl/Cmd -)
• Then:
  • The layout remains functional
  • Text is still legible (not too small)
• Verification Method: Manual

---

Automated Test Mapping

• Playwright E2E tests: e2e/responsive/layout.spec.ts

  • Test sidebar visibility at desktop, tablet, and mobile breakpoints
  • Test toggle button behavior on tablet and mobile
  • Test navigation menu open/close on mobile
  • Test cross-browser compatibility (Playwright supports Chromium, Firefox, WebKit)
  • Use page.setViewportSize() to simulate different screen sizes

• Visual Regression Tests (optional): Capture screenshots at each breakpoint and compare against baseline

---

Notes for Developers

• Use CSS custom properties or mixins for breakpoints (e.g., --breakpoint-tablet: 768px)
• Prefer min-width media queries (mobile-first approach) for maintainability
• Use touch-action: manipulation on touch targets to eliminate 300ms tap delay on mobile
• Ensure focus indicators remain visible at all breakpoints (keyboard accessibility)
• Consider using prefers-reduced-motion media query to disable animations for users who prefer reduced motion
• Test on real devices (iOS, Android) if possible, in addition to browser DevTools emulation

[steilerDev]

[qa-integration-tester]

QA Review: UAT Scenarios for Story #29 (Responsive Layout & Cross-Browser Compatibility)

Overall Assessment

The UAT scenarios are thorough and well-organized. Most responsive behavior is automatable with Playwright. Cross-browser testing is fully supported. Edge cases are comprehensive.

---

Automation Feasibility

✅ Fully Automatable (Playwright E2E)

• Scenarios 1-15: Desktop/tablet/mobile layout behaviors, sidebar toggle, touch targets, horizontal scrolling checks
• Scenarios 16-19: Cross-browser testing (Playwright supports Chromium, Firefox, WebKit/Safari)
• Edge Cases 1-8: Viewport resizing, breakpoints, zoom levels

Tool: Playwright with page.setViewportSize({ width: 375, height: 812 }), browserType.launch() for cross-browser

⚠️ Partially Automatable

• Scenario 11-12 (Touch target sizing): Playwright can measure element dimensions via element.boundingBox(). Recommendation: Assert height >= 44 && width >= 44 for all interactive elements.

• Scenarios 6 (Clicking outside sidebar closes it): Marked as "nice-to-have." Recommendation: If implemented, test with page.click('.main-content-area') and verify sidebar closes.

❌ Manual Validation Required

• Edge Case 7-8 (Browser zoom): Zoom testing is complex in automated tests. Recommendation: Mark as manual validation or skip (zoom changes viewport size, which we already test).

• Real device testing: Playwright runs in emulated environments. Recommendation: Keep "Test on real devices" note in UAT scenarios, but mark as manual validation.

---

Testability Gaps

1. "Smooth animation" assertions: Scenarios 4-5 mention animations but don't specify how to verify "smoothness." Recommendation: Skip animation quality checks (subjective). Test functional outcome only (sidebar opens/closes).

2. "No console errors": This assertion appears in many scenarios but is never explicitly checked. Recommendation: Add to every Playwright test via page.on('console', msg => { if (msg.type() === 'error') throw new Error() }).

3. Touch interactions on mobile: Scenarios 8-10 test "tapping" on mobile. Playwright supports touch events via page.tap(). Recommendation: Use page.tap() instead of page.click() for mobile viewport tests.

4. Focus indicators at all breakpoints: Scenario 19 notes this, but there's no dedicated test. Recommendation: Add scenario verifying keyboard focus works at mobile, tablet, and desktop viewports.

5. "Layout is identical to Chrome": Scenario 17-19 assert "identical" layout across browsers. This is unrealistic (browsers have minor rendering differences). Recommendation: Change to "Layout is functional and visually consistent" (allow minor pixel differences).

---

Missing Scenarios

1. Portrait vs. landscape orientation on tablet: Edge Case 3 covers mobile landscape, but tablet landscape (e.g., iPad in landscape) is not tested. Recommendation: Add scenario for tablet landscape viewport (e.g., 1024x768 flipped to 768x1024).

2. Sidebar state persistence: If a user opens the sidebar on mobile, navigates to another page, should the sidebar remain open or auto-close? Recommendation: Add scenario clarifying expected behavior (likely auto-close on navigation).

3. Reduced motion preference: The notes mention prefers-reduced-motion, but no scenario tests it. Recommendation: Add scenario: "Given user has prefers-reduced-motion enabled, When sidebar toggles, Then no animation plays (instant open/close)."

4. Dark mode / high contrast (future): No scenarios for color scheme preferences. Recommendation: Defer to future story (EPIC-01 may include theming).

5. Print layout: What happens if a user prints a page? Should the sidebar be hidden? Recommendation: Add scenario or defer to future story.

---

Coverage Mapping

Scenario	Test Type	Tool
1-15	E2E (viewport resizing)	Playwright
16-19	E2E (cross-browser)	Playwright (Chromium, Firefox, WebKit)
Edge 1-6	E2E (viewport changes)	Playwright
Edge 7-8	Manual validation	Browser DevTools

Component tests (optional, using Jest + @testing-library/react):

• Test Sidebar component renders correctly at different viewport widths (mock window.innerWidth)
• Test toggle button click handler
• Test useMediaQuery hook (if implemented)

---

Test Infrastructure Needs

Already Available

• Playwright (viewport emulation, cross-browser testing)

Recommended Additions

• Playwright mobile emulation: Use devices from @playwright/test to test iPhone 12, Galaxy S9, iPad, etc.

• Visual regression testing (optional): Use @playwright/test screenshot comparison to detect layout shifts.

• Accessibility testing: Use @axe-core/playwright to verify touch target sizing and focus indicators.

Playwright Configuration

• Define viewport presets: mobile (375x667), tablet (768x1024), desktop (1280x800)
• Run tests against Chromium, Firefox, WebKit in CI

---

Recommendations

1. Add concrete assertions for "smooth animations": Skip animation quality checks; test only functional outcome (sidebar opens/closes).
2. Clarify cross-browser "identical" assertion: Change to "functional and visually consistent" (allow minor pixel differences).
3. Add missing scenarios: tablet landscape orientation, sidebar state persistence during navigation, prefers-reduced-motion.
4. Use Playwright's mobile emulation: Test with real device profiles (devices['iPhone 12']) instead of arbitrary viewport sizes.
5. Mark browser zoom tests as manual validation: Zoom is hard to automate reliably.
6. Add console error monitoring: Use page.on('console') to fail tests if JS errors occur.
7. Use page.tap() for mobile scenarios: More accurate than page.click() for touch events.

---

Approved for Development?

Almost. I recommend the uat-validator incorporate these changes:

• Add 3 missing scenarios (tablet landscape, sidebar persistence, prefers-reduced-motion)
• Clarify "identical layout" assertion (change to "functional and consistent")
• Remove animation "smoothness" checks (subjective, not automatable)
• Mark browser zoom tests as manual validation

Once updated, these scenarios will be fully testable and automatable.

---

Next Steps:

1. uat-validator updates scenarios based on this feedback
2. User approves updated UAT plan
3. frontend-developer implements feature
4. qa-integration-tester (me) writes Playwright tests covering all approved scenarios