Responsive design

Most responsive bugs are a layout that was designed at one width and then defended with media queries. Layouts that adapt on their own need fewer breakpoints and break in fewer places.

When this fires

Building or repairing any layout that will be seen at more than one width, and whenever a design hand-off shows a single desktop frame. It does not fire for the proving pass — screenshots, console and interaction checks belong to browser-verification.

Procedure

1. Let the content choose the breakpoints. Widen and narrow until the layout actually breaks — a line gets too long, a card squashes, a nav wraps badly — and put a breakpoint there. Device names are marketing; the content is the constraint.
2. Start from the small layout and add. Write the base styles for the narrow case, then use min-width queries to add complexity. Going the other way means every small screen pays to undo desktop rules, and undoing is where the leaks are.
3. Reach for intrinsic layout before a media query. flex-wrap, grid-template-columns: repeat(auto-fit, minmax(…, 1fr)), min()/max()/clamp(), and container queries where the component's size — not the viewport's — is what should drive it. A component that adapts to its own container survives being moved; a viewport-keyed one does not.
4. Make type fluid without breaking zoom. A clamp() with a rem term in the middle scales with the viewport and still responds to the user's font size and browser zoom. A size expressed in vw alone does not — it ignores zoom entirely, which is a genuine accessibility failure, not a stylistic choice. Keep an explicit floor and ceiling; line length around 45–75 characters.
5. Keep spacing on one scale. Fluid gutters and section padding from the same tokens as the type scale. Ad-hoc pixel values per breakpoint are how layouts drift apart over time.
6. Size targets for fingers, not cursors. 24×24 CSS px is the floor for any interactive target, with clear spacing between adjacent ones; make primary and frequently-tapped actions comfortably larger. Check the real hit area, not the icon — padding counts, a bare glyph does not.
7. Reflow, never remove. At narrow widths, content stacks, wraps, collapses into a disclosure or moves into a menu. It does not disappear. Anything only reachable on desktop is a feature that does not exist on mobile — if a design asks for that, stop and ask, because it changes what the product does rather than how it looks.
8. Handle media explicitly. Responsive images with srcset/sizes so small screens do not download desktop assets; an aspect-ratio or explicit dimensions so nothing jumps as images load; object-fit so crops behave. Long tables, code blocks and diagrams are the legitimate exception — give them their own horizontal scroll container rather than shrinking the page around them.
9. Distrust viewport units on mobile. 100vh is taller than the visible area while browser chrome is showing; prefer the dynamic/small viewport units with a plain fallback underneath. Where a layout goes edge to edge on a notched device, pad with the safe-area environment variables and set the viewport meta to cover — and never disable user scaling.
10. Do not tie behaviour to width. Wide does not mean mouse and narrow does not mean touch. Gate hover-only affordances on @media (hover: hover) and make sure anything revealed on hover has a tap or focus path too.
11. Check at sizes, not at one size. Walk 320, 375, 768, 1024 and 1440 CSS px, plus 1280 at 400% zoom — which is the same reflow constraint as 320 and catches the zoom bugs that resizing misses. Reload after each change, do not just drag the window: layout-time breakpoints, container query registration and device gates only re-run on load.
12. At every size, look for the same six things. Horizontal page scroll; clipped or overlapping content; text squeezed under ~40 characters or stretched past ~80; targets and their spacing; images loading at the right size with no jump; and whether the reading order still matches the visual order after items reflow.

Checklist

• Breakpoints correspond to where content broke, not to device names
• Base styles are the narrow case; complexity added with min-width
• Intrinsic layout used where it removes a media query
• Fluid type keeps a rem term, a floor and a ceiling; zoom still works
• Every interactive target is at least 24×24 CSS px with real spacing
• No content removed at small sizes — reflowed, collapsed or moved instead
• No horizontal page scroll at 320px; exceptions scoped to their own container
• Images sized responsively and reserve their space before loading
• 100vh assumptions and safe areas handled; scaling not disabled
• Hover-only affordances have a tap and focus equivalent
• Each width was reloaded, not just resized
• 1280 at 400% zoom checked alongside 320px

Failure handling

• Something overflows and the culprit is not obvious — find the element wider than its container before changing anything. Long unbroken strings, fixed pixel widths, negative margins and 100vw inside a padded parent cause most of it. Do not apply overflow: hidden to the page: it hides the symptom and clips content for everyone.
• The design only exists at one width — say which breakpoints you inferred and why, and get them confirmed. Inventing the mobile layout silently and calling it done is how two people ship two different products.
• A fix at one width breaks another — re-walk the whole set of widths after every fix, not just the one you were working on. This is the most common regression in this area.
• A third-party or embedded component will not reflow — contain it and its scroll, record it as a known limit, and do not claim the page reflows cleanly.
• You cannot open a browser — report the layout as changed but unchecked. Reading CSS is not checking layout, and resizing without reloading is not checking breakpoints.

Evidence to report

The widths walked and whether each was reloaded; a screenshot per width where the layout meaningfully differs; what overflowed or clipped and what fixed it; the breakpoints added or moved, with the content reason for each; the zoom result at 400%; and the sizes, states or components not checked. "Made it responsive" without the width list is not evidence — hand the rendered proof to browser-verification.