# Design System - Responsive Foundation

## Overview

This document establishes the responsive design rules for Self Serve Pinnlo. All layouts are **mobile-first** (CSS methodology) and **width-based**, adapting fluidly to viewport size rather than detecting device type.

**Key Principles:**
- Mobile-first CSS (base styles start small, enhance upward)
- Desktop and mobile get **equal treatment** - same quality experience
- Width-based transitions, not device detection
- Graceful degradation in split-screen and resized windows
- Fluid layouts that adapt, not scale

---

## Breakpoints

### Tailwind Breakpoint System

| Tailwind Prefix | Min Width | Layout Name | Use Case |
|-----------------|-----------|-------------|----------|
| (none/base) | 0px | Mobile | Phones, narrow windows |
| `sm:` | 640px | Large Mobile / Small Tablet | Large phones, small tablets, narrow split-screen |
| `md:` | 768px | Tablet | Tablets, medium split-screen |
| `lg:` | 1024px | Desktop | Laptops, desktops |
| `xl:` | 1280px | Wide Desktop | Large monitors (optional enhancements) |

### CSS Media Queries

```css
/* Base styles apply to all screen sizes */
.component {
  width: 100%;
}

/* Large mobile / small tablet */
@media (min-width: 640px) {
  .component { width: 350px; }
}

/* Tablet */
@media (min-width: 768px) {
  .component { width: 380px; }
}

/* Desktop */
@media (min-width: 1024px) {
  .component { width: 388px; }
}

/* Wide desktop */
@media (min-width: 1280px) {
  .component { /* optional enhancements */ }
}
```

### Tailwind Usage Pattern

```jsx
// Responsive classes - base applies to all, then enhance upward
<div className="
  w-full              // All screens: full width
  sm:w-[350px]        // ≥640px: fixed width
  lg:w-[388px]        // ≥1024px: desktop width
">
```

---

## Mobile Reference Frame

| Property | Value |
|----------|-------|
| **Width** | 393px |
| **Purpose** | Canonical source for spacing, typography, components |
| **Height** | Fluid (vertical scrolling) |
| **Scaling** | Fluid/responsive adaptation, NOT proportional scaling |

The 393px mobile frame is the **design source of truth** for component design. Components should:
- Use percentage widths or `100%` where appropriate
- Have fluid typography that adapts
- Maintain touch-friendly targets at all sizes

---

## Spacing Scale

Consistent spacing tokens used across all breakpoints.

| Token | Value | Tailwind | Use Case |
|-------|-------|----------|----------|
| `--space-1` | 4px | `p-1`, `m-1`, `gap-1` | Tight spacing, icon gaps |
| `--space-2` | 8px | `p-2`, `m-2`, `gap-2` | Small component padding |
| `--space-3` | 12px | `p-3`, `m-3`, `gap-3` | Medium spacing |
| `--space-4` | 16px | `p-4`, `m-4`, `gap-4` | Standard padding |
| `--space-6` | 24px | `p-6`, `m-6`, `gap-6` | Section spacing |
| `--space-8` | 32px | `p-8`, `m-8`, `gap-8` | Large spacing |
| `--space-12` | 48px | `p-12`, `m-12`, `gap-12` | Major sections |
| `--space-16` | 64px | `p-16`, `m-16`, `gap-16` | Page-level spacing |

### Responsive Spacing Adjustments

```jsx
// Spacing that adapts to viewport
<div className="
  p-4              // All screens: 16px padding
  md:p-6           // Tablet+: 24px padding
  lg:p-8           // Desktop+: 32px padding
">
```

---

## Touch Targets

### Minimum Sizes

| Element | Minimum Size | Recommended |
|---------|--------------|-------------|
| Buttons | 44 × 44px | 48 × 48px |
| Icon buttons | 44 × 44px | 44 × 44px |
| List items | 44px height | 48-56px height |
| Form inputs | 44px height | 48px height |
| Nav items | 44 × 44px | 48 × 48px |

### Implementation

```jsx
// Button with proper touch target
<button className="
  min-h-[44px]      // Minimum touch height
  min-w-[44px]      // Minimum touch width
  px-4              // Horizontal padding
  py-2              // Vertical padding
">

// Icon button with touch-friendly hitbox
<button className="
  w-11 h-11         // 44px × 44px
  flex items-center justify-center
">
  <Icon className="w-5 h-5" />  // 20px icon inside 44px button
</button>
```

