howells/responsive

<tool_restrictions>

MANDATORY Tool Restrictions

BANNED TOOLS — calling these is a skill violation:

• EnterPlanMode — BANNED. Do NOT call this tool. This skill manages its own workflow and writes results directly. Claude's built-in plan mode would bypass this process.
• ExitPlanMode — BANNED. You are never in plan mode. There is nothing to exit.

REQUIRED TOOLS:

• AskUserQuestion — Preserve the one-question-at-a-time interaction pattern for every question to the user, including confirming routes, choosing options, and validating fixes. In Claude Code, use the tool. In Codex, ask one concise plain-text question at a time unless a structured question tool is actually available in the current mode. This prevents walls of text. If you need to provide context before asking, keep it to 2-3 sentences max, and do not narrate missing tools or fallbacks to the user.

If you feel the urge to "plan before acting" — that urge is satisfied by following the <process> steps below. Execute them directly. </tool_restrictions>

<arc_runtime> This workflow requires the full Arc bundle, not a prompts-only install.

Paths in this skill use these conventions:

• agents/..., references/..., disciplines/..., templates/..., scripts/..., rules/..., skills/<name>/... are Arc-owned files at the plugin root. Resolve the plugin root from this skill's filesystem location — it's the directory containing agents/ and skills/.
• ./... is local to this skill's directory.
• .ruler/..., docs/..., src/..., or any project-relative path refers to the user's project repository. </arc_runtime>

<required_reading> Read these using the Read tool when relevant:

1. references/touch-targets.md — Minimum target sizes, pseudo-element expansion, mobile-specific patterns
2. references/ux-laws.md — Fitts's Law (target sizing), Gestalt proximity (spacing decisions) </required_reading>

Responsive Audit & Fix

Systematically audit and fix every page for mobile responsiveness, with visual verification via browser screenshots.

Announce at start: "I'm using the responsive skill to audit and fix mobile responsiveness across your project."

---

<process>

Phase 1: Setup & Discovery

Step 1: Select Browser Tool

Prefer Chrome MCP in Claude Code.

If Chrome MCP is unavailable:

• prefer agent-browser for navigation, resizing, and screenshots
• fall back to Playwright if browser automation must be scripted directly
• only stop if no browser-capable path is available

Step 2: Detect Dev Server URL

Do not prompt with hardcoded port options — detect first.

Read package.json and resolve the dev URL:

1. Read root package.json. Inspect scripts.dev.
2. If dev delegates to a workspace (e.g. pnpm --dir site dev, pnpm -C apps/web dev, turbo run dev --filter=web, npm run dev --workspace=...), follow the reference and read that workspace's package.json.
3. Glob for .env, .env.local, .env.development. Look for PORT=.
4. If still unresolved, check next.config.*, vite.config.*, astro.config.* for an explicit port.

Scan the leaf scripts.dev for one of these patterns (first match wins):

| Pattern | Example | Port | |---------|---------|------| | --port N / -p N | next dev --port 4000 | 4000 | | ${PORT:-N} shell fallback | next dev --port ${PORT:-26000} | 26000 (unless $PORT is set in .env*) | | PORT=N inline | PORT=8080 next dev | 8080 | | PORT=N in .env* | PORT=3005 in .env.local | 3005 | | Vite default | vite with no port flag | 5173 | | Astro default | astro dev with no port flag | 4321 | | SvelteKit default | vite dev (kit) | 5173 | | Next default | next dev with no port flag | 3000 | | Remix default | remix dev | 3000 |

.env* PORT values override ${PORT:-N} fallbacks.

If exactly one dev URL was detected: Announce it and navigate directly:

"Using http://localhost:26000 (from site/package.json → next dev --port ${PORT:-26000})."

If multiple candidates (monorepo with several dev servers):

AskUserQuestion:
  question: "Which dev server should I audit?"
  header: "Dev server"
  options:
    - label: "[detected URL 1]"
      description: "[source]"
    - label: "[detected URL 2]"
      description: "[source]"

If nothing could be detected:

AskUserQuestion:
  question: "I couldn't detect a dev URL. What should I audit?"
  header: "Dev server"
  options:
    - label: "Enter a URL"
      description: "I'll type it in"

Then verify the server is running with the selected browser tool:

mcp__claude-in-chrome__tabs_context_mcp (get or create tab)
mcp__claude-in-chrome__navigate to the dev server URL
mcp__claude-in-chrome__computer action=screenshot

If the page doesn't load, tell the user to start their dev server and try again. Do not silently fall back to localhost:3000 — surface the failure.

Step 3: Load Design Context

Read design doc (if exists):

Glob: docs/arc/specs/design-*.md
Fallback: docs/plans/design-*.md

If found, read the design doc and note:

• Aesthetic direction (tone, memorable element)
• Typography hierarchy (display, body, mono fonts)
• Spacing system (base unit, scale)
• Color palette (so you don't introduce new colors)

This context guides every fix decision. If there's no design doc, that's fine — apply general responsive best practices from the interface rules.

<required_reading> Read before auditing:

• rules/interface/layout.md — Layout patterns, z-index, viewport units
• rules/interface/interactions.md — Touch, keyboard, hover patterns
• rules/interface/spacing.md — Spacing system and scale </required_reading>

Step 4: Discover Routes

Detect framework:

| Check | Grep Pattern | Framework | |-------|-------------|-----------| | "next" in package.json | Next.js | app/**/page.{tsx,jsx} | | "@remix-run" in package.json | Remix | app/routes/**/*.{tsx,jsx} | | "astro" in package.json | Astro | src/pages/**/*.{astro,mdx} | | "@sveltejs/kit" in package.json | SvelteKit | src/routes/**/+page.svelte | | "react-router" or "@tanstack/react-router" in package.json | Vite + Router | Ask user for route list — no file convention |

If no framework detected or routes use a router config (React Router, TanStack Router), ask the user to provide the list of URLs to audit.

Scan for page files using the appropriate glob pattern. Exclude API routes (app/api/**).

Build route list from file paths:

• app/page.tsx → /
• app/about/page.tsx → /about
• app/blog/[slug]/page.tsx → /blog/[slug] (dynamic)
• app/dashboard/page.tsx → /dashboard (may need auth)

Flag dynamic routes — these need sample values from the user.

Flag potentially auth-protected routes — routes under common auth-gated paths like /dashboard, /settings, /account, /admin.

Step 5: Confirm Routes with User

Present the discovered routes:

AskUserQuestion:
  question: "I found these routes. Any to skip?"
  header: "Routes"
  multiSelect: true
  options:
    - label: "/ (homepage)"
      description: "Public page"
    - label: "/about"
      description: "Public page"
    - label: "/blog/[slug]"
      description: "Dynamic — I'll need a sample slug"
    - label: "/dashboard"
      description: "May need auth — log in via Chrome first"

If dynamic routes exist, ask for sample slugs:

AskUserQuestion:
  question: "What slug should I use for /blog/[slug]?"
  header: "Sample URL"
  options:
    - label: "first-post"
      description: "Use /blog/first-post"
    - label: "hello-world"
      description: "Use /blog/hello-world"

If auth-protected routes exist: Tell the user: "Some routes may need authentication. Please log in via the Chrome browser, then let me know when you're ready."

AskUserQuestion:
  question: "Are the auth-protected routes ready to audit?"
  header: "Auth"
  options:
    - label: "Yes, I'm logged in"
      description: "Continue with all routes including auth-protected ones"
    - label: "Skip auth routes"
      description: "Only audit public pages for now"

---

Phase 2: Page-by-page Audit & Fix

Work through each confirmed route. The loop is tight: screenshot → analyze → fix → verify → check desktop → next page.

For Each Page:

Step 1: Mobile Screenshot (375x812)

mcp__claude-in-chrome__navigate to [dev-server-url]/[route]
mcp__claude-in-chrome__resize_window width=375 height=812
mcp__claude-in-chrome__computer action=wait duration=2
mcp__claude-in-chrome__computer action=screenshot

Wait briefly for any animations or lazy-loaded content to settle before screenshotting.

Step 2: Analyze the Screenshot

Look at the screenshot and evaluate against these categories:

Layout:

• Horizontal overflow (content wider than viewport, horizontal scrollbar)
• Elements overlapping or clipping
• Grids/flexbox not stacking properly
• Fixed-width elements that don't fit

Spacing:

• Content touching container edges (needs padding)
• Inconsistent gaps between elements
• Sections too cramped or too sparse for mobile

Typography:

• Body text smaller than 16px (hard to read on mobile)
• Headings that are too large and cause overflow
• Typography hierarchy lost (everything looks the same size)

Usability:

• Touch targets smaller than 44x44px (buttons, links, icons)
• Input fields without text-base (causes iOS auto-zoom)
• Missing viewport meta tag
• Hover-dependent functionality with no touch alternative

Design intent (if design doc was loaded):

• Does the page still feel like the same design at mobile width?
• Is the memorable element preserved (even if scaled)?
• Are the documented spacing values being used (not arbitrary new values)?
• Is the typography hierarchy intact (scaled down proportionally, not collapsed)?

Step 3: Fix Issues

Apply fixes in code. Follow these principles:

Container queries for component-level fixes: Use @container when fixing a reusable component (card, sidebar, content block, form layout). This makes the component adapt to its container rather than the viewport, so it works in any layout context.

Viewport queries for page-level layout: Use viewport media queries (@media) when fixing page structure — grid column counts, section stacking order, navigation collapse, page-level padding.

Use existing spacing values: Reference rules/interface/spacing.md. Use the Tailwind spacing scale (4, 8, 12, 16, 24, 32, 48, 64). Never invent new spacing values like 13px or 27px.

Use h-dvh not h-screen: Reference rules/interface/layout.md. Dynamic viewport height respects mobile browser chrome.

Gate hover styles: Reference rules/interface/interactions.md. Use @media(hover:hover) so hover effects don't fire on touch devices.

Shared components: If you recognize the same component causing issues across multiple pages, fix the component source file rather than adding page-specific overrides. This is the natural, correct approach — not a special detection system.

Step 4: Verify Mobile Fix

After applying fixes, wait for HMR to recompile before screenshotting:

mcp__claude-in-chrome__computer action=wait duration=3
mcp__claude-in-chrome__computer action=screenshot

Compare visually to the pre-fix screenshot. Are the issues resolved? If not, iterate.

Step 5: Desktop Regression Check (1440x900)

mcp__claude-in-chrome__resize_window width=1440 height=900
mcp__claude-in-chrome__computer action=screenshot

Verify desktop is intact. The fix should not have broken the desktop layout. Check:

• Grid layouts still multi-column
• Spacing still generous (not collapsed)
• Typography still at desktop scale
• No visual artifacts from responsive changes

If desktop broke: Fix the regression, then re-verify at both 375px and 1440px before moving on.

Step 6: Scroll Check

For pages longer than the viewport:

mcp__claude-in-chrome__resize_window width=375 height=812
mcp__claude-in-chrome__computer action=scroll scroll_direction=down scroll_amount=5
mcp__claude-in-chrome__computer action=screenshot

Repeat scrolling and screenshotting until you've covered the full page. Look for below-the-fold issues:

• Footer overflow
• Long content sections with broken layout
• Images or embeds that don't fit
• Sticky/fixed elements obscuring content

Step 7: Next Page

Move to the next route in the list and repeat from Step 1.

Progress update: After each page, briefly note what was fixed: "Homepage: fixed hero grid and nav. Moving to /about."

---

Phase 3: Summary & Commit

Step 1: Present Change Summary

After all pages are audited and fixed, present a summary grouped by page and shared component:

## Responsive Fixes Applied

### / (homepage)
- Fixed hero grid: 3-column → single-column on mobile (container query on HeroCard)
- Fixed nav: added mobile sheet menu via viewport query
- Fixed section padding: p-4 on mobile, p-16 on desktop

### /about
- Fixed image overflow: added max-w-full to team photos
- Fixed touch targets on CTA buttons: expanded hit area to 44px

### /blog/first-post
- Fixed prose width: constrained to viewport on mobile
- Fixed code blocks: added overflow-x-auto

### Shared: components/Card.tsx
- Added @container query for horizontal → vertical layout below 400px

### Shared: components/Navigation.tsx
- Added mobile sheet menu pattern with viewport query

Step 2: Commit

Batch commit all responsive fixes:

# Stage only the files you modified — check git status first
git status
git add [list of modified files]
git commit -m "fix: responsive fixes across [N] pages

- [Brief list of key changes]
- Container queries for [components]
- Viewport queries for [page layouts]"

Step 3: Optional Audit Document

AskUserQuestion:
  question: "Want me to save a responsive audit doc with all issues found and fixes applied?"
  header: "Audit doc"
  options:
    - label: "Yes, save audit doc"
      description: "Write to docs/audits/ for future reference"
    - label: "No, the commit is enough"
      description: "Skip the audit doc"

If yes, write docs/audits/YYYY-MM-DD-responsive.md with the full change summary, and commit it.

Step 4: Final Desktop Verification

Do one final pass: resize to 1440x900 and quickly navigate through all audited pages to confirm everything looks correct at desktop width. This catches any cumulative issues from the page-by-page fixes.

mcp__claude-in-chrome__resize_window width=1440 height=900

Navigate to each page and take a quick screenshot. If anything looks off, fix and re-commit.

</process>

<success_criteria> Responsive audit is complete when:

• [ ] Browser tool connected and dev server verified
• [ ] Design doc read (if exists) for aesthetic context
• [ ] Interface rules loaded (layout, interactions, spacing)
• [ ] Routes discovered and confirmed with user
• [ ] Each page screenshotted at 375px (mobile)
• [ ] Issues identified and fixed per page
• [ ] Each fix verified with re-screenshot at mobile
• [ ] Desktop (1440px) checked after mobile fixes — no regressions
• [ ] Final desktop pass across all pages
• [ ] Changes committed
• [ ] Activity log updated </success_criteria>

Interop

• Invoked after /arc:implement — the natural post-build polish step
• Reads design docs from /arc:design for aesthetic context
• References rules/interface/layout.md, interactions.md, spacing.md for implementation patterns
• Uses Chrome MCP (mcp__claude-in-chrome__*) as the preferred browser path in Claude Code
• Uses agent-browser as the preferred browser fallback outside Claude Code
• Uses Playwright when direct browser scripting is needed
• Follows /arc:commit discipline for commits
• Can invoke web-design-guidelines skill for compliance review (if available)

<arc_log> After completing this skill, append to the activity log. See: references/arc-log.md

Entry: /arc:responsive — [N] pages audited, [N] issues fixed </arc_log>