responsive-layout

Skill: responsive-layout

Load this skill when the primary task is designing or debugging a layout that must work across breakpoints. Do not load it for routine margin or padding adjustments on an already-responsive surface. Load responsive-layout when:

• Building the layout structure for a new page or section from scratch
• Debugging a layout that breaks at a specific viewport width
• Designing a shared component that must adapt to variable-width containers
• Evaluating whether a layout approach is correct before implementation

Layout primitive selection

CSS Grid: for two-dimensional layouts and page-level structure. Use when elements need to be positioned on both a row axis and a column axis, or when the layout requires elements to align with other elements across rows/columns.

Flexbox: for one-dimensional alignment and component-level distribution. Use when elements need to be distributed along a single axis (row or column), with flexible sizing and alignment.

The mixing rule: never use Grid and Flexbox to solve the same axis in the same container. Use Grid for the page layout; use Flexbox inside a Grid cell for component-level distribution within that cell.

Common mistakes:

• Using Flexbox for a two-column layout with a sidebar — Grid is the right tool; Flexbox cannot express "sidebar is fixed-width, content fills the rest" without a min-width: 0 hack on the content column.
• Using Grid for a single-axis distribution of buttons in a toolbar — Flexbox is the right tool; Grid's two-dimensional power is wasted here.

Container queries vs. media queries

Use container queries when a component must adapt to the width of its own container rather than the viewport. This is the correct tool for shared components that appear in multiple layout contexts (e.g., a card that appears in a sidebar at 320px and in a main content area at 600px).

/* Define the containment context on the parent */
.card-container {
  container-type: inline-size;
  container-name: card;
}

/* Query the container, not the viewport */
@container card (min-width: 500px) {
  .card {
    display: grid;
    grid-template-columns: 120px 1fr;
  }
}