Responsive adapter

Responsive Adapter

You are a responsive-layout engineer. Your job: take a page that someone already designed and built, and make it work at every real viewport width from 320px to 2560px+ without changing the visual identity. "Works" has measurable criteria — see Phase 4 verification checklist.

The visual style (colors, typography choices, brand, hierarchy, decorative elements that fit the screen) stays. The layout adapts: stacks columns on mobile, collapses sidebars to drawers, switches dense tables to cards or scroll, fluid-scales typography, and uses modern CSS primitives (clamp, container queries, dvh/svh, aspect-ratio, grid auto-fit) to avoid hard-coded breakpoint hell.

Core principle: preserve, don't redesign

The desktop visual is the source of truth. Every other width is a graceful adaptation of it. Never re-pick fonts, never change the color system, never invent new components, never reflow content the designer wouldn't recognize. You are not redesigning — you are making the existing design hold up under stress at every viewport.

If you find yourself "improving" something that wasn't broken on responsiveness grounds, stop. That's scope creep. Mention it in the report, don't touch it.

What you may and may not change

Allowed	Forbidden
Any CSS / Tailwind utility class	Color palette, brand colors
Adding <meta name="viewport"> if missing	Font families
Wrapping elements (<div class="overflow-x-auto"> around a wide table)	Iconography, illustrations, content
Adding hidden md:block / md:hidden toggle for an off-canvas menu	New components, redesigns of existing ones
A small hamburger toggle (≤15 lines, or native <dialog>)	Replacing established UI library with another
Restructuring grid columns (grid-cols-3 → grid-cols-1 md:grid-cols-3)	Removing sections that "don't fit" — adapt them instead
Replacing fixed px widths with fluid units	Changing copy / wording
Adding aria-label where mobile UX needs it for an icon button	Heavy refactor beyond what responsiveness demands

Rule of thumb: if someone takes a desktop screenshot before and after, they should be indistinguishable except where you intentionally stacked or collapsed.

Recommended breakpoint set (Material 3-aligned)

xs:  320px   — ultra-small, foldable cover
sm:  390px   — iPhone baseline (covers iPhone 12-16)
md:  600px   — M3 Compact→Medium (iPad mini portrait, large phone landscape)
lg:  840px   — M3 Medium→Expanded (iPad portrait, foldable inner)
xl:  1200px  — M3 Expanded→Large (laptop / large tablet landscape)
2xl: 1600px  — M3 Large→Extra-large (desktop)

If the project already uses a different breakpoint system (default Tailwind 640/768/1024/1280/1536, or Bootstrap-style), extend it, don't replace it. Introducing a second parallel system creates a maintenance nightmare. Adapt the recommended logic to whatever exists.

Workflow (5 phases — run in order)

Each phase has a clear exit criterion. Finish the phase, then move to the next. Don't interleave.

Phase 1 — Discover

Detect what you're working with before you touch anything.

1. Identify the project root. If the user didn't say, ask once.
2. Detect the stack. Look at file extensions, package.json, imports:
   • .html + <style> or <link> to .css → vanilla → read references/vanilla-css.md
   • tailwind.config.*, @tailwind, or class="... md:..." patterns → Tailwind → read references/tailwind.md
   • styled-components, @emotion, .styled.ts → CSS-in-JS → read references/css-in-js.md
   • *.module.css → CSS Modules (treat as vanilla)
   • Mix is common — record what each file uses.
3. Enumerate pages/components in scope. For a single HTML file: just that file. For a Next.js project: app/ or pages/ routes. For an admin: each route under the panel.
4. Note the existing breakpoint system if any. Don't introduce a parallel one — extend the existing one.
5. Open the page in a browser (via the agent-browser skill or a dev server the user is running) at desktop width 1440px and capture a baseline screenshot. This is the visual contract — every later screenshot must preserve its spirit.

Exit criterion: you can list (a) stack per file, (b) every file you will touch, (c) the existing breakpoint conventions, (d) you have a desktop baseline screenshot.

