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

```javascript
// 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

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

### Hide/Show Elements

```jsx
// 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

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

### Responsive Spacing

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

---

## 🎨 Mobile-First Component Examples

### Button Component

```tsx
// 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

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

### Navigation

```tsx
// 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...