Breakpoints and layout

Design mobile first and add layout as the screen grows. Use Tailwind's five breakpoint names and values unchanged, so every developer and every AI agent already knows them.

BreakpointsCopy Anchor Link

• MUST write base styles for the phone and add min-width overrides upwards. No max-width media queries except for a one-off fix.
• MUST keep breakpoints in tokens (--breakpoint-md: 48rem in @theme). Never write @media (min-width: 812px) by hand.
• SHOULD change layout at no more than 3 breakpoints per page. Most pages need only md and lg.
• SHOULD use container queries for components that appear in different column widths. Tailwind v4 has them built in: @container on the parent, @md:grid-cols-2 on the child.

Test widthsCopy Anchor Link

Check every page at these widths before calling it done.

ContainersCopy Anchor Link

Three widths cover almost every page.

@theme {
  --container-prose: 65ch;
  --container-page: 1200px;
  --container-wide: 1440px;
}

.container-page {
  width: 100%;
  max-width: var(--container-page);
  margin-inline: auto;
  padding-inline: var(--gutter);
}

• MUST cap reading text at 65ch, even inside a wider container.
• MUST let backgrounds go full bleed and keep content inside the container. The section is wide; the text is not.
• SHOULD NOT add a fourth container width. Use a grid span instead.

Gutters and grid columnsCopy Anchor Link

The grid follows Material's responsive layout grid: 4 columns on phones, 8 on tablets, 12 on desktop.

:root {
  --gutter: 16px;
  --grid-cols: 4;
  --grid-gap: 16px;
}
@media (min-width: 40rem) { :root { --gutter: 24px; --grid-cols: 8;  --grid-gap: 24px; } }
@media (min-width: 64rem) { :root { --gutter: 32px; --grid-cols: 12; --grid-gap: 32px; } }

.grid-page {
  display: grid;
  grid-template-columns: repeat(var(--grid-cols), minmax(0, 1fr));
  gap: var(--grid-gap);
}

• MUST keep side gutters at 16px or more on phones. Text touching the screen edge is the most common phone bug.
• MUST use minmax(0, 1fr), not 1fr, for grid columns that hold text or code, so long content cannot force the column wider.
• SHOULD use 12 columns on desktop because it divides into halves, thirds, quarters and sixths.
• SHOULD span whole columns (col-span-8, col-span-4), never set widths like width: 63%.
• SHOULD use repeat(auto-fit, minmax(16rem, 1fr)) for card grids that should not need breakpoints at all.

Safe areas and viewport heightCopy Anchor Link

Phones have notches, rounded corners and home indicators. Opt in to the full screen, then pad away from the unsafe edges.

// app/layout.tsx (Next.js)
import type { Viewport } from 'next';

export const viewport: Viewport = {
  width: 'device-width',
  initialScale: 1,
  viewportFit: 'cover',
};

.site-header {
  padding-top: env(safe-area-inset-top);
  padding-inline: max(var(--gutter), env(safe-area-inset-left)) max(var(--gutter), env(safe-area-inset-right));
}

.bottom-bar {
  position: fixed;
  inset-inline: 0;
  bottom: 0;
  padding-bottom: calc(12px + env(safe-area-inset-bottom));
}

.hero { min-height: 100svh; }   /* small viewport: never jumps when the toolbar hides */
.app-shell { height: 100dvh; }  /* dynamic viewport: tracks the toolbar */

• MUST add env(safe-area-inset-bottom) to anything fixed to the bottom of the screen once viewport-fit=cover is set.
• MUST use max() so the gutter is never smaller than the normal 16px when the inset is 0.
• MUST NOT use 100vh for full-height layouts on phones. It is taller than the visible area while the browser toolbar shows. Use 100svh for heroes and 100dvh for app shells.
• MUST NOT use 100vw for full-bleed sections. It includes the scrollbar width on desktop and causes a horizontal scroll.

The 390px ruleCopy Anchor Link

Every page MUST work at 390px wide with no horizontal scroll. This is the house rule from the rules. Test it in the browser's device mode, then run this in the console:

[...document.querySelectorAll('*')].filter((el) => el.getBoundingClientRect().right > innerWidth + 1);

An empty array passes. Anything listed is wider than the screen. The usual causes and fixes:

• MUST check at 390px and at 320px, which is the WCAG reflow width.
• MUST keep inputs at 16px text so iOS does not zoom and shift the layout on focus.
• SHOULD use overflow-x: clip rather than hidden on wrappers, because clip does not create a scroll container and does not break position: sticky.

Group by proximityCopy Anchor Link

Related things sit close. Unrelated things sit far apart. The gap between groups should be about twice the gap within them. This does more for structure than any border or card.

• SHOULD allow asymmetry. A 1:2 split feels more designed than three equal columns.
• SHOULD give major sections 80 to 120px of vertical space on desktop.

Turn the overlay on. Every block lines up with a column edge and every line of text with the 8px baseline. Drop to 4 columns and the layout reflows by spanning whole columns.

Why it worksCopy Anchor Link

Shared breakpoint names mean "it breaks at md" is a complete bug report. A small, fixed set of containers and a column grid make alignment automatic, so edges line up across sections without anyone measuring. The 390px check catches the one failure that makes a site feel broken on the device most people will actually use.

SourcesCopy Anchor Link