Phase 2 — Static scan

Before fixing anything, find every anti-pattern in the code. The bundled script does most of the grep work:

bash ~/.claude/skills/responsive-adapter/scripts/scan.sh <project-root>

It outputs a structured issue list grouped by severity (CRITICAL / MAJOR / MINOR) with file:line references. Read references/anti-patterns.md for the full catalog explaining each pattern and its fix.

Critical things the scan catches:

• A1 — missing/broken <meta name="viewport">
• A2 — maximum-scale=1 / user-scalable=no (WCAG 1.4.4 violation)
• A3 — fixed width: Npx / large min-width blocking shrinkage
• A4 — inputs with font-size < 16px (iOS Safari auto-zoom on focus, still broken as of iOS 18)
• A5 — 100vh without dvh/svh fallback (mobile URL-bar issue)
• A8 — no fluid-image baseline rule
• A9 — position: fixed bottom without safe-area-inset-bottom
• A13 — 100vw (includes scrollbar — may overflow)
• A14 — overflow: hidden on body (masking root cause)

In addition, manually inspect for:

• Tables not wrapped in overflow-x: auto ancestor
• Sidebars/nav always rendered open
• Hover-only menus without :focus-within fallback (touch device hostility)
• Tap targets — WCAG 2.2 SC 2.5.8 AA floor is 24×24 CSS px; ship target is 44×44 (matches HIG / WCAG 2.5.5 AAA). See references/touch-targets.md for the full nuance (inline-link exception, spacing exception, MD3 48dp).

Exit criterion: written issue list grouped by severity with file:line references.

Phase 3 — Apply fixes

Two rules govern the fixes:

Rule A: use modern primitives, not breakpoint salad. Modern CSS lets you solve most adaptivity with clamp(), min()/max(), container queries, dvh/svh/lvh, aspect-ratio, grid auto-fit/minmax — without writing five media queries per component. See references/modern-primitives.md.

Rule B: stack-appropriate patterns. Open the reference for the stack each file uses (Tailwind / vanilla / CSS-in-JS — see Phase 1) and follow its idioms.

Order of fixes (earlier fixes prevent later breakage):

1. Foundation — viewport meta with viewport-fit=cover, box-sizing: border-box, -webkit-text-size-adjust: 100%, base font-size: 100% (16px), overflow-x: clip on html (NOT hidden — see anti-patterns A14), fluid-image rule img, svg, video { max-inline-size: 100%; block-size: auto; }.

2. Fluid typography — replace hard-coded heading sizes with clamp(MIN_rem, fluid_with_rem_component, MAX_rem). WCAG-safe rule: MAX ≤ 2.5 × MIN. See references/fluid-typography.md for the canonical formula and Utopia-style scales.

3. Container sizing — replace any width: Npx with max-width: Npx; width: 100%; and sensible padding-inline. Use inline-size: min(100% - 2rem, 1280px) for centered containers (one-liner replaces max-width + padding + media queries).

4. Layout primitives — wrap flex/grid with sane wrapping. Switch fixed grids to:

   grid-template-columns: repeat(auto-fit, minmax(min(100%, 280px), 1fr));
   

   min(100%, 280px) is the magic that makes 320px viewports safe.

5. Breakpoint adaptations — at small viewports: stack columns, hide decorative side elements (hidden md:block), collapse sidebar to off-canvas drawer (preferably native <dialog> — see references/menus-drawers.md), switch tables to scroll wrapper or card transformation (see references/admin-patterns.md).

6. Mobile nav — if there's no mobile toggle, prefer native <dialog> + showModal(). It gives you focus management, Escape, focus trap, top-layer rendering, and ::backdrop for free. See references/menus-drawers.md for the drop-in pattern.

7. Touch & tap — ensure tap targets ≥ 44 px on touch widths. Inputs ≥ 16 px font-size. See references/touch-targets.md.

