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:

| 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**:

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**:

| # | 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