playwright-responsive-screenshots

What this skill does

# Playwright Responsive Screenshots

## Quick Start

Capture screenshots across standard breakpoints in one command:

```
Capture responsive screenshots of https://example.com at mobile, tablet, and desktop breakpoints
```

This skill automates:
- Browser window resizing to standard breakpoints
- Layout settling wait times
- Full-page screenshot capture
- Organized file naming with breakpoint identifiers
- Optional comparison report generation

## Table of Contents

1. When to Use This Skill
2. What This Skill Does
3. Standard Breakpoints
4. Instructions
   4.1. Basic Screenshot Capture
   4.2. Custom Breakpoints
   4.3. Multiple Pages
   4.4. With Comparison Report
5. Supporting Files
6. Expected Outcomes
7. Requirements
8. Red Flags to Avoid

## When to Use This Skill

**Explicit Triggers:**
- "Test responsive design for [URL]"
- "Screenshot at breakpoints"
- "Capture mobile and desktop views of [page]"
- "Validate responsive layout"
- "Generate screenshots for design review"

**Implicit Triggers:**
- User mentions testing across devices
- Request for multi-device validation
- Need to document responsive behavior
- Visual regression testing setup
- Design system breakpoint validation

**Debugging Scenarios:**
- Layout breaks at certain viewport widths
- Media query verification needed
- CSS breakpoint testing
- Responsive component validation

## What This Skill Does

This skill provides an automated workflow for capturing screenshots at multiple viewport sizes:

1. **Define breakpoints** - Use standard or custom viewport dimensions
2. **Navigate to target** - Open the URL in Playwright browser
3. **Resize and capture** - For each breakpoint: resize window, wait for layout, screenshot
4. **Organize output** - Name files with breakpoint identifiers (e.g., `homepage-mobile.png`)
5. **Generate report** - Optional comparison table with screenshot paths

**Key Benefits:**
- Consistent viewport sizes across captures
- Proper layout settling before screenshots
- Organized file naming convention
- Full-page screenshots by default
- Reproducible test results

## Standard Breakpoints

This skill uses industry-standard breakpoints by default:

| Device Category | Width × Height | Common Devices |
|----------------|----------------|----------------|
| **Mobile** | 375 × 667 | iPhone SE, iPhone 12/13/14 |
| **Tablet** | 768 × 1024 | iPad, iPad Mini, Android tablets |
| **Desktop** | 1920 × 1080 | Standard HD desktop/laptop |

**Breakpoint Selection Rationale:**
- Mobile: Most common iPhone viewport (covers ~40% of mobile traffic)
- Tablet: Standard iPad portrait orientation
- Desktop: 1080p standard (most common desktop resolution)

**When to Use Custom Breakpoints:**
- Testing specific device models
- Validating custom media query breakpoints
- Client-specific device requirements
- Edge case viewport testing (ultra-wide, small tablets, etc.)

## Instructions

### 4.1. Basic Screenshot Capture

**Workflow:**

1. **Define target and breakpoints**
   ```
   URL: https://example.com/page
   Breakpoints: mobile, tablet, desktop (standard)
   ```

2. **Navigate to page**
   - Use `browser_navigate` to open URL
   - Verify page loads successfully

3. **For each breakpoint:**
   - **Resize browser window** using `browser_resize`
   - **Wait for layout to settle** using `browser_wait_for` (1 second minimum)
   - **Capture full-page screenshot** using `browser_take_screenshot` with `fullPage: true`
   - **Name file descriptively**: `{page-name}-{breakpoint}.png`

4. **Organize screenshots**
   - Save to predictable location (e.g., `screenshots/`)
   - Group by page or breakpoint as appropriate

5. **Confirm completion**
   - Report number of screenshots captured
   - List file paths for user verification

**Example:**
```
User: "Capture responsive screenshots of https://myapp.dev/dashboard"

Assistant workflow:
1. browser_navigate to https://myapp.dev/dashboard
2. browser_resize(375, 667) → wait 1s → browser_take_screenshot("dashboard-mobile.png", fullPage: true)
3. browser_resize(768, 1024) → wait 1s → browser_take_screenshot("dashboard-tablet.png", fullPage: true)
4. browser_resize(1920, 1080) → wait 1s → browser_take_screenshot("dashboard-desktop.png", fullPage: true)
5. Report: "Captured 3 screenshots: dashboard-mobile.png, dashboard-tablet.png, dashboard-desktop.png"
```