---

## Component Behavior by Breakpoint

### Navigation

| Breakpoint | Behavior |
|------------|----------|
| **Mobile** (< 640px) | Bottom navigation bar with primary sections; overflow actions in hamburger menu |
| **Tablet** (≥ 768px) | Bottom navigation or condensed top bar |
| **Desktop** (≥ 1024px) | Persistent top navigation bar with links and actions |

```jsx
// Navigation responsive pattern
<nav className="
  fixed bottom-0 left-0 right-0  // Mobile: bottom bar
  lg:static lg:top-0             // Desktop: top bar
">
```

---

### Chat Panel

| Breakpoint | Behavior |
|------------|----------|
| **Mobile** (< 640px) | Full-screen view, entered as primary screen |
| **Tablet** (≥ 768px) | Slide-over panel or split view |
| **Desktop** (≥ 1024px) | Persistent right-hand sidebar, 388px wide |

```jsx
// Chat panel responsive pattern
<aside className="
  fixed inset-0                   // Mobile: full screen
  md:inset-auto md:right-0 md:w-[380px] md:h-full  // Tablet: slide-over
  lg:static lg:w-[388px]          // Desktop: sidebar
">
```

**Mobile Chat Flow:**
1. User taps chat icon in bottom nav
2. Chat opens as full-screen view
3. Back button returns to previous screen

---

### Modals

| Breakpoint | Behavior |
|------------|----------|
| **Mobile** (< 640px) | Full-screen or slide-up bottom sheet |
| **Tablet** (≥ 768px) | Centered modal, max-width ~90% |
| **Desktop** (≥ 1024px) | Centered modal, max-width 1296px |

```jsx
// Modal responsive pattern
<div className="
  fixed inset-0                   // Mobile: full screen
  md:inset-auto md:top-1/2 md:left-1/2 md:-translate-x-1/2 md:-translate-y-1/2
  md:w-[90%] md:max-w-4xl         // Tablet: centered, constrained
  lg:max-w-[1296px]               // Desktop: max width
  md:rounded-xl                   // Border radius on tablet+
">
```

**Bottom Sheet Pattern (Mobile):**
```jsx
<div className="
  fixed bottom-0 left-0 right-0
  bg-white rounded-t-2xl
  max-h-[90vh] overflow-y-auto
  animate-slide-up
">
```

---

### Strategy Selector

| Breakpoint | Behavior |
|------------|----------|
| **Mobile** (< 640px) | Dedicated screen accessed from navigation |
| **Tablet** (≥ 768px) | Dropdown or dedicated screen |
| **Desktop** (≥ 1024px) | Inline control in top navigation |

---

### Page Editor

| Breakpoint | Behavior |
|------------|----------|
| **Mobile** (< 640px) | Full-width, simplified toolbar |
| **Tablet** (≥ 768px) | Full-width with expanded toolbar |
| **Desktop** (≥ 1024px) | 1040px max-width, full toolbar |

```jsx
<div className="
  w-full                          // Mobile: full width
  lg:max-w-[1040px] lg:mx-auto    // Desktop: centered, max width
">
```

---

### Cards (Strategy/Template)

| Breakpoint | Behavior |
|------------|----------|
| **Mobile** (< 640px) | Full-width or 2-column grid |
| **Tablet** (≥ 768px) | 2-3 column grid |
| **Desktop** (≥ 1024px) | Auto-fit grid, 190px cards |

```jsx
<div className="
  grid gap-4
  grid-cols-1                     // Mobile: single column
  sm:grid-cols-2                  // Small tablet: 2 columns
  md:grid-cols-3                  // Tablet: 3 columns
  lg:grid-cols-[repeat(auto-fit,190px)]  // Desktop: auto-fit
">
```

---

## Typography Scaling

Typography uses the same scale across breakpoints but may adjust for readability.

| Element | Mobile | Desktop | Tailwind |
|---------|--------|---------|----------|
| H1 | 28px | 36px | `text-[28px] lg:text-[36px]` |
| H2 | 22px | 28px | `text-[22px] lg:text-[28px]` |
| H3 | 18px | 22px | `text-lg lg:text-[22px]` |
| Body | 14px | 14px | `text-sm` |
| Small | 12px | 12px | `text-xs` |
| Caption | 10px | 10px | `text-[10px]` |

