Layout guide

Responsive Layouts Start with Content

Begin at the narrowest width your users need. Let labels, controls, and reading order determine when the layout should change.

Choose the layout model

CSS Grid is suited to two-dimensional placement: card collections have both rows and columns. Flexbox arranges one-dimensional groups such as a toolbar that wraps. Choose the simplest model that follows the content.

Set a breakpoint where the actual content stops fitting comfortably. Start narrow, increase the available width, and observe where labels collide, cards become too narrow, or controls wrap awkwardly. Avoid choosing breakpoints only because they match popular device names.

Worked example: cards and toolbar

The grid listing auto-fits cards at a 17rem minimum and collapses to one column when only one fits. The toolbar uses Flexbox because its controls form a single group; it wraps as space runs out. The final button uses an auto margin to move to the far edge when a row has room, while remaining in DOM order.

html
<section class="cards card-list" aria-label="Recent projects">
  <article class="card"><h2>North Star</h2><p>Research and planning</p></article>
  <article class="card"><h2>Open Studio</h2><p>Tools for the whole team</p></article>
  <article class="card"><h2>Field Notes</h2><p>Updates from the project</p></article>
</section>
<nav class="toolbar" aria-label="Project actions">
  <a href="#overview">Overview</a><a href="#files">Files</a><button>New project</button>
</nav>
css
* { box-sizing: border-box; }
.cards { display: grid; grid-template-columns: repeat(auto-fit, minmax(min(100%, 17rem), 1fr)); gap: 1rem; }
.card { min-width: 0; padding: 1.25rem; border: 1px solid #cbd5e1; border-radius: 1rem; }
.card h2 { overflow-wrap: anywhere; }
.toolbar { display: flex; flex-wrap: wrap; align-items: center; gap: .5rem; margin-block: 1.5rem; }
.toolbar a, .toolbar button { padding: .65rem .9rem; }
.toolbar button { margin-inline-start: auto; }

/* Fallback: keep controls inside their containing block. */
.card-list { container-type: inline-size; }
@supports (container-type: inline-size) {
  @container (min-width: 42rem) { .card { padding: 1.75rem; } }
}
@media (min-width: 48rem) { .card { padding: 1.5rem; } }

Try adjusting the fluid spacing with the CSS Clamp Calculator. The examples use a narrow-first default and only add a wider card padding when the card’s container has room.

Viewport and container queries

A viewport media query responds to the browser window. A container query responds to the space available to a component, so the same card can adapt in a sidebar or a full-width page. Set `container-type: inline-size` on an ancestor before using `@container`. The padding change above has a viewport fallback; browsers that do not support container queries still get a usable fluid grid and toolbar.

Responsive review checklist

  • Check narrow widths such as 320px and 360px.
  • Use long labels and translated text to reveal wrapping issues.
  • Zoom text to 200% and verify controls remain reachable.
  • Check horizontal overflow at page and component level.
  • Preserve meaningful DOM and keyboard order when visual layout changes.
  • Verify the examples in both themes and with keyboard input.