agentleFS
khairoldkhairold/claude-skills/skills/responsive-audit/SKILL.md

responsive-audit

Skill0 starsChanged 7 months agoMITView on GitHub

Audit a component for responsive behaviour using dev-browser. Screenshots it at multiple breakpoints, reads the visual output, reads the source code, identifies responsive issues, and produces a concrete fix plan. Optionally compares against a reference URL. Requires dev-browser CLI. Use when asked to "make this responsive", "check responsive", "audit breakpoints", or "fix mobile layout".

4 other projects use a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

5 rules. 0 are common, 2 are distinctive, and 3 are very specific to this project.

  • 0

    Common

    Most of the 4 edited versions we read keep these.

  • 2

    Distinctive

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Use dev-browser --headless to capture the component at each project breakpoint.

    line 28
  2. Very specific:

    Use the read tool on each saved screenshot PNG.

    line 62
  3. Very specific:

    If a reference URL is provided (e.g.

    line 71
  4. Distinctive:

    Read all component source files.

    line 80
  5. Distinctive:

    Commit with a descriptive message noting the responsive changes:

    line 122

“Common” is measured: kept by at least 6 in 10 of the 4 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Responsive Audit

Visually audit a component's responsive behaviour by screenshotting it at standard breakpoints, then produce a fix plan or implement the fixes.

Prerequisites

  • dev-browser CLI installed and available on PATH
  • Dev server running (e.g. localhost:3000, localhost:5173, localhost:4321, etc.)
  • Playwright browsers installed (dev-browser install if needed)

Process

Step 1 — Locate the component

Identify:

  1. The preview URL — the page or embed URL that renders the component in isolation
  2. The source files — find all relevant component files (.tsx, .vue, .svelte, .astro, .jsx, etc.)
  3. The project's breakpoint system — look for breakpoint definitions in the codebase (e.g. Breakpoints.tsx, tailwind.config.*, global.css @theme block). Use these breakpoints, not arbitrary ones.

Step 2 — Screenshot at all breakpoints

Use dev-browser --headless to capture the component at each project breakpoint. At minimum capture these widths:

NameWidthRepresents
mobile375pxPhone (portrait)
tablet768pxTablet (portrait)
laptop1024pxSmall laptop / tablet landscape
desktop1440pxDesktop

Script pattern:

dev-browser --headless <<'EOF'
const page = await browser.getPage("responsive-audit");
await page.goto("<URL>", { waitUntil: "networkidle" });

const breakpoints = [
  { name: "mobile-375", width: 375, height: 800 },
  { name: "tablet-768", width: 768, height: 1024 },
  { name: "laptop-1024", width: 1024, height: 768 },
  { name: "desktop-1440", width: 1440, height: 900 },
];

for (const bp of breakpoints) {
  await page.setViewportSize({ width: bp.width, height: bp.height });
  await new Promise(r => setTimeout(r, 500));
  const buf = await page.screenshot({ fullPage: true });
  const path = await saveScreenshot(buf, `audit-${bp.name}.png`);
  console.log(`${bp.name}: ${path}`);
}
EOF

Step 3 — View and analyse screenshots

Use the read tool on each saved screenshot PNG. For each breakpoint, note:

  • Is there horizontal overflow?
  • Are elements overlapping or cramped?
  • Is text readable?
  • Are interactive elements (buttons, links) tap-target sized on mobile?
  • Is the layout appropriate for the viewport width?

Step 4 — (Optional) Compare against reference

If a reference URL is provided (e.g. the production site), screenshot it at the same breakpoints and compare the layout patterns. Use domcontentloaded instead of networkidle if the site is slow:

await page.goto("<REFERENCE_URL>", { waitUntil: "domcontentloaded", timeout: 15000 });
await new Promise(r => setTimeout(r, 3000));

Step 5 — Read the source code

Read all component source files. Look for:

  • Missing responsive classes — no sm:, md:, lg:, xl: prefixes (Tailwind) or equivalent media queries
  • Fixed widths that should be fluid
  • Flex layouts that don't wrap or reflow
  • Elements that should hide/show at different breakpoints
  • Padding/margins that don't scale down

Step 6 — Produce the plan

Output a structured plan with:

  1. Current state table — breakpoint × what's broken
  2. Breakpoint strategy — which breakpoint is the mobile↔desktop switch point and why
  3. File-by-file changes — what to modify in each file
  4. New files needed — e.g. a mobile drawer, responsive variant

Common responsive patterns for navigation:

  • Desktop nav → hamburger + drawer below the switch breakpoint
  • Multi-column → stacked layout for content grids
  • Hide secondary elements (announcements, labels) on small screens
  • Accordion replaces mega menu on mobile

Step 7 — Implement (if asked)

Apply the changes, then:

  1. Build check — run the project build to verify no errors
  2. Re-screenshot — capture all breakpoints again with the same script
  3. View and verify — read each screenshot to confirm the fix
  4. Test interactions — if there are interactive elements (menus, drawers), use dev-browser to click/tap them and screenshot the result
// Example: testing a mobile menu
await page.click('button[aria-label="Open menu"]');
await new Promise(r => setTimeout(r, 400));
const buf = await saveScreenshot(await page.screenshot(), "audit-mobile-menu-open.png");
  1. Update docs — if the component has design system documentation, update anatomy, behaviour, and file listings

Step 8 — Commit

Commit with a descriptive message noting the responsive changes:

feat(<Component>): add responsive layout with mobile <pattern>

- <file>: <what changed>
- <new file>: <what it does>

Breakpoint: <breakpoint> switches between mobile and desktop layout

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.