---

## Layout Patterns

### Container

```jsx
<div className="
  w-full
  px-4 sm:px-6 lg:px-8           // Responsive horizontal padding
  max-w-7xl mx-auto              // Max width with centering
">
```

### Main Layout with Sidebar

```jsx
<div className="
  flex flex-col                  // Mobile: stacked
  lg:flex-row                    // Desktop: side-by-side
">
  <main className="flex-1">
    {/* Main content */}
  </main>
  <aside className="
    hidden lg:block              // Hidden on mobile
    lg:w-[388px]                 // Desktop sidebar width
  ">
    {/* Chat panel */}
  </aside>
</div>
```

### Bottom Navigation (Mobile)

```jsx
<nav className="
  fixed bottom-0 left-0 right-0
  lg:hidden                      // Hide on desktop
  h-16                           // 64px height
  bg-white border-t border-gray-200
  flex items-center justify-around
  pb-safe                        // Safe area for notched phones
">
```

---

## Safe Areas (Notched Devices)

For devices with notches or home indicators:

```css
/* Add to global styles */
.pb-safe {
  padding-bottom: env(safe-area-inset-bottom);
}

.pt-safe {
  padding-top: env(safe-area-inset-top);
}
```

```jsx
// Bottom navigation with safe area
<nav className="
  pb-safe                        // Padding for home indicator
  min-h-[calc(64px+env(safe-area-inset-bottom))]
">
```

---

## Testing Checklist

### Viewport Widths to Test

| Width | Scenario |
|-------|----------|
| 320px | Small phone (iPhone SE) |
| 375px | Medium phone (iPhone 12 mini) |
| 393px | Design reference frame |
| 414px | Large phone (iPhone Plus/Max) |
| 640px | Breakpoint: sm |
| 768px | Breakpoint: md (iPad Mini portrait) |
| 834px | iPad portrait |
| 1024px | Breakpoint: lg (iPad landscape) |
| 1280px | Breakpoint: xl |
| 1440px | Common desktop |
| 1920px | Full HD desktop |

### Scenarios to Test

- [ ] Browser window resizing (drag edge)
- [ ] Split-screen on iPad
- [ ] Split-screen on macOS
- [ ] Portrait and landscape orientation
- [ ] Zoom levels (100%, 125%, 150%)
- [ ] Text size accessibility settings

---

## Tailwind Config Extension

Add to `tailwind.config.js`:

```js
module.exports = {
  theme: {
    extend: {
      spacing: {
        'safe': 'env(safe-area-inset-bottom)',
      },
      screens: {
        // Default screens are already correct:
        // 'sm': '640px',
        // 'md': '768px',
        // 'lg': '1024px',
        // 'xl': '1280px',
        // '2xl': '1536px',
      },
    },
  },
}
```

---

## CSS Custom Properties

```css
:root {
  /* Spacing */
  --space-1: 4px;
  --space-2: 8px;
  --space-3: 12px;
  --space-4: 16px;
  --space-6: 24px;
  --space-8: 32px;
  --space-12: 48px;
  --space-16: 64px;

  /* Component Dimensions */
  --chat-panel-width: 388px;
  --modal-max-width: 1296px;
  --editor-max-width: 1040px;
  --nav-height-mobile: 64px;
  --nav-height-desktop: 55px;

  /* Touch Targets */
  --touch-target-min: 44px;

  /* Safe Areas */
  --safe-area-bottom: env(safe-area-inset-bottom, 0px);
  --safe-area-top: env(safe-area-inset-top, 0px);
}
```

---

## Design Tokens Summary

| Token | Value | Tailwind |
|-------|-------|----------|
| Mobile breakpoint | < 640px | (base) |
| Tablet breakpoint | ≥ 768px | `md:` |
| Desktop breakpoint | ≥ 1024px | `lg:` |
| Touch target min | 44px | `min-h-11 min-w-11` |
| Chat panel width | 388px | `w-[388px]` |
| Modal max width | 1296px | `max-w-[1296px]` |
| Editor max width | 1040px | `max-w-[1040px]` |
| Mobile nav height | 64px | `h-16` |
| Desktop nav height | 55px | `h-[55px]` |