singular-particular-space/skills/controlled-ux-designer/RESPONSIVE-DESIGN.md

# Responsive Design Reference

Detailed reference for implementing responsive, mobile-first designs.

## Mobile-First Approach

Always start with mobile design, then progressively enhance for larger screens.

**Why Mobile-First:**
- Forces focus on essential content
- Easier to scale up than scale down
- Better performance on mobile devices
- Aligns with usage patterns (mobile-first web)

## Breakpoint Strategy

### Standard Breakpoints

```css
/* Mobile First Approach */
/* Base styles: 0-640px (mobile) */

/* Small tablets and large phones */
@media (min-width: 640px) { }

/* Tablets */
@media (min-width: 768px) { }

/* Small laptops */
@media (min-width: 1024px) { }

/* Desktops */
@media (min-width: 1280px) { }

/* Large desktops */
@media (min-width: 1536px) { }
```

### Specific Breakpoint Ranges

| Range | Pixels | Target Devices | Layout Strategy |
|-------|--------|----------------|-----------------|
| **XS** | 0-479px | Small phones (iPhone SE, older Android) | Single column, stacked navigation, large touch targets (min 44px) |
| **SM** | 480-767px | Large phones (iPhone 14, most modern phones) | Single column, simplified UI, bottom navigation, reduced complexity |
| **MD** | 768-1023px | Tablets (iPad, Android tablets) | 2 columns possible, sidebar navigation, some desktop features |
| **LG** | 1024-1439px | Small laptops, landscape tablets | Multi-column layouts, full navigation, desktop UI patterns |
| **XL** | 1440px+ | Desktop monitors, large screens | Max-width containers, multi-panel layouts, advanced features visible |

**Mobile Simplification Examples:**

- **Navigation**: Hamburger menu (mobile) → Full nav bar (desktop)
- **Forms**: Stacked fields (mobile) → Side-by-side fields (desktop)
- **Content**: Single column (mobile) → Multi-column grid (desktop)
- **Actions**: Fixed bottom bar (mobile) → Inline buttons (desktop)
- **Tables**: Collapsed cards (mobile) → Full data table (desktop)
- **Sidebars**: Hidden/collapsible (mobile) → Always visible (desktop)
- **Filters**: Modal/drawer (mobile) → Sidebar panel (desktop)

### Tailwind Responsive Classes

```tsx
<div className="
  w-full          // mobile: full width
  sm:w-1/2        // small: half width
  md:w-1/3        // medium: third width
  lg:w-1/4        // large: quarter width
">
  Responsive width
</div>
```

## Responsive Images

### Using srcset for Responsive Images

```tsx
<img
  src="image-800w.jpg"
  srcSet="
    image-400w.jpg 400w,
    image-800w.jpg 800w,
    image-1200w.jpg 1200w
  "
  sizes="
    (max-width: 640px) 100vw,
    (max-width: 1024px) 50vw,
    33vw
  "
  alt="Descriptive alt text"
  loading="lazy"
/>
```

### Next.js Image Component

```tsx
import Image from 'next/image';

<Image
  src="/hero-image.jpg"
  alt="Descriptive alt text"
  width={1200}
  height={600}
  priority // for above-the-fold images
  className="w-full h-auto"
/>
```

## Responsive Typography

### Fluid Typography with Tailwind

```tsx
<h1 className="
  text-3xl      // mobile: 30px
  sm:text-4xl   // small: 36px
  md:text-5xl   // medium: 48px
  lg:text-6xl   // large: 60px
">
  Responsive Headline
</h1>
```

### Fluid Typography with CSS Clamp

```css
h1 {
  /* min: 2rem (32px), preferred: 5vw, max: 4rem (64px) */
  font-size: clamp(2rem, 5vw, 4rem);
  line-height: 1.2;
}

p {
  /* min: 1rem (16px), preferred: 2.5vw, max: 1.25rem (20px) */
  font-size: clamp(1rem, 2.5vw, 1.25rem);
  line-height: 1.6;
}
```

## Responsive Layouts

### CSS Grid Responsive Pattern

```tsx
<div className="
  grid
  grid-cols-1        // mobile: 1 column
  sm:grid-cols-2     // small: 2 columns
  md:grid-cols-3     // medium: 3 columns
  lg:grid-cols-4     // large: 4 columns
  gap-4              // consistent gap
">
  {items.map(item => (
    <Card key={item.id}>{item.content}</Card>
  ))}
</div>
```

### Flexbox Responsive Pattern

