Responsiveness Check

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:

1. playwright-cli (preferred) — supports resize, named sessions, and sub-agent parallelism. If installed, run /playwright-cli first to load the full command reference. 2. Playwright MCP (mcp__plugin_playwright_playwright__*) — browser_resize for viewport changes. 3. 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:

Process:

1. Open the URL in a single browser session (height: 900px) 2. 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 3. Compare adjacent widths — identify where layout transitions occur 4. 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:

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:

This tells the developer exactly where to set (or fix) their CSS breakpoints.

Severity Levels

Consistent with ux-audit:

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

Breakpoints Reference

Standard Breakpoints (8)

Sweep Breakpoints (15)

Every 160px from 320 to 2560:

Trouble Zones

These width ranges are where responsive bugs hide:

Default Height

Use 900px viewport height for all tests. This matches a typical laptop/desktop viewport and provides a consistent baseline for above-fold comparisons. Only vary height if specifically testing vertical responsiveness (rare).

Tailwind v4 Default Breakpoints

For reference when diagnosing where CSS breakpoints are set:

Responsiveness Report Template

Use this structure when writing responsiveness check reports.

Report Structure

# Responsiveness Check: [URL]

**Date**: YYYY-MM-DD
**Mode**: Standard / Sweep / Targeted (range)
**Breakpoints tested**: [list widths]
**Browser tool**: playwright-cli / Playwright MCP / Chrome MCP

## Summary

| Width | Status | Issues |
|-------|--------|--------|
| 320px | Fail | 2 critical, 1 high |
| 375px | Fail | 1 high |
| 768px | Warn | 1 medium |
| 1024px | Pass | — |
| 1280px | Pass | — |
| 1440px | Pass | — |
| 1920px | Warn | 1 medium |
| 2560px | Fail | 1 high |

**Overall**: X issues across Y breakpoints. [1-sentence summary of the main finding.]

## Critical & High Issues

### [Issue title] — [Severity]

**Width(s)**: 320px, 375px
**Check**: Horizontal overflow

[Description: what's happening, what element is affected]

[Screenshot reference or inline image]

**Fix suggestion**: [CSS/HTML fix if obvious]

---

[Repeat for each critical/high issue]

## Transition Analysis

| Transition | Observed At | Clean? | Notes |
|-----------|-------------|--------|-------|
| Nav: hamburger → full | ~960px | Yes | Smooth transition, no flicker |
| Grid: 1-col → 2-col | ~700px | No | Cards overlap briefly at 680-720px |
| Sidebar appears | ~1100px | Yes | Content reflows cleanly |
| Footer: stacked → inline | ~640px | Yes | — |

## Per-Breakpoint Notes

Only include breakpoints with findings. Skip clean ones.

### 320px — Fail

- **[Critical]** Hero text overflows viewport, horizontal scroll appears
- **[High]** CTA button text wraps to 3 lines, looks broken
- Nav hamburger works correctly

### 375px — Fail

- **[High]** Service cards stack but images overflow container by ~20px

### 1920px+ — Warn

- **[Medium]** Content area maxes out at 1280px, leaving 320px margins each side — feels disconnected

## Recommendations

Group by effort:

### Quick Fixes (CSS only)
- Add `overflow-x: hidden` on hero container
- Set `max-width: 100%` on service card images
- Add `max-w-[1600px]` container for ultra-wide

### Structural Changes
- Add a breakpoint between 768–1024px for tablet-specific layout
- Rethink grid gap scaling for 1920px+

Status Definitions

Writing Guidelines

• Findings-first: Lead with what's broken, not what works
• Be specific: "Hero h1 overflows at 320px by ~40px" not "text overflow issues"
• Include the width: Every finding must state which width(s) it affects
• Screenshot at failures: Screenshots make the report actionable
• Skip clean breakpoints: Don't write "1280px — everything looks great" — only note breakpoints with issues
• Group fixes by effort: CSS-only fixes vs structural changes helps prioritise