Responsive Design

A production-grade reference for building responsive web experiences that adapt fluidly across every screen size. This skill encodes specific, opinionated rules for mobile-first CSS architecture, fluid typography with clamp(), container queries, breakpoint strategy, and intrinsic layout techniques. Every pattern includes concrete, copy-paste-ready CSS - not vague advice.

The difference between a truly responsive site and a barely-functional one comes down to architecture: fluid values over hard breakpoints, container awareness over viewport assumptions, and content-driven layout over device-targeted hacks.

---

When to use this skill

Trigger this skill when the user:

• Asks how to build a responsive layout or page structure
• Needs a breakpoint strategy or media query system
• Wants to implement fluid typography that scales with the viewport
• Is using or learning container queries
• Needs responsive images with srcset or <picture>
• Asks about clamp(), min(), max(), or viewport units (vw, vh, dvh)
• Wants a responsive navigation pattern (hamburger, bottom nav, drawer)
• Needs a responsive spacing or sizing scale
• Asks about mobile-first CSS architecture
• Needs adaptive layout for components like cards, grids, or sidebars

Do NOT trigger this skill for:

• Pure visual styling that isn't adaptive (colors, shadows, typography scale with no fluid values)
• Backend or API concerns, even if a mobile app is involved

---

Key principles

1. Mobile-first always - Write base CSS for the smallest screen. Use min-width media queries to progressively enhance for larger screens. max-width queries lead to override chains and maintenance nightmares.

2. Use fluid values over fixed breakpoints - clamp(), min(), max(), and vw/cqi units create layouts that work at every size, not just at your three chosen breakpoints. Breakpoints should be rare exceptions for layout shifts, not the primary mechanism for responsiveness.

3. Container queries over media queries for components - Components should respond to the space they're placed in, not the viewport. Use @container for any component that might appear in different-width contexts (sidebars, cards, modals). Reserve media queries for page-level layout changes only.

4. Content determines breakpoints, not devices - Add a breakpoint when the content breaks, not because you want to target iPhone vs tablet. Resize your browser slowly and add breakpoints where the layout actually needs help.

5. Test on real devices - DevTools device mode is not a substitute. Test on actual hardware at key points: 320px minimum width (small Android), 375px (iPhone), 768px (tablet portrait), 1024px (tablet landscape), and 1440px (desktop). Check landscape orientation and unusual sizes like 900px.

---

Core concepts

Viewport vs container - The viewport is the browser window. The container is the nearest ancestor with container-type set. Media queries respond to the viewport; container queries respond to the container. Use media queries to change page layout structure; use container queries to change component layout within a space.

Fluid vs adaptive - Adaptive design has discrete breakpoints where it "snaps" between layouts. Fluid design scales continuously. The best responsive systems combine both: fluid typography and spacing everywhere, with adaptive layout changes at a handful of content-driven breakpoints.

Intrinsic design - Coined by Jen Simmons. Letting content inform size using CSS Grid's auto-fill/auto-fit/minmax() and Flexbox's flex-wrap. Fewer media queries, more resilient layouts.

CSS logical properties - Use margin-inline, padding-block, inset-inline instead of margin-left/right, padding-top/bottom, left/right. These adapt automatically to writing direction (LTR/RTL) and block axis, making internationalised responsive layouts trivial.

---

Common tasks

1. Mobile-first breakpoint system

Define a single breakpoint token set. Apply them consistently with min-width only. Never mix min-width and max-width in the same component.

:root {
  --bp-sm:  640px;   /* large phones landscape */
  --bp-md:  768px;   /* tablets portrait       */
  --bp-lg:  1024px;  /* tablets landscape      */
  --bp-xl:  1280px;  /* desktop                */
  --bp-2xl: 1536px;  /* large desktop          */
}

/* Usage pattern - always mobile base, then expand */
.component {
  /* mobile base styles */
  display: flex;
  flex-direction: column;
  gap: 16px;
  padding: 16px;
}

@media (min-width: 768px) {
  .component {
    flex-direction: row;
    gap: 24px;
    padding: 24px;
  }
}

@media (min-width: 1024px) {
  .component {
    gap: 32px;
    padding: 32px 48px;
  }
}

Never write @media (max-width: 767px) - that's desktop-first and leads to specificity battles. The base styles ARE the mobile styles.

2. Fluid typography with clamp()

clamp(min, preferred, max) - the preferred value is a viewport-relative expression. The browser picks the middle value, clamped to min/max.