```tsx
<div className="
  flex
  flex-col           // mobile: stack vertically
  md:flex-row        // medium+: horizontal layout
  gap-6
  items-center
">
  <div className="w-full md:w-1/2">Content Left</div>
  <div className="w-full md:w-1/2">Content Right</div>
</div>
```

## Touch-Friendly Interfaces

### Touch Target Sizing

```tsx
// Minimum 44x44px touch targets
<button className="
  min-w-[44px]
  min-h-[44px]
  px-4 py-2
  rounded-lg
  touch-manipulation // prevents 300ms tap delay
">
  Tap Me
</button>
```

### Touch Gestures

```tsx
// Consider common mobile gestures
<div className="
  overflow-x-auto    // horizontal scroll
  snap-x             // snap scrolling
  snap-mandatory
  overscroll-contain // prevent bounce on mobile
">
  {/* Scrollable content */}
</div>
```

## Navigation Patterns

### Mobile Menu Pattern

```tsx
import { useState } from 'react';
import { List, X } from '@phosphor-icons/react';

export function MobileNav() {
  const [isOpen, setIsOpen] = useState(false);

  return (
    <>
      {/* Mobile menu button */}
      <button
        onClick={() => setIsOpen(!isOpen)}
        className="md:hidden p-2"
        aria-label="Toggle menu"
      >
        {isOpen ? <X size={24} /> : <List size={24} />}
      </button>

      {/* Mobile menu overlay */}
      {isOpen && (
        <div className="
          fixed inset-0 z-50 bg-white
          md:hidden
        ">
          <nav className="p-6 space-y-4">
            {/* Navigation items */}
          </nav>
        </div>
      )}

      {/* Desktop navigation */}
      <nav className="hidden md:flex gap-6">
        {/* Navigation items */}
      </nav>
    </>
  );
}
```

### Sticky Navigation

```tsx
<header className="
  sticky top-0 z-40
  bg-white/80
  backdrop-blur-md
  border-b border-slate-200
">
  <nav className="container mx-auto px-4 py-4">
    {/* Navigation content */}
  </nav>
</header>
```

## Responsive Forms

### Form Layout Pattern

```tsx
<form className="space-y-6">
  {/* Full width on mobile, side-by-side on desktop */}
  <div className="
    grid
    grid-cols-1
    md:grid-cols-2
    gap-4
  ">
    <div>
      <label htmlFor="firstName" className="block text-sm font-medium mb-1">
        First Name
      </label>
      <input
        id="firstName"
        type="text"
        className="
          w-full px-4 py-2
          border border-slate-300
          rounded-lg
          focus:ring-2 focus:ring-blue-500
          touch-manipulation
        "
      />
    </div>

    <div>
      <label htmlFor="lastName" className="block text-sm font-medium mb-1">
        Last Name
      </label>
      <input
        id="lastName"
        type="text"
        className="
          w-full px-4 py-2
          border border-slate-300
          rounded-lg
          focus:ring-2 focus:ring-blue-500
          touch-manipulation
        "
      />
    </div>
  </div>

  {/* Full width textarea */}
  <div>
    <label htmlFor="message" className="block text-sm font-medium mb-1">
      Message
    </label>
    <textarea
      id="message"
      rows={4}
      className="
        w-full px-4 py-2
        border border-slate-300
        rounded-lg
        focus:ring-2 focus:ring-blue-500
        touch-manipulation
      "
    />
  </div>

  <button
    type="submit"
    className="
      w-full md:w-auto
      px-8 py-3
      bg-blue-600 text-white
      rounded-lg
      hover:bg-blue-700
      transition-colors
      touch-manipulation
    "
  >
    Submit
  </button>
</form>
```

## Responsive Content Hiding

### Show/Hide Based on Screen Size

```tsx
<div>
  {/* Show only on mobile */}
  <div className="block md:hidden">
    Mobile content
  </div>

  {/* Show only on tablet and up */}
  <div className="hidden md:block">
    Desktop content
  </div>

  {/* Show only on desktop */}
  <div className="hidden lg:block">
    Large screen content
  </div>
</div>
```

## Performance Optimization

### Lazy Loading Images

```tsx
<img
  src="image.jpg"
  alt="Description"
  loading="lazy"
  className="w-full h-auto"
/>
```

### Responsive Video

```tsx
<div className="relative aspect-video">
  <video
    className="absolute inset-0 w-full h-full object-cover"
    poster="thumbnail.jpg"
    controls
    preload="metadata"
  >
    <source src="video-mobile.mp4" media="(max-width: 640px)" />
    <source src="video-desktop.mp4" />
  </video>
</div>
```

## Testing Responsive Designs

