---
name: responsive-adaptive-layout
description: Build responsive layouts with fluid grids, container queries, and adaptive patterns that work from 320px to ultrawide — no breakpoint chaos.
---

# Responsive & Adaptive Layout

From mobile-first to fluid grids — layout that serves the content

Build layouts that serve the content at every viewport — from 320px phones to ultrawide monitors. Mobile-first, fluid by default, with breakpoints only where the design genuinely needs them.

## Mobile-First Workflow

Always start at the smallest viewport (375px) and scale up with `min-width` media queries. This forces you to prioritize content and progressive enhancement.

```css
/* Base: mobile (375px) */
.grid { display: grid; grid-template-columns: 1fr; gap: 1rem; }

/* Tablet (768px+) */
@media (min-width: 768px) {
  .grid { grid-template-columns: repeat(2, 1fr); gap: 1.5rem; }
}

/* Desktop (1024px+) */
@media (min-width: 1024px) {
  .grid { grid-template-columns: repeat(3, 1fr); gap: 2rem; }
}
```

Rules:
- Touch targets: minimum 44×44px at mobile.
- Text: minimum 16px body at mobile (14px only for dense data UI).
- Navigation: hamburger at mobile, horizontal at tablet+.
- Padding: 1rem at mobile, 1.5–2rem at desktop.

## Fluid Layouts Without Breakpoints

Many responsive needs can be solved without media queries:

### Auto-fit Grids

```css
.card-grid {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(min(100%, 280px), 1fr));
  gap: 1.5rem;
}
```

This creates a grid that:
- Shows 1 column on narrow viewports.
- Adds columns as space allows (minimum 280px per card).
- Never overflows (the `min(100%, 280px)` prevents overflow at narrow widths).

### Fluid Spacing

```css
section {
  padding-block: clamp(2rem, 1.5rem + 2.5vw, 4rem);
}
```

### Fluid Typography

```css
h1 {
  font-size: clamp(2rem, 1.5rem + 2.5vw, 3.5rem);
}
```

## Container Queries

When components need to respond to their container, not the viewport:

```css
.card-container { container-type: inline-size; }

@media (min-width: 400px) {
  .card { flex-direction: row; }
}
```

Use container queries for:
- Sidebar vs. main content cards (same component, different widths).
- Dashboard widgets that reflow based on panel size.
- Components in a design system that must work in any context.

## Layout Patterns

### The Holy Grail (Adaptive)

```css
.page {
  display: grid;
  grid-template-areas:
    "header"
    "main"
    "footer";
  min-height: 100dvh;
}

@media (min-width: 768px) {
  .page {
    grid-template-columns: 240px 1fr;
    grid-template-areas:
      "header header"
      "sidebar main"
      "footer footer";
  }
}
```

### The Dashboard Shell

```css
.dashboard {
  display: grid;
  grid-template-columns: auto 1fr;
  grid-template-rows: auto 1fr;
  min-height: 100dvh;
}

.sidebar { grid-row: 1 / -1; }
.topbar { grid-column: 2; }
.content { grid-column: 2; overflow: auto; }
```

At mobile: sidebar becomes a drawer (off-canvas, toggled by hamburger).

### The Content Layout

```css
.article {
  max-width: 65ch;
  margin-inline: auto;
  padding-inline: 1rem;
}

.article-wide {
  max-width: min(100% - 2rem, 900px);
  margin-inline: auto;
}
```

## Breakpoint Strategy

Don't add breakpoints because "it looks wrong." Add them because the layout pattern genuinely changes.

| Breakpoint | Typical device | When to add |
|------------|---------------|-------------|
| 640px | Large phone | Navigation pattern changes |
| 768px | Tablet | Grid columns increase, sidebar appears |
| 1024px | Small laptop | Full navigation, wider content |
| 1280px | Desktop | Maximum content width, side panels |
| 1536px | Large desktop | Wider gutters, additional columns |

## Adaptive Width Classes (Material Design 3 Model)

| Class | Width | Layout |
|-------|-------|--------|
| Compact | < 600px | Single column, bottom nav |
| Medium | 600–839px | 2 columns, nav rail or drawer |
| Expanded | 840–1199px | 2–3 columns, persistent nav |
| Large | 1200–1599px | Full layout, side panels |
| Extra large | ≥ 1600px | Maximum content width, generous gutters |

## Common Responsive Problems

### Text Overflow
Long heading words + large clamp scales + narrow grids cause headline overflow on tablet/mobile.

**Fix**: test the longest heading copy at every breakpoint. If it overflows, reduce the clamp max or rewrite the copy. The viewport is part of the design.

### Images
```css
img {
  max-width: 100%;
  height: auto;
  aspect-ratio: 16 / 9; /* prevent layout shift */
  object-fit: cover;
}
```

### Tables
Wide data tables don't fit mobile. Options:
- Horizontal scroll with `overflow-x: auto` on wrapper.
- Card layout at mobile (each row becomes a card).
- Column hiding with priority system (hide least-important columns first).

### Fixed-Width Elements
Never use fixed pixel widths for layout containers. Use `max-width` with fluid inner content:
```css
.container {
  max-width: min(100% - 2rem, 1200px);
  margin-inline: auto;
}
```

## Testing Checklist

- [ ] 320px: all content accessible, no horizontal scroll, touch targets ≥ 44px.
- [ ] 375px: standard phone — navigation works, text readable.
- [ ] 768px: tablet — layout reflows appropriately.
- [ ] 1024px: laptop — full layout visible.
- [ ] 1440px: desktop — content doesn't stretch too wide (max-width on text).
- [ ] 200% zoom: content reflows, no overlapping text.
- [ ] Landscape phone: layout doesn't break.
- [ ] Foldable/resizable: layout adapts smoothly.

## PageWeave-Specific

PageWeave uses Tailwind CSS v4. Use Tailwind's responsive utilities:

```html
<div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4 md:gap-6">
```

Tailwind breakpoints: `sm` (640px), `md` (768px), `lg` (1024px), `xl` (1280px), `2xl` (1536px).

For container queries in Tailwind v4:
```html
<div class="@container">
  <div class="@md:flex-row flex-col">
```

## Anti-Patterns

- Desktop-first with `max-width` queries (misses mobile edge cases).
- Breakpoints at every 100px (too many — use the natural content breakpoints).
- Fixed pixel widths for layout containers.
- `100vw` without accounting for scrollbar (causes horizontal scroll).
- Hiding content with `display: none` at mobile instead of restructuring.
- Images without `max-width: 100%` (overflow viewport).
- Text without `max-width` or `ch` units (unreadable line length on wide screens).