responsiveness-check

jezweb ｜ 測試與驗證 ｜ 原文 ｜ MIT

用瀏覽器依序調整寬度截圖，找出版面在哪個斷點壞掉

---
name: responsiveness-check
description: "用瀏覽器自動化測試網站在不同 viewport 寬度下的響應式表現。在同一個 session 裡依序調整各斷點，每個寬度截圖，偵測版面轉換（欄數變化、導覽切換、溢出）。產出比較報告，精確指出版面在哪裡壞掉。用 'responsiveness check'、'check responsive'、'breakpoint test'、'viewport test'、'responsive sweep'、'check breakpoints' 或 'test at mobile' 觸發。"
compatibility: claude-code-only
---

# Responsiveness Check

測試網站版面如何回應 viewport 寬度的變化。在單一瀏覽器 session 裡依序調整各斷點，每個寬度截圖，比較相鄰的尺寸，並回報版面在哪裡壞掉。

**這個測什麼**：版面的響應式表現：溢出、堆疊、導覽轉換、內容重排。

**這個不測什麼**：一般的無障礙（ARIA、語意化 HTML、標題階層、顏色對比）。那些不會隨 viewport 寬度改變，請改用 ux-audit skill。

## 瀏覽器工具優先順序

開始之前，先偵測有哪些可用的瀏覽器工具：

1. **playwright-cli**（優先）：支援調整大小、具名 session 和 sub-agent 平行。如果有安裝，先執行 `/playwright-cli` 載入完整的指令參考。
2. **Playwright MCP**（`mcp__plugin_playwright_playwright__*`）：用 `browser_resize` 改變 viewport。
3. **Chrome MCP**（`mcp__claude-in-chrome__*`）：用 `resize_window` 改變 viewport。使用的是使用者已登入的 Chrome session。

如果都沒有，告訴使用者，並建議安裝 playwright-cli 或 Playwright MCP。

## 運作模式

### 模式 1：標準檢查

**什麼時候**："check responsive"、"responsiveness check"、"test breakpoints"

測試涵蓋裝置範圍的 8 個關鍵斷點：

| 寬度 | 裝置情境 |
|-------|---------------|
| 320px | 小手機（iPhone SE） |
| 375px | 標準手機（iPhone 14） |
| 768px | 平板直向（iPad） |
| 1024px | 平板橫向 / 小筆電 |
| 1280px | 筆電 |
| 1440px | 桌機 |
| 1920px | Full HD |
| 2560px | 超寬 / 4K |

**流程**：

1. 在單一瀏覽器 session 裡打開 URL（高度：900px）
2. 從 320px 開始。對每個斷點寬度：
   a. 調整 viewport
   b. 稍等一下讓 CSS 重排（版面轉場）
   c. 對首屏區域截圖
   d. 如果頁面有大量首屏以下的內容，就捲動並截圖
   e. 執行 8 項版面檢查（見下方矩陣）
   f. 記下任何問題與嚴重度
3. 比較相鄰的寬度，找出版面在哪裡轉換
4. 寫報告

### 模式 2：掃描

**什麼時候**："responsive sweep"、"sweep all breakpoints"、"find where it breaks"

從 320 到 2560，每 160px 測一次（共 15 個寬度）。跟標準模式一樣用單一 session，只是資料點更多。這個模式是用來找出版面壞掉的**精確寬度**。

寬度：320、480、640、800、960、1120、1280、1440、1600、1760、1920、2080、2240、2400、2560

開始掃描模式之前要**簡短確認**（15 張截圖是個不小的 session）。

### 模式 3：指定範圍

**什麼時候**："check between 768 and 1024"、"test tablet breakpoints"、"focus on mobile widths"

以 80px 為間隔，測試使用者指定的範圍。已知某個區間有問題、需要詳細調查時使用。

範例："check between 768 and 1024" 會測：768、848、928、1008（再加上終點 1024）。

### 多個 URL