### Browser DevTools

1. Open Chrome/Firefox DevTools (F12)
2. Toggle device toolbar (Ctrl+Shift+M)
3. Test common breakpoints:
   - iPhone SE (375px)
   - iPhone 12 Pro (390px)
   - iPad (768px)
   - iPad Pro (1024px)
   - Desktop (1280px+)

### Real Device Testing

**Essential devices to test:**
- Small phone (iPhone SE, Android small)
- Large phone (iPhone Pro Max, Android large)
- Tablet (iPad, Android tablet)
- Desktop (various resolutions)

### Playwright Testing

```typescript
// Use playwright MCP to test responsive breakpoints
await page.setViewportSize({ width: 375, height: 667 }); // iPhone SE
await page.screenshot({ path: 'mobile.png' });

await page.setViewportSize({ width: 768, height: 1024 }); // iPad
await page.screenshot({ path: 'tablet.png' });

await page.setViewportSize({ width: 1920, height: 1080 }); // Desktop
await page.screenshot({ path: 'desktop.png' });
```

## Common Responsive Patterns

### Card Grid

```tsx
<div className="
  grid
  grid-cols-1
  sm:grid-cols-2
  lg:grid-cols-3
  xl:grid-cols-4
  gap-6
  p-4
">
  {items.map(item => (
    <article
      key={item.id}
      className="
        bg-white
        rounded-lg
        border border-slate-200
        overflow-hidden
        hover:shadow-lg
        transition-shadow
      "
    >
      <img
        src={item.image}
        alt={item.title}
        className="w-full h-48 object-cover"
        loading="lazy"
      />
      <div className="p-4">
        <h3 className="text-lg font-semibold mb-2">{item.title}</h3>
        <p className="text-slate-600">{item.description}</p>
      </div>
    </article>
  ))}
</div>
```

### Hero Section

```tsx
<section className="
  relative
  min-h-screen
  flex items-center
  px-4 sm:px-6 lg:px-8
">
  <div className="
    max-w-7xl mx-auto w-full
    grid grid-cols-1 lg:grid-cols-2
    gap-12
    items-center
  ">
    <div className="space-y-6">
      <h1 className="
        text-4xl sm:text-5xl lg:text-6xl
        font-bold
        tracking-tight
      ">
        Your Headline Here
      </h1>
      <p className="
        text-lg sm:text-xl
        text-slate-600
        max-w-2xl
      ">
        Supporting description that works across all screen sizes.
      </p>
      <div className="
        flex flex-col sm:flex-row
        gap-4
      ">
        <button className="
          px-8 py-3
          bg-blue-600 text-white
          rounded-lg
          hover:bg-blue-700
          transition-colors
        ">
          Primary Action
        </button>
        <button className="
          px-8 py-3
          border-2 border-slate-300
          rounded-lg
          hover:border-slate-400
          transition-colors
        ">
          Secondary Action
        </button>
      </div>
    </div>
    <div className="
      relative
      aspect-square
      rounded-2xl
      overflow-hidden
    ">
      <img
        src="hero-image.jpg"
        alt="Hero"
        className="w-full h-full object-cover"
      />
    </div>
  </div>
</section>
```

## Accessibility Considerations

### Focus Management on Mobile

```tsx
<button
  className="
    focus:outline-none
    focus:ring-4 focus:ring-blue-500
    focus:ring-offset-2
    rounded-lg
  "
  aria-label="Descriptive label"
>
  Action
</button>
```

### Skip Links

```tsx
<a
  href="#main-content"
  className="
    sr-only
    focus:not-sr-only
    focus:absolute
    focus:top-4 focus:left-4
    focus:z-50
    focus:px-4 focus:py-2
    focus:bg-blue-600 focus:text-white
    focus:rounded-lg
  "
>
  Skip to main content
</a>
```

## Best Practices Summary

✅ **Do:**
- Start with mobile design first
- Use relative units (rem, em, %) for flexibility
- Test on real devices, not just emulators
- Ensure touch targets are at least 44x44px
- Use semantic HTML for better accessibility
- Implement lazy loading for images and videos
- Optimize assets for mobile networks
- Use CSS Grid and Flexbox for flexible layouts
- Provide adequate spacing between interactive elements

❌ **Don't:**
- Design for desktop first and scale down
- Use fixed pixel widths for layout containers
- Rely solely on browser DevTools for testing
- Make touch targets too small
- Forget keyboard navigation
- Load all images eagerly
- Use large unoptimized images on mobile
- Use complex nested tables for layout
- Place important actions in hard-to-reach areas