screenshot

スクリーンショットによる UI 検証

UI の変更を視覚的に検証するワークフローです。コードレビューを効率化し、レスポンシブデザインの問題を早期に発見できます。

このスキルを使う場面

次の場合にこのスキルを使います：

• UI に変更を加える場合（コンポーネント、スタイル、レイアウト）
• レスポンシブデザインを実装する場合
• 視覚的な変更を含むプルリクエストを作成する場合
• レビュアーにローカルでコードを実行してもらわずに、UI の動作を示したい場合
• バグ修正前後の視覚的な状態を記録する必要がある場合

スクリーンショットによる検証が重要な理由

メリット

• レビューの迅速化：レビュアーはローカル環境をセットアップせずに、変更をすぐに確認できます
• デザインの記録：デザイン上の判断を視覚的に記録できます
• 視覚的な変更履歴：UI の変遷を記録できます
• レスポンシブデザインの問題を発見：モバイルやタブレットでの問題を早期に検出できます
• コミュニケーションの削減：視覚的な変更に関するやり取りを減らせます
• 品質ゲート：視覚的な出力を意識的に確認するよう促します

解決できる問題

• ❌「レイアウトの問題をローカルで再現できません」
• ❌「モバイルではどのように表示されますか？」
• ❌「これが意図したデザインですか？」
• ❌「以前のバージョンと比べてどうですか？」
• ✅ これらすべてに、PR のスクリーンショットで回答できます

必須のスクリーンショット

UI を変更する PR では、3 種類すべてのビューポートサイズで撮影してください。

1. デスクトップ表示（1920x1080）

• ページ全体のスクリーンショット
• 必要に応じて主要コンポーネントの拡大画像
• 修正やリファクタリングの場合は変更前と変更後の比較
• 状態の違い（デフォルト、ホバー、アクティブ、エラー、読み込み中）

2. タブレット表示（768x1024）

• 縦向き
• レスポンシブのブレークポイントを確認
• タッチ操作の対象が見えること
• タブレットモードでのメニューやナビゲーション

3. モバイル表示（375x667）

• 縦向き（一般的な最小サイズである iPhone 8／SE のサイズ）
• タッチ対象のサイズが見えること（最小 44x44px）
• スクロール時の動作を記録
• モバイルメニューの状態

スクリーンショットの撮影方法

ブラウザーの DevTools を使う方法

Chrome／Edge DevTools：

1. DevTools を開きます（F12 または Cmd+Option+I）
2. デバイスツールバーを切り替えます（Cmd+Shift+M または Ctrl+Shift+M）
3. デバイスのプリセットまたはカスタムサイズを選択します：
   • デスクトップ：1920 x 1080
   • タブレット：768 x 1024
   • モバイル：375 x 667
4. スクリーンショットを撮影します：
   • ページ全体：Cmd+Shift+P →「Capture full size screenshot」
   • ビューポートのみ：Cmd+Shift+P →「Capture screenshot」

Firefox DevTools：

1. DevTools を開きます（F12）
2. レスポンシブデザインモードを切り替えます（Cmd+Option+M）
3. サイズを設定します
4. ツールバーのスクリーンショットアイコンをクリックします

CLI スクリーンショットツール

Playwright を使う方法（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');

実行：node screenshot.js

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 説明テンプレート

このテンプレートを使って、視覚的な変更を記録してください：

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

#### Hover State
![Hover](./screenshots/state-hover.png)

#### Active/Selected State
![Active](./screenshots/state-active.png)

#### Error State
![Error](./screenshots/state-error.png)

#### Loading State
![Loading](./screenshots/state-loading.png)

## Responsive Design Notes
- Breakpoints: 768px (tablet), 375px (mobile)
- All touch targets > 44x44px
- Text remains readable at all sizes (min 16px body)
- No horizontal scrolling on any viewport
- Images scale proportionally

## Accessibility Checks
- [ ] Keyboard navigation works
- [ ] Focus states visible
- [ ] Color contrast meets WCAG AA (4.5:1)
- [ ] Alt text on images
- [ ] ARIA labels where needed

スクリーンショットの自動テスト

Playwright Test を使う方法

// tests/visual.spec.js
const { test, expect } = require('@playwright/test');

test.describe('Visual Regression', () => {
  test('homepage looks correct on desktop', async ({ page }) => {
    await page.goto('http://localhost:3000');
    await page.setViewportSize({ width: 1920, height: 1080 });
    await expect(page).toHaveScreenshot('homepage-desktop.png');
  });

  test('homepage looks correct on mobile', async ({ page }) => {
    await page.goto('http://localhost:3000');
    await page.setViewportSize({ width: 375, height: 667 });
    await expect(page).toHaveScreenshot('homepage-mobile.png');
  });
});

実行：npx playwright test --update-snapshots（初回にベースラインを生成します）

Storybook + Chromatic を使う方法

コンポーネント単位の視覚的なテストの場合：

