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 スタイリング手法の特定

手法	検出方法	編集対象
純粋な 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 検査項目

検査中および修正後の検証時に再度、references/visual-checklist.md に沿って作業を進めてください。

レイアウトの問題

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

レスポンシブの問題

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

アクセシビリティの問題

問題	説明	重要度
コントラスト不足	テキストと背景のコントラスト比が低い	高
フォーカス状態なし	キーボードナビゲーション時に状態を判別できない	高
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. ユーザーに影響範囲を確認する