Responsive Adapter

Responsive Adapter

$SKILL_DIR = this SKILL.md's directory; set once per session. All script paths are relative to it.

The desktop visual is the source of truth; every other width is a graceful adaptation — layout adapts, style does not. Fixing what wasn't broken on responsiveness grounds is scope creep — report it, don't touch it.

Allowed vs forbidden

Desktop screenshots before and after must be indistinguishable except where you intentionally stacked or collapsed.

Breakpoints (Material 3-aligned)

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

If the project already has a system (Tailwind 640/768/1024/1280/1536, Bootstrap), extend it, never run a second one in parallel.

Phase 1 — Discover

1. Identify project root; ask once if unstated.
2. Detect stack per file — .html + .css → vanilla (references/vanilla-css.md); tailwind.config.* / @tailwind / md: classes → Tailwind (references/tailwind.md); styled-components / @emotion / .styled.ts → CSS-in-JS (references/css-in-js.md); *.module.css → treat as vanilla. Mixes are common.
3. Enumerate pages/routes in scope.
4. Note the existing breakpoint conventions.
5. Open at 1440px via agent-browser and capture the baseline screenshot — the visual contract.

Exit: stack per file, file list, breakpoint conventions, baseline screenshot.

Phase 2 — Static scan

bash $SKILL_DIR/scripts/scan.sh <project-root>

Outputs issues by severity with file:line. Full catalog and fixes: references/anti-patterns.md.

Caught: A1 missing/broken viewport meta · A2 maximum-scale=1 / user-scalable=no (WCAG 1.4.4) · A3 fixed width: Npx / large min-width · A4 inputs font-size < 16px (iOS Safari auto-zoom, still present in iOS 18) · A5 100vh without dvh/svh · A8 no fluid-image baseline · A9 bottom-fixed without safe-area-inset-bottom · A13 100vw (includes scrollbar) · A14 overflow: hidden on body.

Inspect manually: tables without an overflow-x: auto ancestor; sidebars always rendered open; hover-only menus without :focus-within; tap targets (WCAG 2.2 SC 2.5.8 AA floor 24×24, ship target 44×44 — references/touch-targets.md).

Exit: written issue list by severity with file:line.

Phase 3 — Apply fixes

Rule A: modern primitives, not breakpoint salad — clamp(), min()/max(), container queries, dvh/svh/lvh, aspect-ratio, grid auto-fit/minmax (references/modern-primitives.md). Rule B: follow the idioms of each file's stack reference from Phase 1.

Order matters — 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%, overflow-x: clip on html (never hidden, see A14), img, svg, video { max-inline-size: 100%; block-size: auto; }.
2. Fluid type — clamp(MIN_rem, fluid_with_rem_component, MAX_rem), WCAG-safe MAX ≤ 2.5 × MIN. Never pure vw in the middle term — it stops responding to zoom: clamp(1rem, 0.875rem + 1vw, 2rem). Formula and scales: references/fluid-typography.md.
3. Containers — width: Npx → max-width: Npx; width: 100% + padding-inline; centered: inline-size: min(100% - 2rem, 1280px).
4. Layout primitives — grid-template-columns: repeat(auto-fit, minmax(min(100%, 280px), 1fr)); — the min(100%, …) is what makes 320px safe.
5. Breakpoint adaptations — stack columns, hide decorative side elements, sidebar → off-canvas drawer (references/menus-drawers.md), tables → scroll wrapper or cards (references/admin-patterns.md).
6. Mobile nav — prefer native <dialog> + showModal(): focus management, Escape, focus trap, top layer, ::backdrop for free.
7. Touch — tap targets ≥44px at touch widths, inputs ≥16px.
8. Safe areas — max(12px, env(safe-area-inset-bottom)) on bottom-fixed elements; requires viewport-fit=cover. See references/platform-quirks.md.
9. Edge widths — cap main content (max-w-[1400px] mx-auto) so ≥1920px isn't empty stretch; at 320px verify no min-width > viewport − 2 × padding.
10. Query choice — @media for app shell, OS preferences, srcset sizes, print. @container for reusable components adapting to their slot. Heuristic: moving the component to another slot changes styles → @container.

Then diff your own changes against the forbidden list. Anything that matches — revert.

Exit: every Phase-2 issue fixed or marked "won't fix — ", no forbidden changes.

Phase 4 — Browser verification

Static scans miss computed layouts, JS-driven UI, font fallbacks, real iOS behavior — non-negotiable: CSS that diffs clean is not a page that works at 320px.

Serve the page (python3 -m http.server 8000 or dev script), screenshot via agent-browser at the minimum matrix (full list: references/device-matrix.md):

Thorough QA adds 320, 884–984 (foldable inner — frequent breakage), 1280/1366, 1536, 2560/3440.

Check each screenshot for:

Also re-screenshot 1440px and compare to the Phase-1 baseline — a mobile-focused request must not regress desktop.

Exit: a screenshot per matrix width, with annotated issues for failures.

Phase 5 — Report

# Responsive Adaptation Report

## Stack detected
## Files modified — <path>:<lines> — <reason>
## Anti-patterns fixed — [SEVERITY] <name> (×N) — <how>
## Verification results — | Width | Status | Issues | for every matrix width
## Screenshots — path per width
## Won't-fix — <issue> — <reason>
## Remaining concerns

Done = PASS at every matrix width, desktop visually equivalent to baseline, no forbidden changes, report + screenshots delivered. Any failing width → iterate Phase 3, re-verify affected widths only, re-report. Can't reach PASS → list failing widths and blockers. Never claim done otherwise.

Execution rules

• Surgically adapt existing CSS, however ugly. Never rewrite the page from scratch.
• Never add a CSS framework the project doesn't use.
• CSS over JS: modern primitives cover ~90% of cases; useMediaQuery-style hooks also cause SSR hydration flashes. Legit JS: ResizeObserver for canvas/charts, virtualized tables, dynamic font measurement.
• Stay in scope — don't gate work on dark mode, RTL, or reduced motion.

References

Read only when a phase points to them.