Retrofit Responsiveness with an Agent-Driven Multi-Viewport Audit

Tier: Core · Workflow area: Styling, responsive & i18n

The audit is the product of this playbook. Teams that skip straight to "make it responsive" fix the three breakages they happen to notice and ship the other nine. An agent with a browser notices all twelve.

Prerequisites

• •
  The app running locally or on staging, reachable by an agent-driven browser (chrome-devtools-mcp or Playwright).
• •
  A route list for the surfaces in scope — ten representative URLs beat "the whole app."
• •
  Agreement on target widths. A solid ladder: 360, 390, 768, 1024, 1280, 1536 — plus 320 if you support small phones.

The recipe

1. 1.

   Send the agent across the matrix, read-only. The instruction that produces a catalog instead of chatter:

   Copy

   Using the browser, visit each URL in routes.txt at widths 360, 390,
   768, 1024, 1280 (height 900). At each stop: screenshot, then check for
   (a) horizontal overflow (document.scrollingElement.scrollWidth >
   innerWidth — report the offending element via elementsFromPoint along
   the right edge), (b) text truncated or overlapping, (c) touch targets
   under 44px at widths <= 768, (d) fixed-position elements covering
   content, (e) images/media overflowing containers.
   Output findings.md: one row per issue — route | width(s) | component
   or selector | symptom | screenshot file | suspected CSS cause.
   Change nothing.
   

   The overflow probe matters: horizontal scroll is the number-one retrofit symptom and agents can detect it programmatically instead of squinting at screenshots.

2. 2.

   Deduplicate into component-level work. Thirty findings usually collapse into six real problems — the same fixed-width card breaks on five routes. Have the agent do the first pass:

   Copy

   Group findings.md by root component (use the selector and screenshots).
   For each group: one line naming the component, the width range where it
   breaks, and the count of affected routes. Order by affected-route count.
   

   You now have a ranked backlog with evidence attached — this is the artifact to show your lead before writing any CSS.

3. 3.

   Choose the modern fix per class of breakage. Retrofits done as @media patches recreate the problem at the next unanticipated width. Match cause to tool. Fixed widths on cards/panels → max-width plus width: 100%, or grid minmax(). Row layouts that should stack → container queries (container-type: inline-size on the wrapper, @container (width < 480px)) so the component responds to its slot, not the viewport — critical for anything that renders in both a sidebar and a main column. Rigid type/spacing scales → clamp() (e.g. font-size: clamp(1rem, 0.9rem + 0.7vw, 1.25rem)). Column counts hardcoded per breakpoint → grid-template-columns: repeat(auto-fit, minmax(16rem, 1fr)). Tables → horizontal scroll in an overflow-x: auto wrapper, or a card layout under a container query; never let the page body scroll sideways.

4. 4.

   Fix one component group per PR, agent-verified. Point the agent at one group with the fix strategy chosen:

   Copy

   Fix group 2 (OrderTable overflow below 768px) using the overflow-wrapper
   strategy. Then re-run the step-1 audit for the affected routes only and
   append a before/after screenshot pair per route to the PR description.
   Confirm no NEW findings appeared at any width.
   

   The "no new findings" clause is essential — responsive fixes love to break the width that was fine.

5. 5.

   Sweep the in-between widths before closing. Breakpoint-ladder testing misses failures at 850px that 768 and 1024 both pass. One pass with a width-stepping loop (every 100px across the range, overflow check only) is cheap for an agent and catches the stragglers that make users think your app is flaky.

6. 6.

   Install the regression tripwire. Add the overflow probe as a Playwright test across three widths per key route in CI. It is a one-expectation test — scrollWidth <= innerWidth — and it converts this one-time retrofit into a standing guarantee.

Tool variations

• chrome-devtools-mcp + Claude Code: the primary setup — resize, screenshot, run the overflow probe, and read computed styles in one loop, then make the fixes in the same session.
• Playwright script + any assistant: generate the audit script once, run it in CI or locally, and feed findings.md plus screenshots to the model for steps 2–3; better for repeatable re-audits.
• Copilot in VS Code: fine for the per-component fix lane once the catalog exists; it lacks the browser, so pair it with the Playwright audit script.
• Device-emulation caveat: viewport-width emulation catches layout breakage but not touch ergonomics or iOS Safari's dynamic toolbar; do one manual pass on a real phone before declaring victory.

Quality check

• Catalog before codeevery fix traces to a findings.md row; anything fixed "while in there" gets its own row retroactively.
• Component-scoped PRseach PR names its group, its strategy, and carries before/after pairs at the failing widths.
• No new findingsthe re-audit after each PR is clean at every width, not just the one being fixed.
• In-between sweep donethe 100px-step overflow pass across the full range reports zero.
• Tripwire mergedthe CI overflow test exists, so the surface cannot silently regress to desktop-only.