:root {
  /* fluid body text: 15px at 320px viewport, 18px at 1280px */
  --text-base: clamp(0.9375rem, 0.8rem + 0.6vw, 1.125rem);

  /* fluid headings */
  --text-lg:   clamp(1.125rem,  0.9rem + 1vw,   1.5rem);
  --text-xl:   clamp(1.25rem,   0.9rem + 1.5vw, 2rem);
  --text-2xl:  clamp(1.5rem,    1rem + 2vw,     2.5rem);
  --text-3xl:  clamp(1.875rem,  1rem + 3vw,     3.5rem);
  --text-4xl:  clamp(2.25rem,   1rem + 4.5vw,   5rem);

  /* fluid spacing */
  --space-section: clamp(2rem, 1rem + 4vw, 6rem);
  --space-gap:     clamp(1rem, 0.5rem + 2vw, 2rem);
}

body { font-size: var(--text-base); }
h1   { font-size: var(--text-4xl); line-height: 1.1; }
h2   { font-size: var(--text-3xl); line-height: 1.2; }
h3   { font-size: var(--text-2xl); line-height: 1.3; }

Calculate fluid clamp() values precisely using Utopia (utopia.fyi) or the formula: clamp(min, min + (max - min) * ((100vw - minVp) / (maxVp - minVp)), max). Never guess the middle value.

3. Container queries for components

Container queries let components adapt to their available space regardless of viewport. Essential for any component used in varied layout contexts.

/* 1. Establish a containment context on the wrapper */
.card-wrapper {
  container-type: inline-size;
  container-name: card;  /* optional, enables named queries */
}

/* 2. Style the component to respond to its container */
.card {
  /* base: narrow container (e.g. sidebar, 240px wide) */
  display: flex;
  flex-direction: column;
  gap: 12px;
}

/* 3. Expand when container is wide enough */
@container card (min-width: 480px) {
  .card {
    flex-direction: row;
    gap: 24px;
  }

  .card-image {
    width: 200px;
    flex-shrink: 0;
  }
}

@container card (min-width: 720px) {
  .card {
    gap: 32px;
  }

  .card-image {
    width: 280px;
  }
}

container-type: inline-size is the common case - it tracks width only. Use container-type: size only when you also need to query height. The container element itself cannot be styled by @container - only its descendants can.

4. Responsive grid layouts

Combine intrinsic CSS Grid with a fallback for very small screens.

/* Intrinsic auto-fill grid - no breakpoints needed */
.grid-auto {
  display: grid;
  grid-template-columns: repeat(auto-fill, minmax(min(100%, 280px), 1fr));
  gap: clamp(12px, 2vw, 24px);
}

/* Explicit breakpoint grid for controlled column counts */
.grid-explicit {
  display: grid;
  grid-template-columns: 1fr;           /* mobile: 1 col */
  gap: 16px;
}

@media (min-width: 640px) {
  .grid-explicit { grid-template-columns: repeat(2, 1fr); gap: 20px; }
}

@media (min-width: 1024px) {
  .grid-explicit { grid-template-columns: repeat(3, 1fr); gap: 24px; }
}

@media (min-width: 1280px) {
  .grid-explicit { grid-template-columns: repeat(4, 1fr); gap: 32px; }
}

/* Sidebar layout with fluid sidebar width */
.layout-sidebar {
  display: grid;
  grid-template-columns: 1fr;
}

@media (min-width: 1024px) {
  .layout-sidebar {
    grid-template-columns: clamp(200px, 20%, 280px) 1fr;
    gap: 32px;
  }
}

Prefer minmax(min(100%, Npx), 1fr) over minmax(Npx, 1fr) - the min() prevents overflow on very narrow screens where Npx exceeds container width.

5. Responsive images with srcset and picture

Always provide multiple image sizes. Let the browser pick the best one.

<!-- Fluid image: browser picks from srcset based on display width -->
<img
  src="hero-800.jpg"
  srcset="
    hero-400.jpg   400w,
    hero-800.jpg   800w,
    hero-1200.jpg 1200w,
    hero-1600.jpg 1600w
  "
  sizes="
    (min-width: 1280px) 1200px,
    (min-width: 768px)  calc(100vw - 64px),
    100vw
  "
  alt="Descriptive alt text"
  width="1200"
  height="600"
  loading="lazy"
  decoding="async"
/>

<!-- Art direction with <picture>: different crop per breakpoint -->
<picture>
  <source
    media="(min-width: 1024px)"
    srcset="hero-landscape-1600.jpg 1600w, hero-landscape-800.jpg 800w"
    sizes="100vw"
  />
  <source
    media="(min-width: 480px)"
    srcset="hero-square-800.jpg 800w, hero-square-400.jpg 400w"
    sizes="100vw"
  />
  <img
    src="hero-portrait-400.jpg"
    srcset="hero-portrait-400.jpg 400w, hero-portrait-800.jpg 800w"
    sizes="100vw"
    alt="Descriptive alt text"
    width="400"
    height="600"
  />