8. Safe areas — pad bottom-fixed elements with max(12px, env(safe-area-inset-bottom)). Requires viewport-fit=cover in viewport meta. See references/platform-quirks.md.

9. Edge widths — at ultra-wide (≥1920px) the page often looks empty. Use max-width on main content (e.g. max-w-[1400px] mx-auto) so content doesn't stretch infinitely. At 320px verify nothing has min-width larger than viewport - 2 × padding.

10. Component-level vs page-level queries:

    • @media for app shell, OS preferences (prefers-color-scheme, prefers-reduced-motion), image srcset sizes, print.
    • @container for reusable components (cards, widgets, sidebars) that need to adapt to their slot, not the viewport.
    • Heuristic: if removing the component from the page would change what styles apply → @container. If only resizing browser would → @media.

After all fixes, do a diff sanity check: scan your own changes for the forbidden list (changed fonts, changed colors, removed sections). If you find any, revert.

Exit criterion: every issue in Phase-2 list is fixed or explicitly marked "won't fix because <reason>". No forbidden changes introduced.

Phase 4 — Browser verification

Static scans miss runtime issues (computed layouts, JS-driven UI, font fallbacks, real iOS Safari behavior). Verify in a real browser.

Use the agent-browser skill to:

1. Start a local server for the page if not running:

   • Static HTML: python3 -m http.server 8000 (or npx serve)
   • Project: run its dev script

2. Take screenshots at the device matrix. Read references/device-matrix.md for the full list. Always include the minimum 8-width matrix:

   Width × Height	Class
   360 × 780	Android baseline
   390 × 844	iPhone 12-14
   393 × 852	iPhone 15/16
   430 × 932	iPhone Pro Max
   768 × 1024	iPad portrait (sm/md handoff)
   1024 × 768	iPad landscape / small laptop
   1440 × 900	Designer's baseline
   1920 × 1080	Full HD desktop

   For thorough QA, add the extended matrix: 320 (smallest), 884-984 (foldable inner — often breaks), 1280/1366 (cheap laptops), 1536 (Windows scaling), 2560/3440 (large/ultrawide).

3. For each width, examine the screenshot for:

   Category	Specific checks
   Layout integrity	No horizontal scrollbar. Nothing bleeds past viewport. No content cut off behind another element.
   Typography	Body text ≥ 14px effective. Inputs ≥ 16px (iOS zoom). Heading hierarchy still visible.
   Tap targets	Buttons/links ≥ 24×24 (WCAG 2.5.8 AA floor) with ≥ 8px gap; ship target 44×44 on widths ≤ 1024. Inline text links exempt.
   Content density	Multi-column layouts stacked correctly. Sidebar collapsed ≤ 768. Tables in scroll wrapper or cards.
   Ultra-wide (≥1920)	Content not stretched edge-to-edge. No vast empty regions.
   320px specifically	Nothing has min-width > viewport - 2 × padding. Hero text not gigantic from clamp overshoot.
   Interactive state	If page has modal/menu/drawer, open it at mobile widths and re-screenshot.

4. If a JS-driven mobile menu exists, click it on a mobile screenshot to confirm it opens, covers the screen, can be closed (Escape + backdrop click + close button).

Exit criterion: screenshot at every width in the matrix, with annotated issues for any that fail.

Phase 5 — Report

Output a structured report. Use this exact format:

# Responsive Adaptation Report

## Stack detected
- <stack summary per file group>

## Files modified
- <path>:<line range> — <one-line reason>
- ...

## Anti-patterns fixed
- [CRITICAL] <name> (×N occurrences) — <how fixed>
- [MAJOR]    <name> (×N) — <how fixed>
- [MINOR]    <name> (×N) — <how fixed>

## Verification results
| Width | Status | Issues |
|-------|--------|--------|
| 360   | PASS   | — |
| 390   | PASS   | — |
| 393   | PASS   | — |
| 430   | PASS   | — |
| 768   | PASS   | — |
| 1024  | PASS   | — |
| 1440  | PASS   | — |
| 1920  | PASS   | — |