1. Storybook をセットアップ：

// Button.stories.jsx
export default {
  title: 'Components/Button',
  component: Button,
};

export const Primary = () => <Button variant="primary">Click me</Button>;
export const Secondary = () => <Button variant="secondary">Click me</Button>;

2. Chromatic を統合：

npm install --save-dev chromatic
npx chromatic --project-token=<token>

3. CI との統合（GitHub Actions）：

# .github/workflows/chromatic.yml
name: Chromatic
on: push
jobs:
  chromatic:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npx chromatic --project-token=${{ secrets.CHROMATIC_TOKEN }}

スクリーンショットのチェックリスト

UI の変更を含む PR を提出する前に確認してください：

撮影要件

• デスクトップのスクリーンショット（1920x1080）を撮影した
• タブレットのスクリーンショット（768x1024）を撮影した
• モバイルのスクリーンショット（375x667）を撮影した
• すべてのスクリーンショットを PR にアップロードした
• バグ修正の場合、変更前後の比較を含めた

品質チェック

• スクリーンショットにページ全体が表示されている（途中で切れていない）
• スクリーンショットに localhost の URL が表示されていない
• スクリーンショットに機密データ（PII、キーなど）が含まれていない
• スクリーンショットが鮮明で読みやすい
• ファイル名が内容を表している（例：desktop-homepage.png）

ドキュメント

• 各ビューポートでの主な変更点を記載した
• レスポンシブ時の動作を説明した
• アクセシビリティに関する注意事項を含めた
• 該当する場合、操作時の状態を記録した

よくある問題と解決策

問題：スクリーンショットのファイルサイズが大きすぎる

問題：スクリーンショットが 5MB 以上あり、PR の読み込みが遅くなります 解決策：アップロードする前に画像を圧縮します

# Using ImageMagick
convert input.png -quality 85 output.png

# Using pngquant
pngquant input.png --output output.png

問題：スクリーンショット間で動的コンテンツが変化する

問題：タイムスタンプやランダムデータによって、スクリーンショットに一貫性がなくなります 解決策：テストでモックデータを使用するか、時間を固定します

// Mock Date
const mockDate = new Date('2025-01-01T00:00:00Z');
jest.useFakeTimers();
jest.setSystemTime(mockDate);

// Or in Playwright
await page.addInitScript(() => {
  Date.now = () => 1704067200000; // Fixed timestamp
});

問題：スクリーンショットの差分にフォントのレンダリングの違いが現れる

問題：同じコードでも、OS によって表示が異なります 解決策：一貫した環境を保つために Docker を使用します

FROM mcr.microsoft.com/playwright:v1.40.0-jammy
WORKDIR /app
COPY . .
RUN npm ci
CMD ["npm", "run", "screenshot"]

スクリーンショットの整理

ディレクトリ構成

screenshots/
├── desktop/
│   ├── homepage.png
│   ├── product-list.png
│   └── checkout.png
├── tablet/
│   ├── homepage.png
│   ├── product-list.png
│   └── checkout.png
└── mobile/
    ├── homepage.png
    ├── product-list.png
    └── checkout.png

命名規則

• 内容が分かる名前を付けます：desktop-homepage-logged-in.png
• 関連する場合は状態を含めます：mobile-form-error-state.png
• バージョンを比較します：before-header-fix.png、after-header-fix.png

CI/CD との統合

GitHub Actions の例

name: Visual Testing
on: pull_request

jobs:
  screenshots:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install dependencies
        run: npm ci

      - name: Build app
        run: npm run build

      - name: Start app
        run: npm start &

      - name: Wait for app
        run: npx wait-on http://localhost:3000

      - name: Capture screenshots
        run: node scripts/screenshot.js

      - name: Upload screenshots
        uses: actions/upload-artifact@v4
        with:
          name: screenshots
          path: screenshots/

ベストプラクティス

推奨事項

• ✅ 3 種類すべてのビューポートサイズをキャプチャします
• ✅ バグ修正の前後を含めます
• ✅ 操作状態（ホバー、アクティブ、エラー）を記録します
• ✅ 大きな画像を圧縮します
• ✅ 内容が分かるファイル名を使用します
• ✅ 重要な変更点をスクリーンショットに注釈として付けます

避けるべきこと

• ❌ モバイルのスクリーンショットを省略します（「デスクトップのみ」はまれです）
• ❌ 機密データを含むスクリーンショットをアップロードします
• ❌ ランダムなビューポートサイズを使用します（標準に従ってください）
• ❌ レスポンシブのブレークポイントを記録し忘れます
• ❌ スクリーンショットだけに頼ります（コードレビューも必要です）

関連スキル

• universal-verification-pre-merge - マージ前の検証チェックリスト
• universal-testing-webapp-testing - Web アプリケーションのテストパターン
• toolchains-javascript-testing-playwright - Playwright テストフレームワーク
• universal-debugging-verification-before-completion - 検証ワークフロー