# Layout Guide — Agent Instructions

This file is the single source of truth for spacing, grid systems, responsive design, and layout rules in this design system.

---

## Spacing: The 8pt Grid

All spacing values must be multiples of 8px (4px for fine-tuning inside components). No random values. Ever.

All tokens live in `layout.css` as `--space-0` through `--space-13`.

### The Most Important Rule

Internal spacing (inside a component) must be LESS than or equal to external spacing (between components). When this is violated, elements feel disconnected from their containers.

### Proximity Creates Meaning

| Relationship | Spacing | Tokens |
|---|---|---|
| Related items | 8–16px | `--space-2` to `--space-4` |
| Loosely related | 24–32px | `--space-6` to `--space-7` |
| Different sections | 48–64px | `--space-9` to `--space-10` |
| Different content areas | 64–128px | `--space-10` to `--space-13` |

### Common Usage

| Context | Token | Value |
|---|---|---|
| Icon gaps, tight inline | `--space-1` | 4px |
| Related elements (icon + label) | `--space-2` | 8px |
| Label-to-input gap | `--space-3` | 12px |
| Default internal padding | `--space-4` | 16px |
| Card padding, form field gaps | `--space-6` | 24px |
| Section spacing | `--space-7` | 32px |
| Page section spacing | `--space-10` | 64px |

---

## Grid Systems

- Use a **12-column grid** (divides evenly by 2, 3, 4, 6)
- Gutter width: 16–32px (must use spacing tokens: `--space-4` to `--space-7`)
- Container max-widths by purpose:
  - 640px — narrow (reading, forms)
  - 768px — reading column
  - 1024px — app layout
  - 1280px — wide app
  - 1536px — dashboard

---

## Alignment

- **Left-align text** (centered text is harder to scan)
- Align elements to a shared left edge wherever possible
- Optical alignment sometimes matters more than mathematical alignment (e.g., play button triangles need visual centering, not exact centering)

---

## Whitespace

- Whitespace creates grouping, hierarchy, and breathing room
- More whitespace around an element = more importance
- Prefer whitespace over visible dividers to separate sections
- If dividers are needed, make them subtle (1px, low opacity)

---

## Responsive Design

### Breakpoints

All breakpoint tokens live in `layout.css`:

| Token | Value | Context |
|---|---|---|
| `--bp-sm` | 640px | Mobile landscape |
| `--bp-md` | 768px | Tablet portrait |
| `--bp-lg` | 1024px | Tablet landscape / small desktop |
| `--bp-xl` | 1280px | Desktop |
| `--bp-2xl` | 1536px | Large desktop |

### Design mobile-first, then add complexity for larger screens.

Responsive means the experience is GOOD at every size, not just that it fits.

- **Mobile:** Single column, bottom nav, full-width buttons, no hover states
- **Tablet:** Two columns where appropriate, adaptive density
- **Desktop:** Multi-column, sidebar nav, hover states, higher information density

### Mobile-First Component Adjustments

| Component | Mobile | Tablet | Desktop |
|---|---|---|---|
| Nav | Bottom tabs or hamburger | Top nav, simplified | Full top nav + sidebar |
| Buttons | Full width, 48px height | Auto width, 40px | Auto width, 36–40px |
| Cards | Single column, full width | 2 columns | 3–4 columns |
| Tables | Card view or horizontal scroll | Visible with scroll | Full table |
| Modals | Full screen (sheet) | Centered, 480px max | Centered, type-based |
| Forms | Single column, large targets | Single or two column | Two column for long forms |
| Typography | Base 16px | Base 16px | Base 16px (scale up headings) |

### Touch Target Rules

- Minimum: 44×44px (Apple HIG) / 48×48dp (Material)
- Comfortable: 48×48px
- Space between targets: at least 8px (`--space-2`)
- Bottom of screen = easiest thumb reach
- Top corners = hardest thumb reach

### Viewport Tricks

```css
/* Proper mobile viewport height (accounts for browser chrome) */
.full-height { height: 100dvh; }

/* Safe area for notched phones */
.container {
  padding-left: env(safe-area-inset-left);
  padding-right: env(safe-area-inset-right);
  padding-bottom: env(safe-area-inset-bottom);
}
```