Responsive Web: mobile-first, any stack, verified
The goal is a layout that works at every width, not at five device widths someone picked.
Bugs live in between: 412px, 905px, the one pixel where max-width: 767px and min-width: 769px both
stop applying. So this skill has two halves that always go together:
- Build mobile-first: write the layout so it adapts on its own and needs few breakpoints.
- Prove it: run
scripts/check_responsive.py, which renders the page and measures the layout at every width. "Looks fine to me" from a screenshot or two doesn't count as proof. Done means the checker reports 0 errors.
The checker only sees the rendered page (DOM boxes and computed styles), so it does not care how the CSS was written. That is what makes this work for any technology.
0. Read the project first
Before writing CSS, spend a minute finding:
- How styles are written here: Tailwind (
tailwind.config.*or@themein CSS), Bootstrap/SCSS variables, CSS modules, styled-components/emotion, Vue/Svelte scoped styles, plain CSS files. Write new code in the same system with the same tokens. A second styling system is a maintenance bug. - The existing breakpoints, and reuse them. Don't invent new ones unless the content needs one.
- How to see the page: a static
.htmlfile, or a dev server (npm run dev,php artisan serve,python manage.py runserver,rails s,dotnet watch...). You need a URL or file path for the checker.
references/stacks.md shows the mobile-first syntax and breakpoint location for common stacks.
1. Build mobile-first
Write base styles for the smallest screen, with no media query. Add layout as space grows, using
min-width queries. Phones get the simplest CSS, content stacks naturally, and each breakpoint only
adds things. The desktop-first way (write desktop, then patch down with max-width) leaves gaps
between the patches, and those gaps are where most responsive bugs come from.
If the codebase is already desktop-first, don't rewrite it. Write your new or changed parts mobile-first inside its conventions, and fix what the checker finds.
Prefer layouts that adapt without breakpoints
- Grids:
grid-template-columns: repeat(auto-fit, minmax(min(100%, 16rem), 1fr)). Columns appear as space allows, with no breakpoint and no overflow at 320px (themin(100%, …)part is what prevents it). - Rows that should wrap:
display: flex; flex-wrap: wrap; gap: …with a sensibleflex-basis. - Sizes:
width: 100%; max-width: 40reminstead ofwidth: 640px. Fluid type and spacing withclamp(min, preferred, max). - A component that appears in slots of different widths (sidebar vs. main column): use container
queries (
container-type: inline-size+@container), so it responds to its slot, not the window. - Add a breakpoint where the content breaks (narrow the window until something looks wrong), not at a device width.
Known layout breakers. Check each one when you write it.
| Breaker | Why it breaks | Use instead |
|---|---|---|
fixed width/min-width in px on containers | wider than a 320px phone | max-width + width:100%, %, fr, minmax() |
| flex/grid child with long content | children default to min-width: auto and refuse to shrink | min-width: 0 on the child (or minmax(0,1fr)) |
| long words, URLs, emails, codes | no break opportunity | overflow-wrap: anywhere on text containers |
white-space: nowrap on buttons/labels/nav | text can't wrap, pushes width | allow wrap, or ellipsis with min-width:0 + a title |
| images, video, iframes, embeds | intrinsic width > screen | max-width:100%; height:auto; aspect-ratio for embeds |
| tables | columns can't shrink below content | wrap in overflow-x:auto container, or stack rows on small screens |
pre/code blocks | preserved whitespace | overflow-x:auto on the block |
100vw | includes the scrollbar, so it's ~15px too wide on desktop | 100% (or 100dvw only for true full-bleed with care) |
fixed height on boxes with text | text wraps to more lines on phones and spills/clips | min-height, or no height |
| absolute positioning of content | doesn't take space; collides at other widths | normal flow/grid; absolute only for decoration |
height: 100vh heroes | mobile browser bars and short landscape screens cut it | min-height: 100svh (with 100vh fallback before it) |
Never hide the symptom
- No
overflow-x: hiddenonhtml/bodyto stop sideways scrolling. It hides the bug while content is still cut off (and it breaksposition: sticky). Find the element that is too wide. The checker reports this masking asclipped-offscreen. - No
user-scalable=noormaximum-scale=1. Blocking zoom is an accessibility failure (WCAG 1.4.4). - No JavaScript width checks or user-agent sniffing for layout. CSS media/container queries do it
without flicker. JS is fine for behaviour (
matchMedia), not for layout. - Don't change the test to pass it (raising
--min, adding ignores to make errors disappear).
Touch, input, viewport
<meta name="viewport" content="width=device-width, initial-scale=1">in every page head.- Tap targets at least 24x24px (WCAG 2.2 AA). Aim for 44x44px for buttons and icon controls on touch screens, and keep space between neighbours.
- Hover-only UI (menus, tooltips that reveal content) needs
@media (hover: hover)and a tap alternative. - Form fields
font-size: 16pxor more on phones, otherwise iOS Safari zooms in on focus. Use propertype,inputmode, andautocomplete. - Short landscape phones (320–430px tall) are real. Sticky headers plus cookie banners shouldn't cover
more than about a third of the screen. Collapse or shrink them on short heights
(
@media (max-height: 500px)). - Notched devices: use
env(safe-area-inset-*)padding only together withviewport-fit=cover.
Typography, media, navigation, content
remfor type,clamp()for headings, line length capped (max-width: 65chor so), unitless line-height.- Images:
srcset/sizesfor photos,width/heightattributes oraspect-ratioto avoid layout shift,object-fit: coverwhen the box ratio differs from the image (otherwise it stretches). - Navigation: on small screens use a real
<button>witharia-expanded/aria-controlsthat opens the menu. Show inline links from the width where they actually fit. - Keep content parity: don't drop content on mobile because it was hard to fit. Reorder, condense, or collapse it.
references/patterns.md has copy-ready CSS for each of these (grid, nav, table, form, hero, cards, media).
2. Verify: run the checker
One-time setup (Python 3.9+):
pip install playwright
python -m playwright install chromium
Run it against the rendered page. Start the dev server first if there is one.
python <skill-dir>/scripts/check_responsive.py http://localhost:5173/ --out responsive-report
python <skill-dir>/scripts/check_responsive.py site/index.html --out responsive-report # static file
- Several pages: pass several URLs. Check every page or route you changed, plus one that uses the shared layout (header/footer).
- SPA that renders late:
--wait-for "#app main". Logged-in pages:--storage-state state.json. - Inner loop while fixing:
--quick(~5–10 s). Run a full run before you say you're done (~20–40 s per page). - Exit code: 0 = no errors, 1 = errors found (or warnings with
--strict), 2 = could not run.
What it does: sweeps 320→1920px in 10px steps plus common device widths plus both sides of every breakpoint found in the page's own CSS. It reloads key widths with real mobile emulation (touch, meta viewport) and checks four short landscape phones. At each width it measures:
| Error (must fix) | Meaning |
|---|---|
horizontal-overflow | page scrolls sideways; names the element that sticks out and what forces it wide |
clipped-offscreen | content cut off at the screen edge (often hidden by overflow-x:hidden on body) |
occluded-target | a link/button is covered by another element (or by a fixed bar at every scroll position) |
small-target | tap target under 24px and crowded by neighbours |
text-spill / text-clipped | text runs out of its box / is cut by a fixed size + overflow:hidden |
text-overlap | text of two unrelated blocks drawn on top of each other |
distorted-media | image/video stretched (box ratio ≠ natural ratio, no object-fit) |
viewport-meta, layout-viewport | missing/zoom-blocking viewport meta; phone renders at desktop width |
Warnings (fix them or explain why not): touch-target (<44px controls on touch widths), small-text
(<12px on phones), input-zoom (<16px inputs), fixed-coverage (fixed/sticky bars >35% of a short screen).
The report (report.md, report.json) groups findings like this:
1. **horizontal-overflow** at 320-610px; 568x320 - `body > main.wrap > div.promo` "Fresh coffee..."
- worst: 296 px past right edge at 320px
- clues: stays exactly 600px wide at every failing width: a fixed width - use max-width/%/fr/minmax instead
- close-up: responsive-report/closeups/01-horizontal-overflow-320.png
The clues line is the diagnosis. Read it before you open the CSS.
3. Fix loop
- Fix the smallest failing width first. Mobile is the foundation, and fixing it often fixes the rest.
- Fix the root cause the clues point to, in the source the project uses (the Tailwind class, the
SCSS partial, the styled component), not with a one-off override.
references/checks.mdlists causes and fixes for each check. - Re-run (
--quick), repeat, then do a full run. Stop when there are 0 errors and every warning is fixed or has a reason. - Something intentionally breaks a rule (a decorative shape bleeding off-screen, a deliberate overlap
in a hero collage)? Mark that element
data-responsive-ignore="text-overlap"(space-separated check names) and add a comment in the code saying why. Ignoring real content to get a green run is the same as not testing.
4. Look at it
The checker finds what is measurably broken. Some problems aren't measurable: awkward wraps (one
orphan word on a button), a lonely last grid item, huge empty gutters at 1920px+, an image crop that
cuts off the subject, a menu that's technically fine but hard to use. Open the screenshots the run
saved (screens/320.png, 375, 768, 1024, 1440 and the closeups/) and look at them. If you
can't view images, say so in the report instead of claiming visual review.
When you report visual problems to the user, describe elements by what and where they are ("the price badge on the product photo", "the second card in the menu grid"), not by class names. Users don't read DOM selectors. Keep the selectors in your own notes for finding the code.
5. Audit-only requests
If the user asks to check or audit a site (not fix it), run the full checker first and report findings grouped by severity and width range, with screenshots, before touching code. Ask before fixing if the scope is large.
6. Tell the user what was verified
End with a short, factual summary:
- what you changed (files, components);
- what was tested: pages,
N widths 320–1920px, landscape phones; checker result (0 errors, 1 warning); - each remaining warning and why it stays;
- where the screenshots are;
- what was not verified. The checker uses Chromium only, so Safari/Firefox quirks, real-device keyboards, text-only 200% zoom, RTL, and pages behind login without a storage state aren't covered unless you tested them separately.
Reference files
references/patterns.md: copy-ready mobile-first CSS for common building blocks. Read it when building a new layout or component.references/stacks.md: how mobile-first and breakpoints look in Tailwind, Bootstrap, SCSS, CSS modules, CSS-in-JS, MUI/Chakra, Vue/Svelte/Angular, server templates, plus how to serve each for the checker.references/checks.md: every checker finding with typical causes, fixes, and known false positives. Read it when a finding's cause isn't obvious.scripts/selftest/run_selftest.py: proves the checker still catches each bug type (14 fixtures). Run it after editing the checker.