Screenshot-Based UI Verification

Visual verification workflow for UI changes to accelerate code review and catch responsive design issues early.

When to Use This Skill

Use this skill when:

• Making any UI changes (components, styling, layout)
• Implementing responsive design
• Creating pull requests with visual changes
• Want to demonstrate UI behavior without reviewers running code locally
• Need to document visual state before/after bug fixes

Why Screenshot Verification Matters

Benefits

• Faster Reviews: Reviewers see changes instantly without local setup
• Documents Design: Creates visual record of design decisions
• Visual Changelog: Historical record of UI evolution
• Catches Responsive Issues: Early detection of mobile/tablet problems
• Reduces Communication: Less back-and-forth about visual changes
• Quality Gate: Forces conscious review of visual output

Problems It Solves

• ❌ "I can't reproduce the layout issue locally"
• ❌ "What does this look like on mobile?"
• ❌ "Is this the intended design?"
• ❌ "How does this compare to the old version?"
• ✅ All answered with screenshots in PR

Required Screenshots

For any PR that changes UI, capture all three viewport sizes:

1. Desktop View (1920x1080)

• Full page screenshot
• Key component close-ups if needed
• Before and after comparisons (for fixes/refactors)
• Different states (default, hover, active, error, loading)

2. Tablet View (768x1024)

• Portrait orientation
• Verify responsive breakpoints
• Touch interaction targets visible
• Menu/navigation in tablet mode

3. Mobile View (375x667)

• Portrait orientation (iPhone 8/SE size - common minimum)
• Touch target sizes visible (minimum 44x44px)
• Scrolling behavior documented
• Mobile menu states

How to Capture Screenshots

Browser DevTools Method

Chrome/Edge DevTools:

1. Open DevTools (F12 or Cmd+Option+I)
2. Toggle device toolbar (Cmd+Shift+M or Ctrl+Shift+M)
3. Select device preset or custom dimensions:
   • Desktop: 1920 x 1080
   • Tablet: 768 x 1024
   • Mobile: 375 x 667
4. Capture screenshot:
   • Full page: Cmd+Shift+P → "Capture full size screenshot"
   • Viewport only: Cmd+Shift+P → "Capture screenshot"

Firefox DevTools:

1. Open DevTools (F12)
2. Toggle Responsive Design Mode (Cmd+Option+M)
3. Set dimensions
4. Click screenshot icon in toolbar

CLI Screenshot Tools

Using Playwright (recommended for CI):

// screenshot.js
const { chromium } = require('playwright');

async function captureScreenshots(url) {
  const browser = await chromium.launch();
  const page = await browser.newPage();

  await page.goto(url);

  // Desktop
  await page.setViewportSize({ width: 1920, height: 1080 });
  await page.screenshot({
    path: 'screenshots/desktop.png',
    fullPage: true
  });

  // Tablet
  await page.setViewportSize({ width: 768, height: 1024 });
  await page.screenshot({
    path: 'screenshots/tablet.png',
    fullPage: true
  });

  // Mobile
  await page.setViewportSize({ width: 375, height: 667 });
  await page.screenshot({
    path: 'screenshots/mobile.png',
    fullPage: true
  });

  await browser.close();
}

captureScreenshots('http://localhost:3000');

Run: node screenshot.js

Using Puppeteer:

// screenshot.js
const puppeteer = require('puppeteer');

async function captureScreenshots(url) {
  const browser = await puppeteer.launch();
  const page = await browser.newPage();

  await page.goto(url, { waitUntil: 'networkidle2' });

  // Desktop
  await page.setViewport({ width: 1920, height: 1080 });
  await page.screenshot({
    path: 'screenshots/desktop.png',
    fullPage: true
  });

  // Tablet
  await page.setViewport({ width: 768, height: 1024 });
  await page.screenshot({
    path: 'screenshots/tablet.png',
    fullPage: true
  });

  // Mobile
  await page.setViewport({ width: 375, height: 667 });
  await page.screenshot({
    path: 'screenshots/mobile.png',
    fullPage: true
  });

  await browser.close();
}

captureScreenshots('http://localhost:3000');

PR Description Template

Use this template to document visual changes:

## Visual Changes

### Desktop (1920x1080)
![Desktop view](./screenshots/desktop.png)

**Key changes**:
- Updated header navigation layout
- Improved spacing between sections
- Added hover states to buttons

### Tablet (768x1024)
![Tablet view](./screenshots/tablet.png)

**Key changes**:
- Stacked layout for sidebar
- Touch-friendly button sizes (48x48px)
- Adjusted typography for readability

### Mobile (375x667)
![Mobile view](./screenshots/mobile.png)

**Key changes**:
- Hamburger menu replaces horizontal nav
- Single column layout
- Bottom sticky CTA button

### Before/After Comparison

#### Before (Bug)
![Before fix](./screenshots/before-mobile.png)

**Issue**: Text overflowing container on mobile

#### After (Fixed)
![After fix](./screenshots/after-mobile.png)

**Fix**: Applied word-wrap and max-width constraints

### Interaction States

#### Default State
![Default](./screenshots/state-default.png)