ca-grow-ops-manager/docs/SPRINT-2.5-MOBILE-FIRST.md

Sprint 2.5: Mobile-First UI Refactor (URGENT)

Date: 2025-12-09
Status: 🔴 Critical Priority
Duration: 2-3 hours
Reason: Cultivation floor workers use tablets/phones - desktop-first won't work

---

🎯 Objective

Refactor the entire frontend to be mobile-first with proper responsive breakpoints for tablet and desktop use.

---

📱 Mobile-First Principles

Target Devices

1. Primary: Tablets (iPad, Android tablets) - 768px-1024px
2. Secondary: Large phones - 375px-767px
3. Tertiary: Desktop - 1024px+

Design Requirements

• Minimum tap target: 44×44px (Apple HIG standard)
• Font sizes: Minimum 16px for body text (prevents zoom on iOS)
• Spacing: Generous padding/margins for fat-finger taps
• Dark mode: Default (easier on eyes in grow rooms)
• Landscape support: Tablets often used in landscape

---

🔧 Implementation Plan

Phase 1: Tailwind Configuration (30 min)

Task 2.5.1: Update Tailwind Config

• Add custom breakpoints optimized for tablets
• Set mobile-first defaults
• Add touch-friendly spacing scale
• Configure larger tap targets

// Proposed breakpoints
screens: {
  'xs': '375px',   // Large phones
  'sm': '640px',   // Small tablets portrait
  'md': '768px',   // Tablets portrait
  'lg': '1024px',  // Tablets landscape / small desktop
  'xl': '1280px',  // Desktop
  '2xl': '1536px', // Large desktop
}

Task 2.5.2: Update Base Styles

• Increase base font size to 16px
• Add touch-friendly button styles
• Increase form input sizes
• Add mobile-optimized spacing utilities

---

Phase 2: Component Refactor (1-1.5 hours)

Task 2.5.3: Update Layout Components

• App.tsx: Mobile-first layout structure
• Navigation: Bottom nav for mobile, side nav for tablet+
• Header: Compact mobile header with hamburger menu
• Cards: Stack on mobile, grid on tablet+

Task 2.5.4: Update Page Components

• LoginPage: Full-screen on mobile, centered card on tablet+
• DashboardPage: Single column mobile, 2-col tablet, 3-col desktop
• RoomsPage: List view mobile, grid tablet+
• BatchesPage: List view mobile, grid tablet+
• TimeclockPage: Large buttons for easy tapping

Task 2.5.5: Update UI Components

• Buttons: Minimum 44px height, generous padding
• Forms: Large inputs (min 44px height)
• Tables: Horizontal scroll on mobile, full on tablet+
• Modals: Full-screen on mobile, centered on tablet+

---

Phase 3: Touch Optimization (30-45 min)

Task 2.5.6: Touch-Friendly Interactions

• Increase all clickable areas to 44×44px minimum
• Add active states for touch feedback
• Remove hover-only interactions
• Add swipe gestures where appropriate

Task 2.5.7: Performance Optimization

• Lazy load images
• Optimize bundle size
• Add loading skeletons
• Test on actual devices

---

📐 Responsive Patterns

Stack to Grid

// Mobile: Stack
// Tablet+: Grid
<div className="flex flex-col md:grid md:grid-cols-2 lg:grid-cols-3 gap-4">

Hide/Show Elements

// Mobile: Hidden
// Tablet+: Visible
<div className="hidden md:block">Desktop content</div>

// Mobile: Visible
// Tablet+: Hidden
<div className="block md:hidden">Mobile content</div>

Responsive Text

<h1 className="text-2xl md:text-3xl lg:text-4xl">

Responsive Spacing

<div className="p-4 md:p-6 lg:p-8">

---

🎨 Mobile-First Component Examples

Button Component

// Minimum 44px height, large text, generous padding
<button className="
  min-h-[44px] 
  px-6 py-3 
  text-base md:text-sm 
  font-medium 
  rounded-lg
  active:scale-95 
  transition-transform
">
  Tap Me
</button>

Card Component

// Full width mobile, constrained tablet+
<div className="
  w-full 
  md:max-w-md 
  p-4 md:p-6 
  rounded-lg 
  shadow-lg
">

Navigation

// Bottom nav mobile, side nav tablet+
<nav className="
  fixed bottom-0 left-0 right-0 
  md:static md:w-64 
  bg-card border-t md:border-r
">

---

✅ Success Criteria

• All pages render correctly on 375px width (iPhone SE)
• All tap targets are minimum 44×44px
• No horizontal scroll on any screen size
• Text is readable without zooming (16px minimum)
• Navigation works on mobile, tablet, and desktop
• Forms are easy to fill on touch devices
• Dark mode works across all breakpoints
• Tested on actual iPad and iPhone

---

🧪 Testing Checklist

Devices to Test

• iPhone SE (375px)
• iPhone 14 Pro (393px)
• iPad Mini (768px)
• iPad Pro (1024px)
• Desktop (1280px+)

Orientations

• Portrait (all devices)
• Landscape (tablets)

Features to Test

• Login flow
• Dashboard navigation
• Room/Batch CRUD
• Timeclock buttons
• Forms (add/edit)
• Modals/dialogs

---

📝 Files to Modify

Configuration

• frontend/tailwind.config.js - Update breakpoints
• frontend/src/index.css - Update base styles

Layout

• frontend/src/App.tsx - Mobile-first layout
• frontend/src/components/Layout.tsx - NEW (if needed)
• frontend/src/components/Navigation.tsx - NEW (mobile nav)

Pages

• frontend/src/pages/LoginPage.tsx
• frontend/src/pages/DashboardPage.tsx
• frontend/src/pages/RoomsPage.tsx
• frontend/src/pages/BatchesPage.tsx
• frontend/src/pages/TimeclockPage.tsx

Components

• frontend/src/components/ui/Button.tsx - Touch-friendly
• frontend/src/components/ui/Input.tsx - Larger inputs
• frontend/src/components/ui/Card.tsx - Responsive

---

🚀 Let's Begin

Priority: This is critical for actual floor use. Pausing Sprint 2 (Auth) to tackle this first.

Estimated Time: 2-3 hours

Next Action: Update Tailwind config with mobile-first breakpoints...