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.

Adaptive Width Classes (Material Design 3 Model)

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