測試多個 URL 時（例如「檢查首頁、關於頁和聯絡頁」）：

- 啟動**平行的 sub-agent**，一個 URL 一個（不是一個斷點一個）
- 每個 sub-agent 在自己的具名 session 裡對它的 URL 執行標準檢查
- 把結果合併成一份報告

```
# Sub-agent pattern (playwright-cli)
playwright-cli -s=page1 open https://example.com/ &
playwright-cli -s=page2 open https://example.com/about &
```

## 版面檢查矩陣

這 8 項檢查針對的是**真的會隨 viewport 寬度變化**的問題：

| # | 檢查 | 要找什麼 |
|---|-------|-----------------|
| 1 | **水平溢出** | 內容比 viewport 寬：出現水平捲軸、元素被截掉 |
| 2 | **文字溢出** | 文字在字中間被截斷、和相鄰元素重疊、字體小到看不清楚（< 12px） |
| 3 | **導覽轉換** | 漢堡選單在正確的寬度出現/消失，兩種模式之間沒有「壞掉」的狀態 |
| 4 | **內容堆疊** | 多欄版面在窄寬度下，依合理的閱讀順序堆疊成單欄 |
| 5 | **圖片/媒體縮放** | 圖片溢出容器、長寬比變形、缺少響應式尺寸 |
| 6 | **觸控目標** | 手機寬度（< 768px）下互動元素 < 44px：按鈕、連結、表單輸入 |
| 7 | **留白平衡** | 手機上太擠（沒有喘息空間），寬螢幕上太空（內容迷失在空白裡） |
| 8 | **CTA 可見度** | 每個寬度下，主要的行動呼籲都在首屏可見，不用捲動 |

## 轉換偵測

這個 skill 獨特的價值，是**找出版面在哪裡轉換**，以及轉換乾不乾淨。

比較相鄰寬度的截圖時，遇到以下情況就標記那個寬度：
- **欄數改變**（3 欄 → 2 欄 → 1 欄的格狀）
- **導覽模式切換**（完整導覽 → 漢堡，或反過來）
- **側邊欄出現/消失**（內容寬度跳動）
- **格狀重排**（卡片換到下一列）

回報每次轉換發生的**精確寬度範圍**：

| 轉換 | 從 | 到 | 寬度範圍 |
|-----------|------|-----|-------------|
| 導覽：漢堡 → 完整 | 768px | 1024px | 約 960px 切換 |
| 格狀：1 欄 → 2 欄 | 640px | 768px | 約 700px 重排 |
| 側邊欄出現 | 1024px | 1280px | 約 1100px 顯示 |

這能讓開發者知道該在哪裡設定（或修正）他們的 CSS 斷點。

## 嚴重度等級

與 ux-audit 一致：

| 嚴重度 | 意義 |
|----------|---------|
| **Critical** | 版面壞掉：內容無法閱讀、導覽無法使用、頁面不能用 |
| **High** | 重大的版面問題：大幅溢出、關鍵內容被藏起來、轉換壞掉 |
| **Medium** | 看得出來但還能用：間距尷尬、輕微溢出、堆疊順序不理想 |
| **Low** | 精修：留白微調、輕微的對齊問題、觸控目標稍微不足 |

## 自主規則

- **直接做**：調整 viewport、截圖、分析版面、比較寬度
- **簡短確認**：掃描模式之前（15 個 viewport）、平行測試 4 個以上 URL 之前
- **先問**：與表單互動，或點過認證流程之前

## 報告輸出

把報告寫到 `docs/responsiveness-check-YYYY-MM-DD.md`（單頁快速檢查則直接內嵌回覆）。

報告結構見 [references/report-template.md](references/report-template.md)。

## 參考檔案

| 什麼時候 | 讀什麼 |
|------|------|
| 查詢斷點細節和問題區間 | [references/breakpoints.md](references/breakpoints.md) |
| 撰寫響應式報告 | [references/report-template.md](references/report-template.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) |