### 4.2. Custom Breakpoints

**When user specifies custom viewport sizes:**

1. **Parse breakpoint specifications**
   - Accept formats: "414x896" or "414 x 896" or "width: 414, height: 896"
   - Validate dimensions are reasonable (width 200-3840, height 200-2160)

2. **Name custom breakpoints descriptively**
   - Use width for identifier: "homepage-414w.png"
   - Or use user-provided labels: "homepage-iphone14pro.png"

3. **Follow same workflow**
   - Navigate → Resize → Wait → Capture
   - Apply 1-second wait minimum after resize

**Example:**
```
User: "Screenshot https://app.com at 414x896 (iPhone 14 Pro) and 393x851 (Pixel 7)"

Assistant workflow:
1. browser_navigate to https://app.com
2. browser_resize(414, 896) → wait 1s → browser_take_screenshot("app-iphone14pro.png", fullPage: true)
3. browser_resize(393, 851) → wait 1s → browser_take_screenshot("app-pixel7.png", fullPage: true)
```

### 4.3. Multiple Pages

**For testing multiple pages at standard breakpoints:**

1. **Create page list**
   - Extract page names from URLs for file naming
   - Examples: "/dashboard" → "dashboard", "/settings/profile" → "settings-profile"

2. **Nested loop structure**
   - Outer loop: pages
   - Inner loop: breakpoints
   - Alternative: breakpoints outer, pages inner (user preference)

3. **Naming convention**
   - `{page-name}-{breakpoint}.png`
   - Example: `dashboard-mobile.png`, `dashboard-tablet.png`, `settings-mobile.png`

4. **Optimize navigation**
   - Navigate once per page (before breakpoint loop)
   - Resize/capture without re-navigating

**Example:**
```
User: "Capture responsive screenshots for /home, /products, and /about pages on https://shop.com"

Assistant workflow:
For each page in ["/home", "/products", "/about"]:
  1. browser_navigate to https://shop.com{page}
  2. For each breakpoint in [mobile, tablet, desktop]:
     - browser_resize(width, height)
     - browser_wait_for(1 second)
     - browser_take_screenshot("{page-name}-{breakpoint}.png", fullPage: true)

Result: 9 screenshots (3 pages × 3 breakpoints)
```

### 4.4. With Comparison Report

**Generate markdown report after screenshot capture:**

1. Capture screenshots (as above)
2. Create markdown table with embedded images and metadata
3. Save to `screenshots/report.md` (or user-specified location)
4. Include timestamp, URL, dimensions, and layout notes

See `examples/examples.md` for full report template example.

## Supporting Files

### references/playwright-api.md

Playwright MCP tool reference for screenshot operations:
- `browser_navigate` - Navigation and URL handling
- `browser_resize` - Viewport dimension control
- `browser_wait_for` - Waiting strategies for layout settling
- `browser_take_screenshot` - Screenshot capture options

### examples/examples.md

Comprehensive screenshot capture examples:
- Standard breakpoint captures
- Custom device viewports
- Multi-page workflows
- Report generation
- Edge cases (ultra-wide, mobile landscape, etc.)

### scripts/validate_screenshots.py

Python utility to validate screenshot dimensions match expected breakpoints.

## Expected Outcomes

### Successful Screenshot Capture

```
✅ Responsive Screenshots Captured

URL: https://example.com/homepage
Breakpoints: mobile, tablet, desktop
Pages: 1

Screenshots:
  ✓ homepage-mobile.png (375×667, 234KB)
  ✓ homepage-tablet.png (768×1024, 512KB)
  ✓ homepage-desktop.png (1920×1080, 1.2MB)

Location: /Users/username/screenshots/
Total time: 8.3 seconds

All screenshots captured successfully. Full-page screenshots enabled.
```

### With Comparison Report

```
✅ Responsive Screenshots Captured with Report

URL: https://shop.com
Breakpoints: