Responsive Design

Auto-generate your docs

Use container queries (@container) for component-level responsiveness and adapt the interface for different contexts—don’t just shrink it.

Mobile-First: Write It Right

Start with base styles for mobile, use min-width queries to layer complexity. Desktop-first (max-width) means mobile loads unnecessary styles first.

/* Mobile base styles */
.card {
  padding: 1rem;
  font-size: 0.875rem;
}

/* Tablet and up */
@media (min-width: 640px) {
  .card {
    padding: 1.5rem;
    font-size: 1rem;
  }
}

/* Desktop */
@media (min-width: 1024px) {
  .card {
    padding: 2rem;
  }
}

Breakpoints: Content-Driven

Don’t chase device sizes—let content tell you where to break. Start narrow, stretch until design breaks, add breakpoint there. Three breakpoints usually suffice: 640, 768, 1024px Use clamp() for fluid values without breakpoints:

.container {
  padding: clamp(1rem, 5vw, 3rem);
  font-size: clamp(1rem, 2.5vw, 1.5rem);
}

Detect Input Method, Not Just Screen Size

Screen size doesn’t tell you input method. A laptop with touchscreen, a tablet with keyboard—use pointer and hover queries.

/* Fine pointer (mouse, trackpad) */
@media (pointer: fine) {
  .button { padding: 8px 16px; }
}

/* Coarse pointer (touch, stylus) */
@media (pointer: coarse) {
  .button { padding: 12px 20px; }  /* Larger touch target */
}

/* Device supports hover */
@media (hover: hover) {
  .card:hover { transform: translateY(-2px); }
}

/* Device doesn't support hover (touch) */
@media (hover: none) {
  .card { /* No hover state - use active instead */ }
}

Critical: Don’t rely on hover for functionality. Touch users can’t hover.

Safe Areas: Handle the Notch

Modern phones have notches, rounded corners, and home indicators. Use env():

body {
  padding-top: env(safe-area-inset-top);
  padding-bottom: env(safe-area-inset-bottom);
  padding-left: env(safe-area-inset-left);
  padding-right: env(safe-area-inset-right);
}

/* With fallback */
.footer {
  padding-bottom: max(1rem, env(safe-area-inset-bottom));
}

Enable viewport-fit in your meta tag:

<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">

Responsive Images: Get It Right

srcset with Width Descriptors

<img
  src="hero-800.jpg"
  srcset="
    hero-400.jpg 400w,
    hero-800.jpg 800w,
    hero-1200.jpg 1200w
  "
  sizes="(max-width: 768px) 100vw, 50vw"
  alt="Hero image"
>

How it works:

srcset lists available images with their actual widths (w descriptors)
sizes tells the browser how wide the image will display
Browser picks the best file based on viewport width AND device pixel ratio

Picture Element for Art Direction

When you need different crops/compositions (not just resolutions):

<picture>
  <source media="(min-width: 768px)" srcset="wide.jpg">
  <source media="(max-width: 767px)" srcset="tall.jpg">
  <img src="fallback.jpg" alt="...">
</picture>

Layout Adaptation Patterns

Three stages:

Mobile: Hamburger + drawer
Tablet: Horizontal compact
Desktop: Full with labels

Tables

Transform to cards on mobile using display: block and data-label attributes:

<table>
  <tr>
    <td data-label="Name">John Doe</td>
    <td data-label="Email">john@example.com</td>
  </tr>
</table>

@media (max-width: 640px) {
  table, thead, tbody, tr, th, td {
    display: block;
  }
  
  td::before {
    content: attr(data-label) ": ";
    font-weight: bold;
  }
}

Progressive Disclosure

Use <details>/<summary> for content that can collapse on mobile:

<details>
  <summary>Advanced options</summary>
  <div class="advanced-content">
    <!-- Collapsed by default on mobile -->
  </div>
</details>

Testing: Don’t Trust DevTools Alone

DevTools device emulation is useful for layout but misses:

Actual touch interactions
Real CPU/memory constraints
Network latency patterns
Font rendering differences
Browser chrome/keyboard appearances

Test on at least: One real iPhone, one real Android, a tablet if relevant. Cheap Android phones reveal performance issues you’ll never see on simulators.

Guidelines

DO

Use container queries (@container) for component-level responsiveness
Adapt the interface for different contexts—don’t just shrink it
Start mobile-first and layer complexity
Test on real devices, not just emulators
Use pointer and hover queries to detect input methods
Handle safe areas on notched devices

DON’T

Hide critical functionality on mobile—adapt the interface, don’t amputate it
Use desktop-first design
Do device detection instead of feature detection
Create separate mobile/desktop codebases
Ignore tablet and landscape orientations
Assume all mobile devices are powerful

⌘I

Frontend Design

Quality & Refinement

Enhancement

Structure & Flow

Setup

Mobile-First: Write It Right

Breakpoints: Content-Driven

Detect Input Method, Not Just Screen Size

Safe Areas: Handle the Notch

Responsive Images: Get It Right

srcset with Width Descriptors

Picture Element for Art Direction

Layout Adaptation Patterns

Navigation

Tables

Progressive Disclosure

Testing: Don’t Trust DevTools Alone

Guidelines

DO

DON’T

​Mobile-First: Write It Right

​Breakpoints: Content-Driven

​Detect Input Method, Not Just Screen Size

​Safe Areas: Handle the Notch

​Responsive Images: Get It Right

​srcset with Width Descriptors

​Picture Element for Art Direction

​Layout Adaptation Patterns

​Navigation

​Tables

​Progressive Disclosure

​Testing: Don’t Trust DevTools Alone

​Guidelines

​DO

​DON’T

Mobile-First: Write It Right

Breakpoints: Content-Driven

Detect Input Method, Not Just Screen Size

Safe Areas: Handle the Notch

Responsive Images: Get It Right

srcset with Width Descriptors

Picture Element for Art Direction

Layout Adaptation Patterns

Navigation

Tables

Progressive Disclosure

Testing: Don’t Trust DevTools Alone

Guidelines

DO

DON’T