</picture>

Always include width and height attributes to prevent layout shift (CLS). Use loading="lazy" for images below the fold. Use loading="eager" for the LCP hero image. The sizes attribute is the most important part - a wrong sizes wastes bandwidth by downloading the wrong resolution.

6. Responsive navigation patterns

For detailed responsive navigation patterns (hamburger drawer, bottom tab bar, safe area handling), see references/navigation-patterns.md.

7. Responsive spacing scale

Fluid spacing that adapts to viewport size without breakpoints.

:root {
  --space-1:  clamp(0.25rem, 0.2rem + 0.25vw, 0.375rem);  /*  4px -> 6px  */
  --space-2:  clamp(0.5rem,  0.4rem + 0.5vw,  0.75rem);   /*  8px -> 12px */
  --space-3:  clamp(0.75rem, 0.6rem + 0.75vw, 1rem);      /* 12px -> 16px */
  --space-4:  clamp(1rem,    0.75rem + 1.25vw, 1.5rem);   /* 16px -> 24px */
  --space-6:  clamp(1.5rem,  1rem + 2vw, 2.5rem);         /* 24px -> 40px */
  --space-8:  clamp(2rem,    1.25rem + 3vw, 4rem);        /* 32px -> 64px */
  --space-12: clamp(3rem,    2rem + 4vw,  6rem);          /* 48px -> 96px */
  --space-16: clamp(4rem,    2.5rem + 6vw, 8rem);        /* 64px -> 128px */
}

/* Apply fluid section padding */
.section {
  padding-block: var(--space-12);
  padding-inline: var(--space-4);
}

/* Fluid gap for grids and flex containers */
.card-grid {
  display: grid;
  grid-template-columns: repeat(auto-fill, minmax(min(100%, 280px), 1fr));
  gap: var(--space-4);
}

---

Anti-patterns

Anti-pattern	Why it fails	What to do instead
Writing desktop CSS first, then overriding with max-width queries	Override chains grow into unmaintainable specificity battles	Start with mobile base styles, add min-width queries to expand
Fixed px font sizes	Breaks user's browser font-size preference, fails WCAG 1.4.4	Use rem for all font sizes so they scale with user's base preference
Using viewport media queries for component styling	Component breaks when placed in a sidebar or different layout	Use @container queries for component-level responsiveness
Hiding content on mobile instead of reorganizing it	Content hidden by CSS is still downloaded; important info becomes inaccessible	Reflow content using Grid/Flexbox direction changes; only hide decorative elements
Static px values in clamp() middle expression	The preferred value won't scale; clamp becomes a fixed value	Use a viewport-relative unit (e.g. 0.8rem + 2vw) as the middle value
100vw width causing horizontal scrollbar	100vw includes scrollbar width; overflows container by ~15px	Use 100% for widths inside containers; use 100vw only for truly full-bleed elements

---

Gotchas

1. clamp() middle value not viewport-relative - clamp(1rem, 1.5rem, 2rem) looks like a fluid value but the middle is a fixed rem, so it never actually scales. The middle value must contain a viewport-relative unit (vw, cqi) to produce fluid scaling. Always verify the preferred expression includes a fluid unit.

2. container-type set on the element being styled - @container queries style descendants, not the container element itself. If you set container-type on .card and write @container (.card) { .card { ... } }, the inner rule never applies. The containment context must be on a wrapper element, one level up from the component being styled.

3. 100vw causing horizontal scrollbar - 100vw includes the scrollbar width (typically 15-17px on desktop). Using it for full-width elements inside a document with a vertical scrollbar overflows by that amount. Use 100% for widths inside layout containers; reserve 100vw for truly viewport-edge elements like modals and overlays.

4. Fixed px font sizes breaking user's zoom preference - WCAG 1.4.4 requires text to be resizable to 200% without loss of content. Fonts set in px don't scale with the browser's base font size preference. Use rem for all font sizes.

5. env(safe-area-inset-bottom) missing on bottom-fixed elements - On notched iOS devices, position: fixed; bottom: 0 elements overlap the home indicator. Always add padding-bottom: env(safe-area-inset-bottom) to fixed bottom bars and tab bars. Missing this creates an unusable UI on iPhone X and later models.

---

References

For detailed pattern examples, load the relevant reference file:

• references/breakpoint-patterns.md - Common responsive layout patterns with CSS examples
• references/navigation-patterns.md - Hamburger drawer, bottom tab bar, and safe area handling