CommunityCoding & Developmentgithub.com

responsive-web

Coding skill. Build and verify web UIs that hold up at every screen width (320px phones to 2560px monitors) using a mobile-first approach that works with any stack: plain CSS, Tailwind, Bootstrap, SCSS, CSS modules, CSS-in-JS, React/Vue/Svelte/Angular, or server-rendered templates. Ships a Playwright checker that sweeps 150+ widths plus landscape phones and measures real layout breakage: horizontal scroll, cut-off or overlapping text, covered or tiny tap targets, stretched images, missing or zoom-blocking

What is responsive-web?

responsive-web is a Claude Code agent skill that coding skill. Build and verify web UIs that hold up at every screen width (320px phones to 2560px monitors) using a mobile-first approach that works with any stack: plain CSS, Tailwind, Bootstrap, SCSS, CSS modules, CSS-in-JS, React/Vue/Svelte/Angular, or server-rendered templates. Ships a Playwright checker that sweeps 150+ widths plus landscape phones and measures real layout breakage: horizontal scroll, cut-off or overlapping text, covered or tiny tap targets, stretched images, missing or zoom-blocking.

Works with~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/isikenes35/responsive-web/tree/HEAD

Installed? Explore more Coding & Development skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Ask in your favorite AI

Open a new chat with this agent skill pre-loaded.

Documentation

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:

  1. Build mobile-first: write the layout so it adapts on its own and needs few breakpoints.
  2. 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 @theme in 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 .html file, 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 (the min(100%, …) part is what prevents it).
  • Rows that should wrap: display: flex; flex-wrap: wrap; gap: … with a sensible flex-basis.
  • Sizes: width: 100%; max-width: 40rem instead of width: 640px. Fluid type and spacing with clamp(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.

BreakerWhy it breaksUse instead
fixed width/min-width in px on containerswider than a 320px phonemax-width + width:100%, %, fr, minmax()
flex/grid child with long contentchildren default to min-width: auto and refuse to shrinkmin-width: 0 on the child (or minmax(0,1fr))
long words, URLs, emails, codesno break opportunityoverflow-wrap: anywhere on text containers
white-space: nowrap on buttons/labels/navtext can't wrap, pushes widthallow wrap, or ellipsis with min-width:0 + a title
images, video, iframes, embedsintrinsic width > screenmax-width:100%; height:auto; aspect-ratio for embeds
tablescolumns can't shrink below contentwrap in overflow-x:auto container, or stack rows on small screens
pre/code blockspreserved whitespaceoverflow-x:auto on the block
100vwincludes the scrollbar, so it's ~15px too wide on desktop100% (or 100dvw only for true full-bleed with care)
fixed height on boxes with texttext wraps to more lines on phones and spills/clipsmin-height, or no height
absolute positioning of contentdoesn't take space; collides at other widthsnormal flow/grid; absolute only for decoration
height: 100vh heroesmobile browser bars and short landscape screens cut itmin-height: 100svh (with 100vh fallback before it)

Never hide the symptom

  • No overflow-x: hidden on html/body to stop sideways scrolling. It hides the bug while content is still cut off (and it breaks position: sticky). Find the element that is too wide. The checker reports this masking as clipped-offscreen.
  • No user-scalable=no or maximum-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: 16px or more on phones, otherwise iOS Safari zooms in on focus. Use proper type, inputmode, and autocomplete.
  • 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 with viewport-fit=cover.

Typography, media, navigation, content

  • rem for type, clamp() for headings, line length capped (max-width: 65ch or so), unitless line-height.
  • Images: srcset/sizes for photos, width/height attributes or aspect-ratio to avoid layout shift, object-fit: cover when the box ratio differs from the image (otherwise it stretches).
  • Navigation: on small screens use a real <button> with aria-expanded/aria-controls that 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-overflowpage scrolls sideways; names the element that sticks out and what forces it wide
clipped-offscreencontent cut off at the screen edge (often hidden by overflow-x:hidden on body)
occluded-targeta link/button is covered by another element (or by a fixed bar at every scroll position)
small-targettap target under 24px and crowded by neighbours
text-spill / text-clippedtext runs out of its box / is cut by a fixed size + overflow:hidden
text-overlaptext of two unrelated blocks drawn on top of each other
distorted-mediaimage/video stretched (box ratio ≠ natural ratio, no object-fit)
viewport-meta, layout-viewportmissing/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

  1. Fix the smallest failing width first. Mobile is the foundation, and fixing it often fixes the rest.
  2. 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.md lists causes and fixes for each check.
  3. Re-run (--quick), repeat, then do a full run. Stop when there are 0 errors and every warning is fixed or has a reason.
  4. 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.

Related Skills