web-design-reviewer

Web デザインレビュー担当

このスキルは、Web サイトのデザイン品質を視覚的に検査・検証し、問題を特定してソースコードレベルで修正します。

適用範囲

• 静的サイト（HTML/CSS/JS）
• React / Vue / Angular / Svelte などの SPA フレームワーク
• Next.js / Nuxt / SvelteKit などのフルスタックフレームワーク
• WordPress / Drupal などの CMS プラットフォーム
• その他すべての Web アプリケーション

前提条件

必須

1. 対象の Web サイトが稼働していること

   • ローカル開発サーバー（例：http://localhost:3000）
   • ステージング環境
   • 本番環境（読み取り専用のレビューの場合）

2. ブラウザー自動化を利用できること

   • スクリーンショットの取得
   • ページ遷移
   • DOM 情報の取得

3. ソースコードにアクセスできること（修正を行う場合）

   • プロジェクトがワークスペース内に存在すること

ワークフローの概要

flowchart TD
    A[Step 1: Information Gathering] --> B[Step 2: Visual Inspection]
    B --> C[Step 3: Issue Fixing]
    C --> D[Step 4: Re-verification]
    D --> E{Issues Remaining?}
    E -->|Yes| B
    E -->|No| F[Completion Report]

---

ステップ 1：情報収集フェーズ

1.1 URL の確認

URL が指定されていない場合は、ユーザーに確認します。

レビュー対象の Web サイトの URL を指定してください（例：http://localhost:3000）

1.2 プロジェクト構成の把握

修正を行う場合は、次の情報を収集します。

項目	質問例
フレームワーク	React / Vue / Next.js などを使用していますか？
スタイリング方法	CSS / SCSS / Tailwind / CSS-in-JS など、何を使用していますか？
ソースの場所	スタイルファイルやコンポーネントはどこにありますか？
レビュー範囲	特定のページのみですか、それともサイト全体ですか？

1.3 プロジェクトの自動検出

ワークスペース内のファイルから自動検出を試みます。

Detection targets:
├── package.json     → Framework and dependencies
├── tsconfig.json    → TypeScript usage
├── tailwind.config  → Tailwind CSS
├── next.config      → Next.js
├── vite.config      → Vite
├── nuxt.config      → Nuxt
└── src/ or app/     → Source directory

1.4 スタイリング方法の特定

方法	検出方法	編集対象
Pure CSS	*.css ファイル	グローバル CSS またはコンポーネント CSS
SCSS/Sass	*.scss、*.sass	SCSS ファイル
CSS Modules	*.module.css	モジュール CSS ファイル
Tailwind CSS	tailwind.config.*	コンポーネント内の className
styled-components	コード内の styled.	JS/TS ファイル
Emotion	@emotion/ のインポート	JS/TS ファイル
CSS-in-JS（その他）	インラインスタイル	JS/TS ファイル

---

ステップ 2：視覚検査フェーズ

2.1 ページの巡回

1. 指定された URL に移動します
2. スクリーンショットを取得します
3. DOM 構造／スナップショットを取得します（可能な場合）
4. 他のページがある場合は、ナビゲーションをたどって巡回します

2.2 検査項目

レイアウトの問題

問題	説明	重大度
要素のはみ出し	コンテンツが親要素またはビューポートからはみ出している	高
要素の重なり	意図しない要素の重なり	高
配置の問題	グリッドまたはフレックスの配置に関する問題	中
余白の不統一	パディング／マージンの不統一	中
テキストの切り取り	長いテキストが適切に処理されていない	中

レスポンシブ対応の問題

問題	説明	重大度
モバイル非対応	小さな画面でレイアウトが崩れる	高
ブレークポイントの問題	画面サイズの変更時に不自然な切り替わりがある	中
タッチ対象	モバイルでボタンが小さすぎる	中

アクセシビリティの問題

問題	説明	重大度
コントラスト不足	テキストと背景のコントラスト比が低い	高
フォーカス状態がない	キーボード操作中の状態を判別できない	高
alt テキストがない	画像に代替テキストがない	中

視覚的一貫性

問題	説明	重大度
フォントの不統一	複数のフォントファミリーが混在している	中
色の不統一	ブランドカラーが統一されていない	中
余白の不統一	類似した要素間の余白が均一でない	低

2.3 ビューポートテスト（レスポンシブ）

次のビューポートでテストします。

名前	幅	代表的なデバイス
モバイル	375px	iPhone SE/12 mini
タブレット	768px	iPad
デスクトップ	1280px	標準的な PC
ワイド	1920px	大型ディスプレイ

---

ステップ 3：問題修正フェーズ

3.1 問題の優先順位付け

block-beta
    columns 1
    block:priority["Priority Matrix"]
        P1["P1: Fix Immediately\n(Layout issues affecting functionality)"]
        P2["P2: Fix Next\n(Visual issues degrading UX)"]
        P3["P3: Fix If Possible\n(Minor visual inconsistencies)"]
    end

3.2 ソースファイルの特定

問題のある要素からソースファイルを特定します。

1. セレクターによる検索

   • クラス名または ID でコードベースを検索します
   • grep_search を使ってスタイル定義を調べます