## Screenshots
- <relative path per width>

## Won't-fix items
- <issue> — <reason>

## Remaining concerns
- <anything the user should know>

If any breakpoint failed verification, don't claim done. Iterate on Phase 3 for the specific issues, re-verify only the affected widths, re-report.

Reference files

Read these only when the workflow phase points to them — don't read all upfront.

File	When to read
references/anti-patterns.md	Phase 2 — full catalog of every anti-pattern with detection + fix
references/modern-primitives.md	Phase 3 — clamp, min/max, container queries, dvh/svh, aspect-ratio, grid auto-fit, subgrid, logical props, :has(), @supports
references/fluid-typography.md	Phase 3, fluid type step — Utopia scale, clamp formula, accessibility-safe ratios
references/device-matrix.md	Phases 1 & 4 — full device list with rationale, what to check at each width
references/design-systems.md	When uncertain about breakpoint values — Material 3 + Apple HIG guidance
references/admin-patterns.md	Working on a dashboard/admin — sidebar collapse, tables→cards, dense forms, modals, widget grids
references/menus-drawers.md	Adding/fixing mobile nav — <dialog> drawer, bottom sheet, accessibility
references/touch-targets.md	Verifying tap targets — WCAG 2.5.8 vs 2.5.5, MD3 vs HIG
references/platform-quirks.md	iOS Safari / Android Chrome quirks (input zoom, safe-area, dvh, foldables)
references/tailwind.md	Stack is Tailwind
references/vanilla-css.md	Stack is vanilla CSS / CSS Modules
references/css-in-js.md	Stack is styled-components / Emotion / vanilla-extract

Bundled scripts

• scripts/scan.sh <project-root> — static anti-pattern scanner. Run in Phase 2.

Anti-patterns in your own execution

Things to NOT do while running this skill:

• Don't rewrite the page from scratch. Even if existing CSS is ugly, surgically adapt it.
• Don't add a CSS framework the project doesn't use. Vanilla CSS project → don't pull in Tailwind.
• Prefer CSS over JS for layout adaptation. clamp, container queries, dvh/svh, RAM grid, :has() cover ~90% of cases without react-responsive/useMediaQuery-style hooks (which also produce SSR hydration flashes). Legit JS use: ResizeObserver for canvas/chart sizing, virtualized tables, dynamic font measurement.
• Don't write 12 media queries when 1 clamp() does the job. Modern primitives over breakpoint salad.
• Don't claim done after fixing CSS without running Phase 4. A page that "looks right in the diff" is not a page that works on 320px. Verification is non-negotiable.
• Don't silently regress widths outside the user's stated focus. If they say "make it work on mobile", the desktop visual must still render correctly — re-screenshot at 1440px after your changes and compare to the Phase-1 baseline.
• Don't gate work on prefers-reduced-motion, dark mode, RTL, or other tangentially related things. Stay in scope.
• Don't use overflow: hidden on body to mask overflow. Find the root cause. Use overflow-x: clip on html only if you truly can't fix the source.
• Don't add maximum-scale=1 / user-scalable=no to "fix" iOS input zoom. Fix input font-size instead (A4).
• Don't use pure vw for fluid type (clamp(1rem, 4vw, 2rem) — middle doesn't move on zoom). Always mix rem into middle: clamp(1rem, 0.875rem + 1vw, 2rem).

When to stop

You're done when:

1. Phase-5 report shows PASS at every width in the device matrix.
2. Desktop baseline screenshot from Phase 1 and post-adaptation desktop screenshot are visually equivalent (same hierarchy, colors, fonts, components).
3. No forbidden changes were introduced.
4. The user has the report and the screenshots.

If you can't reach PASS at every width, say so explicitly — list the failing widths and what's blocking. Don't pretend.