Responsive layout

Matter's responsive strategy is mobile-first, container-query-first, with six canonical breakpoints for surface-level shifts. This page documents the rules that govern reflow.

The strategy in one paragraph

A component reflows when its container size changes. A page reflows when the viewport size changes. Components use container queries; pages use breakpoints. Touch targets stay ≥ 44×44 at every size. Compact density is orthogonal to viewport — a user can be compact on a phone or comfortable on a 4K display, and both shapes work.

When to use container queries

Every component grid and inline-card row uses container queries. The card grid inside the dashboard sidebar reflows independently from the card grid in the main column because each grid has its own container.

.card-grid {
  container-type: inline-size;
  display: grid;
  grid-template-columns: 1fr;
  gap: 16px;
}

@container (min-width: 480px) {
  .card-grid {
    grid-template-columns: repeat(2, 1fr);
  }
}

@container (min-width: 720px) {
  .card-grid {
    grid-template-columns: repeat(3, 1fr);
  }
}

The container-type: inline-size declares the element as a query container; descendant @container queries match against the container's inline size. No JavaScript, no resize observers, no viewport math.

When to use breakpoints

Three page-level shifts justify viewport breakpoints:

1. Sidebar / drawer toggle. The dashboard's sidebar is full at lg and up; below lg, it collapses to a drawer triggered by a hamburger.
2. Rail activation. Rails (right-side panels) appear at xl and up. Below xl, rail content moves into a tab on the main column.
3. Hero typography clamps. clamp(min, vw, max) handles intra-breakpoint scaling. The 2xl breakpoint is where the clamp's max engages.

Beyond these three shifts, prefer container queries. The dashboard's per-card layout, the cap-table donut, the agenda list — all use container queries.

Touch-target floor

The floor never drops. Compact density tightens spacing around the touch target via outer padding; the click-receptive area remains 44×44 via inline padding and negative margins. This is the WIG touch rule and Matter enforces it across every interactive component.

Compact density × viewport

The two axes are independent. Below is the matrix:

Compact is the right choice for dense data surfaces (cap-table grids, audit logs, file listings) regardless of viewport. Comfortable is the right choice for marketing surfaces and reading-heavy contexts.

Below xs (narrowest)

Below 360px, Matter does not optimise. Screens render at fixed 360px with horizontal scroll. The dashboard is functional but visually pinched. We don't ship custom breakpoints below xs because:

• Below 360px, we're optimising for a vanishingly small audience.
• The cost of "tight layout below 320px" is design debt that outweighs the gain.

If you need narrower support, propose it via Governance.

Reflow patterns by component

Implementation: testing reflow

# Open Chrome devtools, toggle device toolbar (Cmd+Shift+M)
# Step through: 320 / 360 / 640 / 768 / 1024 / 1280 / 1536 / 1920
# Verify at each width:
#   1. Touch targets remain ≥ 44×44
#   2. Text doesn't overflow or clip
#   3. Sidebar / rail behaves per the breakpoint table
#   4. Container-query components reflow independently

Every component MDX page renders at three previews (light/dark/forced-colors) — but the reflow test is on you to walk through manually. Automated visual regression at every breakpoint × density × theme is a tranche-4 item.

Anti-patterns