2. コンポーネントによる検索

   • 要素のテキストまたは構造からコンポーネントを特定します
   • semantic_search を使って関連ファイルを調べます

3. ファイルパターンによる絞り込み

   Style files: src/**/*.css, styles/**/*
   Components: src/components/**/*
   Pages: src/pages/**, app/**
   

3.3 修正の適用

フレームワーク固有の修正ガイドライン

詳細については、references/framework-fixes.md を参照してください。

修正の原則

1. 変更を最小限にする：問題の解決に必要な最小限の変更だけを行います
2. 既存のパターンを尊重する：プロジェクトの既存のコードスタイルに従います
3. 破壊的変更を避ける：ほかの領域に影響しないよう注意します
4. コメントを追加する：必要に応じて、修正理由を説明するコメントを追加します

---

ステップ 4：再検証フェーズ

4.1 修正後の確認

1. ブラウザーを再読み込みします（または開発サーバーの HMR が反映されるまで待ちます）
2. 修正した領域のスクリーンショットを撮影します
3. 修正前と修正後を比較します

4.2 回帰テスト

• 修正がほかの領域に影響していないことを確認します
• レスポンシブ表示が崩れていないことを確認します

4.3 反復の判断

flowchart TD
    A{Issues Remaining?}
    A -->|Yes| B[Return to Step 2]
    A -->|No| C[Proceed to Completion Report]

反復回数の上限：特定の問題に対して修正を 3 回以上試みる必要がある場合は、ユーザーに相談してください

---

出力形式

レビュー結果レポート

# Web Design Review Results

## Summary

| Item | Value |
|------|-------|
| Target URL | {URL} |
| Framework | {Detected framework} |
| Styling | {CSS / Tailwind / etc.} |
| Tested Viewports | Desktop, Mobile |
| Issues Detected | {N} |
| Issues Fixed | {M} |

## Detected Issues

### [P1] {Issue Title}

- **Page**: {Page path}
- **Element**: {Selector or description}
- **Issue**: {Detailed description of the issue}
- **Fixed File**: `{File path}`
- **Fix Details**: {Description of changes}
- **Screenshot**: Before/After

### [P2] {Issue Title}
...

## Unfixed Issues (if any)

### {Issue Title}
- **Reason**: {Why it was not fixed/could not be fixed}
- **Recommended Action**: {Recommendations for user}

## Recommendations

- {Suggestions for future improvements}

---

必要な機能

機能	説明	必須
Web ページのナビゲーション	URL へのアクセス、ページ遷移	✅
スクリーンショットの撮影	ページ画像の撮影	✅
画像分析	視覚的な問題の検出	✅
DOM の取得	ページ構造の取得	推奨
ファイルの読み書き	ソースコードの読み取りと編集	修正に必須
コード検索	プロジェクト内のコード検索	修正に必須

---

リファレンス実装

Playwright MCP による実装

このスキルのリファレンス実装として、Playwright MCP を推奨します。

機能	Playwright MCP ツール	目的
ナビゲーション	browser_navigate	URL へのアクセス
スナップショット	browser_snapshot	DOM 構造の取得
スクリーンショット	browser_take_screenshot	目視確認用の画像
クリック	browser_click	インタラクティブ要素の操作
リサイズ	browser_resize	レスポンシブテスト
コンソール	browser_console_messages	JS エラーの検出

設定例（MCP サーバー）

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest", "--caps=vision"]
    }
  }
}

その他の互換性のあるブラウザー自動化ツール

ツール	特徴
Selenium	幅広いブラウザーと言語をサポート
Puppeteer	Chrome/Chromium に特化、Node.js
Cypress	E2E テストとの統合が容易
WebDriver BiDi	標準化された次世代プロトコル

これらのツールでも同じワークフローを実装できます。必要な機能（ナビゲーション、スクリーンショット、DOM の取得）が備わっていれば、使用するツールは柔軟に選べます。

---

ベストプラクティス

DO（推奨）

• ✅ 修正を行う前に、必ずスクリーンショットを保存します
• ✅ 一度に 1 つの問題を修正し、それぞれを検証します
• ✅ プロジェクトの既存のコードスタイルに従います
• ✅ 大規模な変更を行う前に、ユーザーに確認します
• ✅ 修正の詳細を十分に記録します

DON'T（非推奨）

• ❌ 確認を得ずに大規模なリファクタリングを行う
• ❌ デザインシステムやブランドガイドラインを無視する
• ❌ パフォーマンスを考慮しない修正を行う
• ❌ 複数の問題を一度に修正する（検証が困難になります）

---

トラブルシューティング

問題：スタイルファイルが見つからない

1. package.json の依存関係を確認します
2. CSS-in-JS の可能性を検討します
3. ビルド時に CSS が生成される可能性を検討します
4. ユーザーにスタイリング方法を確認します

問題：修正が反映されない

1. 開発サーバーの HMR が動作しているか確認します
2. ブラウザーのキャッシュを消去します
3. プロジェクトでビルドが必要な場合は、再ビルドします
4. CSS の詳細度に関する問題を確認します

問題：ほかの領域にも影響する修正

1. 変更をロールバックします
2. より具体的なセレクターを使用します
3. CSS Modules またはスコープ付きスタイルの使用を検討します
4. 影響範囲を確認するため、ユーザーに相談します