Responsive Layout

Typography responsiveness

• Step heading sizes per breakpoint: text-3xl md:text-5xl rather than one fixed size. If the design calls for continuous scaling, do it through a token-defined clamp(), not an ad hoc one in a className.
• <input>/<textarea> text stays ≥16px (text-base) on phone — smaller triggers iOS's auto-zoom on focus, which is its own kind of layout break.

Navigation

• ≥5 top-level links collapse below md into a menu button (aria-expanded, aria-controls) opening a Radix Dialog/Sheet or disclosure panel; it closes on link click and Escape.
• Sticky header: sticky top-0 z-20 (z-20 is the sticky-header band of the fixed z-scale: 10 raised · 20 sticky header · 30 dropdown · 40 overlay · 50 modal/toast). Anchored sections under it need scroll-mt-20 (or whatever matches the header's height) so #section links don't land underneath it.
• Fixed/sticky bars respect env(safe-area-inset-*) so they don't sit under a notch or home indicator.
• Mobile menu requirements: trigger button with aria-expanded/aria-controls, Radix Dialog/Sheet for the panel (focus trap and body scroll lock come free), closes on link click and Escape.

Touch

• Targets ≥44×44px on phone (min-h-11 min-w-11 or padding to reach it), ≥24px on desktop.
• ≥8px between adjacent targets so a miss-tap doesn't hit the neighbor.
• No hover-only functionality — anything a mouse user reaches by hovering needs a tap-accessible equivalent; gate hover-only niceties behind @media (hover: hover) so touch devices don't get a stuck hover state.
• touch-action: manipulation on interactive elements removes the ~300ms double-tap-to-zoom delay.

Images & media

• Responsive sourcing: srcset/sizes, or <picture> with art-directed breakpoints, so phones don't download the desktop asset.
• loading="lazy" below the fold; the hero/LCP image stays eager.
• aspect-* (or explicit width/height) reserves the box before the image loads, preventing layout shift.

Worked Example

A pricing comparison section, written desktop-first, has three overflow bugs:

// ❌ desktop-first: three columns, a fixed-width badge, and a long plan name that doesn't wrap
<section className="grid grid-cols-3 gap-6 p-8">
  {plans.map(plan => (
    <div key={plan.id} className="border p-6">
      <div className="flex gap-2">
        <h3 className="font-semibold">{plan.name}</h3>
        <span className="whitespace-nowrap rounded bg-primary px-2 py-1 text-primary-foreground">
          Most popular
        </span>
      </div>
      <div className="w-[280px] mt-4">{plan.description}</div>
    </div>
  ))}
</section>

Bug 1: grid-cols-3 with no mobile step — three ~110px columns at 360px. Bug 2: the h3 + whitespace-nowrap badge are flex siblings with no min-w-0, so a long plan name pushes the badge (and the row) past the viewport edge. Bug 3: w-[280px] is wider than the phone viewport itself.

// ✅ mobile-first: one column on phone, badge wraps with the title, fluid width
<section className="grid grid-cols-1 gap-6 p-4 sm:grid-cols-2 lg:grid-cols-3 lg:p-8">
  {plans.map(plan => (
    <div key={plan.id} className="border p-6">
      <div className="flex min-w-0 flex-wrap items-center gap-2">
        <h3 className="min-w-0 break-words font-semibold">{plan.name}</h3>
        <span className="shrink-0 rounded bg-primary px-2 py-1 text-primary-foreground">
          Most popular
        </span>
      </div>
      <div className="mt-4 w-full max-w-sm">{plan.description}</div>
    </div>
  ))}
</section>

Common Mistakes

• Starting a layout at 1440px and adding max-*:/media-query patches to make it survive at 360px.
• w-screen on anything that isn't a direct, unpadded child of body.
• Fighting Tailwind v4's image preflight with max-w-none instead of sizing the image on purpose.
• grid-cols-N/flex rows with no mobile step, found only when real (long) content is dropped in.
• overflow-x-clip/hidden on body to "fix" an overflow instead of finding and fixing the element causing it.

Red Flags

• Any unprefixed grid-cols-2/grid-cols-3/grid-cols-4 on a page-level grid.
• w-[, h-screen, or w-screen anywhere in the diff.
• A flex/grid item holding truncate or whitespace-nowrap text with no min-w-0 on an ancestor in the same flex/grid context.
• A <table> with no overflow-x-auto wrapper and no stacked-card fallback.
• A component never rendered with a long/realistic string before hand-off.