responsive-design

Mobile-First Is Not a Technical Strategy — It Is a Content Strategy

Mobile-first forces content prioritization. When you design for 320px first, you must decide what actually matters. Desktop is the easy case — there is room for everything. Mobile reveals what is essential. Start narrow, enhance wide. Use min-width media queries exclusively (progressive enhancement).

Breakpoint Reference

Define breakpoints based on common device classes. Use min-width (mobile-first) exclusively.

Name	Range	Min-Width Query	Typical Devices
xs	0-479px	(base styles)	Small phones
sm	480-639px	@media (min-width: 480px)	Large phones
md	640-767px	@media (min-width: 640px)	Small tablets
lg	768-1023px	@media (min-width: 768px)	Tablets, small laptops
xl	1024-1279px	@media (min-width: 1024px)	Laptops, desktops
2xl	1280px+	@media (min-width: 1280px)	Large desktops

Rule: Design for xs first. Add complexity at each breakpoint. Never start with desktop and subtract.

Fluid Grids

Use CSS Grid auto-fit/auto-fill with minmax() for grids that reflow without media queries. Use clamp() for fluid sizing that interpolates between a minimum and maximum.

/* Responsive card grid — no media queries needed */
.card-grid {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
  gap: 24px;
}

/* Fluid container padding */
.container {
  padding-inline: clamp(16px, 4vw, 48px);
  max-width: 1200px;
  margin-inline: auto;
}

Container Queries

Container queries decouple component responsiveness from the viewport. A card in a sidebar and a card in the main content area can respond to their own available space.

.card-wrapper {
  container-type: inline-size;
  container-name: card;
}

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

@container card (max-width: 399px) {
  .card { flex-direction: column; }
}

Use container queries when: a component appears in multiple layout contexts (sidebar, main, modal) and must adapt to its container, not the viewport.

Responsive Images

Use srcset for resolution switching and <picture> for art direction. Lazy-load below-fold images. Set fetchpriority="high" on the LCP image.

Attribute	Purpose
srcset + sizes	Browser selects the best resolution based on viewport and pixel density
<picture> + <source>	Art direction — different crops or aspect ratios per breakpoint
loading="lazy"	Defer loading for images below the fold
fetchpriority="high"	Prioritize the Largest Contentful Paint image
width + height	Reserve space to prevent CLS (see craftsmanship-polish for CLS rules)

<picture>
  <source srcset="/img/hero-wide.avif" media="(min-width: 768px)" type="image/avif" />
  <source srcset="/img/hero-wide.webp" media="(min-width: 768px)" type="image/webp" />
  <source srcset="/img/hero-narrow.avif" type="image/avif" />
  <source srcset="/img/hero-narrow.webp" type="image/webp" />
  <img src="/img/hero-narrow.jpg" alt="Hero" width="800" height="600"
       fetchpriority="high" decoding="async" />
</picture>

Responsive Typography

Use clamp() for fluid type scaling. See the typography skill for the full clamp() value table. Never use pure vw alone — it becomes unreadable on small screens and enormous on large ones.

Touch Targets

Apply the 44x44px minimum touch target and 8px spacing rules from the accessibility-inclusive-design skill. On mobile, extend hit areas with padding:

/* Extend hit area with padding */
.icon-btn {
  display: inline-flex;
  align-items: center;
  justify-content: center;
  min-width: 44px;
  min-height: 44px;
  padding: 10px;
}

Navigation Patterns

Choose the navigation pattern based on item count and importance.

Pattern	Items	Best For	Mobile Behavior
Hamburger menu	5+	Content-heavy sites, secondary nav	Slide-in drawer or full-screen overlay
Bottom tabs	3-5	Mobile apps, high-frequency nav	Fixed at bottom, always visible
Priority+	Variable	Primary nav with overflow	Show as many items as fit, collapse rest into "More"
Full-screen overlay	Any	Marketing sites, minimal nav	Covers entire viewport with large tap targets

Rule: On mobile, the most important actions must be reachable with one thumb. Place primary navigation within the bottom 60% of the screen when possible.

Responsive Tables

Tables on mobile require adaptation. Choose the pattern based on data complexity.

Pattern	When to Use	How
Horizontal scroll	Simple data, few columns	overflow-x: auto on table wrapper
Card transformation	Complex data, many columns	Each row becomes a stacked card on mobile
Column priority	Some columns more important	Hide low-priority columns on small screens, show on hover or expand

Mobile Viewport Height

Use 100dvh (dynamic viewport height) instead of 100vh on mobile. The vh unit does not account for browser chrome (address bar, toolbar), causing content to be hidden behind UI elements.

Anti-Patterns

Anti-Pattern	Why It Fails	Fix
Fixed-width layouts (e.g., width: 960px)	Broken on every viewport except one	Use fluid widths, max-width, and minmax()
Horizontal scroll on body	Frustrating, signals broken layout	Audit for elements exceeding viewport width
Tiny touch targets (<44px)	Misclicks, accessibility failure	Apply touch target rules (see accessibility-inclusive-design skill)
Desktop-first with max-width overrides	Fragile, constantly undoing styles	Rewrite mobile-first with min-width queries
Media query soup (20+ breakpoints)	Unmaintainable, overlapping rules	Consolidate to 4-6 breakpoints, use fluid techniques
100vh on mobile	Content hidden behind browser chrome	Use 100dvh or 100svh
Pure vw for font size	Unreadable on mobile, enormous on 4K	Use clamp() (see typography skill)

Cross-Media Notes

• Responsive is web-specific but the principle of "adapt to the medium" is universal. Presentations must work on projector screens and laptop monitors. Documents must work in A4 and Letter formats.
• Presentations: Design slides at 16:9 but test at lower resolutions. Ensure text is readable from the back of the room (minimum 24pt body, 36pt headings).
• Documents: Use responsive margins — wider for print, narrower for screen reading. Test PDF rendering on mobile devices.

Examples

Working implementations in examples/:

• examples/fluid-grid-and-responsive-images.md — Responsive card grid with auto-fit, responsive images with srcset, and touch-target-safe buttons in CSS/Tailwind/React

Review Checklist

When reviewing or building responsive designs:

• Styles are written mobile-first using min-width media queries (no max-width)
• Breakpoints align with the 6-level reference table (xs through 2xl)
• Card grids use auto-fit/auto-fill with minmax() for media-query-free reflow
• Container queries used for components that appear in multiple layout contexts
• All images use srcset + sizes or <picture> for responsive loading
• LCP image has fetchpriority="high" and all below-fold images have loading="lazy"
• All images have width and height attributes (see craftsmanship-polish for CLS rules)
• Touch targets meet accessibility requirements (see accessibility-inclusive-design skill)
• Typography uses clamp() for fluid scaling (see typography skill for values)
• 100dvh used instead of 100vh for full-height mobile layouts
• Tables adapt on mobile (horizontal scroll, card transformation, or column priority)
• Navigation pattern is appropriate for item count and collapses gracefully on mobile