Responsive & Adaptive Layout

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.

/* 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

.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

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

Fluid Typography

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

Container Queries

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

.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)

.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

.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

.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

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:

.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:

<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:

<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).