Responsiveness Check
Test how a website's layout responds to viewport width changes. Resizes through breakpoints in a single browser session, screenshots each width, compares adjacent sizes, and reports where layouts break.
What this tests: Layout responsiveness — overflow, stacking, navigation transitions, content reflow.
What this does NOT test: General accessibility (ARIA, semantic HTML, heading hierarchy, colour contrast). Those don't vary by viewport width — use the ux-audit skill instead.
Browser Tool Priority
Before starting, detect available browser tools:
- playwright-cli (preferred) — supports resize, named sessions, and sub-agent parallelism. If installed, run
/playwright-cli first to load the full command reference.
- Playwright MCP (
mcp__plugin_playwright_playwright__*) — browser_resize for viewport changes.
- Chrome MCP (
mcp__claude-in-chrome__*) — resize_window for viewport changes. Uses the user's logged-in Chrome session.
If none are available, inform the user and suggest installing playwright-cli or Playwright MCP.
Operating Modes
Mode 1: Standard Check
When: "check responsive", "responsiveness check", "test breakpoints"
Test 8 key breakpoints that cover the device spectrum:
| Width |
Device Context |
| 320px |
Small phone (iPhone SE) |
| 375px |
Standard phone (iPhone 14) |
| 768px |
Tablet portrait (iPad) |
| 1024px |
Tablet landscape / small laptop |
| 1280px |
Laptop |
| 1440px |
Desktop |
| 1920px |
Full HD |
| 2560px |
Ultra-wide / 4K |
Process:
- Open the URL in a single browser session (height: 900px)
- Start at 320px. For each breakpoint width:
a. Resize the viewport
b. Wait briefly for CSS reflow (layout transition)
c. Screenshot the above-fold area
d. If the page has significant below-fold content, scroll and screenshot
e. Run the 8 layout checks (see matrix below)
f. Note any issues with severity
- Compare adjacent widths — identify where layout transitions occur
- Write the report
Mode 2: Sweep
When: "responsive sweep", "sweep all breakpoints", "find where it breaks"
Test every 160px from 320 to 2560 (15 widths total). Same single-session approach as Standard — just more data points. This is the mode for finding the exact width where a layout breaks.
Widths: 320, 480, 640, 800, 960, 1120, 1280, 1440, 1600, 1760, 1920, 2080, 2240, 2400, 2560
Briefly confirm before starting sweep mode (15 screenshots is a meaningful session).
Mode 3: Targeted Range
When: "check between 768 and 1024", "test tablet breakpoints", "focus on mobile widths"
Test a user-specified range at 80px increments. Use when a known trouble zone needs detailed investigation.
Example: "check between 768 and 1024" tests: 768, 848, 928, 1008 (plus 1024 as endpoint).
Multi-URL
When testing multiple URLs (e.g., "check the homepage, about page, and contact page"):
- Launch parallel sub-agents, one per URL (not per breakpoint)
- Each sub-agent runs a standard check on its URL in its own named session
- Combine results into a single report
# Sub-agent pattern (playwright-cli)
playwright-cli -s=page1 open https://example.com/ &
playwright-cli -s=page2 open https://example.com/about &
Layout Check Matrix
These 8 checks target issues that actually vary by viewport width:
| # |
Check |
What to Look For |
| 1 |
Horizontal overflow |
Content wider than viewport — horizontal scrollbar appears, elements cut off |
| 2 |
Text overflow |
Text truncated mid-word, overlapping adjacent elements, font size unreadable (< 12px) |
| 3 |
Navigation transition |
Hamburger menu appears/disappears at correct width, no "broken" state between modes |
| 4 |
Content stacking |
Multi-column layouts stack to single column in logical reading order on narrow widths |
| 5 |
Image/media scaling |
Images overflow container, distorted aspect ratios, missing responsive sizing |
| 6 |
Touch targets |
Interactive elements < 44px on mobile widths (< 768px) — buttons, links, form inputs |
| 7 |
Whitespace balance |
Too cramped on mobile (no breathing room), too sparse on wide screens (content lost in space) |
| 8 |
CTA visibility |
Primary call-to-action visible above the fold at each width without scrolling |
Transition Detection
The unique value of this skill is finding where layout transitions happen and whether they're clean.
When comparing screenshots at adjacent widths, flag any width where:
- Column count changes (3-col → 2-col → 1-col grid)
- Navigation mode switches (full nav → hamburger, or vice versa)
- Sidebar appears/disappears (content width jumps)
- Grid reflows (cards wrap to next row)
Report the exact width range where each transition occurs:
| Transition |
From |
To |
Width Range |
| Nav: hamburger → full |
768px |
1024px |
Switches at ~960px |
| Grid: 1-col → 2-col |
640px |
768px |
Reflows at ~700px |
| Sidebar appears |
1024px |
1280px |
Shows at ~1100px |
This tells the developer exactly where to set (or fix) their CSS breakpoints.
Severity Levels
Consistent with ux-audit:
| Severity |
Meaning |
| Critical |
Layout is broken — content unreadable, navigation inaccessible, page unusable |
| High |
Significant layout issue — major overflow, key content hidden, broken transition |
| Medium |
Noticeable but usable — awkward spacing, minor overflow, suboptimal stacking order |
| Low |
Polish — whitespace tweaks, slight alignment issues, minor touch target shortfalls |
Autonomy Rules
- Just do it: Resize viewport, take screenshots, analyse layout, compare widths
- Brief confirmation: Before sweep mode (15 viewports), before testing 4+ URLs in parallel
- Ask first: Before interacting with forms or clicking through authentication flows
Report Output
Write report to docs/responsiveness-check-YYYY-MM-DD.md (or inline for single-page quick checks).
See references/report-template.md for the report structure.
Reference Files
