responsiveness-check

Original source / Raw SKILL.md

---
name: responsiveness-check
description: "Test website responsiveness across viewport widths using browser automation. Resizes a single session through breakpoints, screenshots each width, and detects layout transitions (column changes, nav switches, overflow). Produces comparison reports showing exactly where layouts break. Trigger with 'responsiveness check', 'check responsive', 'breakpoint test', 'viewport test', 'responsive sweep', 'check breakpoints', or 'test at mobile'."
compatibility: claude-code-only
---

# 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

Write report to `docs/responsiveness-check-YYYY-MM-DD.md` (or inline for single-page quick checks).

See [references/report-template.md](references/report-template.md) for the report structure.

## Reference Files

| When | Read |
|------|------|
| Looking up breakpoint details and trouble zones | [references/breakpoints.md](references/breakpoints.md) |
| Writing the responsiveness report | [references/report-template.md](references/report-template.md) |


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### references/report-template.md

```markdown
# Responsiveness Report Template

Use this structure when writing responsiveness check reports.

## Report Structure

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

| Status | Meaning |
|--------|---------|
| **Pass** | No layout issues at this width |
| **Warn** | Minor issues (medium/low severity) — usable but not polished |
| **Fail** | Critical or high severity issues — layout is broken or significantly degraded |

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

```

### references/breakpoints.md

```markdown
# Breakpoints Reference

## Standard Breakpoints (8)

| Width | Device Context | What Typically Breaks |
|-------|---------------|----------------------|
| 320px | Small phone (iPhone SE, Galaxy S) | Everything — if it works here, mobile is solid |
| 375px | Standard phone (iPhone 14/15, Pixel) | Minor text overflow, touch target sizing |
| 768px | Tablet portrait (iPad) | Navigation transition zone, sidebar visibility |
| 1024px | Tablet landscape / small laptop | Grid column counts, content width constraints |
| 1280px | Laptop (13-14") | Max-width containers, wide table layouts |
| 1440px | Desktop (15-16") | Content centering, hero section proportions |
| 1920px | Full HD monitor | Ultra-wide whitespace, content lost in space |
| 2560px | 4K / ultra-wide | Maximum stretch — most sites need max-width containment |

## Sweep Breakpoints (15)

Every 160px from 320 to 2560:

| Width | Transition Zone |
|-------|----------------|
| 320px | Mobile baseline |
| 480px | Large phone / small phablet |
| 640px | Phablet — Tailwind `sm:` starts here |
| 800px | Between tablet and desktop — often overlooked |
| 960px | Common nav hamburger → full switch point |
| 1120px | Sidebar appearance zone |
| 1280px | Tailwind `xl:` — laptop standard |
| 1440px | Common `max-w-7xl` container width |
| 1600px | Wide desktop |
| 1760px | Transition to ultra-wide |
| 1920px | Full HD — Tailwind `2xl:` |
| 2080px | Ultra-wide territory |
| 2240px | Max-width containers should be capping by now |
| 2400px | Extreme width — tests containment |
| 2560px | 4K upper bound |

## Trouble Zones

These width ranges are where responsive bugs hide:

| Range | Why It Breaks |
|-------|--------------|
| **768–1024px** | Tablet no-man's land. Mobile layouts are too cramped, desktop layouts don't fit. Nav transitions happen here. Many sites have NO breakpoint between 768 and 1024. |
| **1024–1280px** | Sidebar visibility zone. Content needs to decide: stack or side-by-side? Grid columns usually jump from 2 to 3 here. |
| **1440–1920px** | Wide screen gap. Sites with `max-w-7xl` (1280px) containers leave massive margins. Hero sections and full-bleed elements need attention. |
| **1920–2560px** | Ultra-wide. Text line lengths become unreadable without containment. Background images may not cover. Grid gaps look enormous. |

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

| Prefix | Min Width |
|--------|-----------|
| `sm:` | 640px |
| `md:` | 768px |
| `lg:` | 1024px |
| `xl:` | 1280px |
| `2xl:` | 1536px |

```