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