design-review

構築されたものを設計仕様書と選択された美的哲学に基づいて測定し、構造化された設計レビューを実行します。

重要 — ビジュアルスクリーンショット取得

設計レビューの一部として、実行されているアプリケーションのスクリーンショットを必ず取得する必要があります。コードレビューだけでは不十分です。ユーザーが見るものを見る必要があります。以下のステップ3のスクリーンショット取得プロトコルに従ってください。これはオプションではありません。

プロンプト例

• "Review what I just built"
• "Run a design critique on the landing page"
• "Check this against the brief"
• "Here's a screenshot. How does it look?" [スクリーンショットを貼り付け]
• "QA pass before I ship this"

プロセス

1. 仕様書を読む。 .design/<feature-slug>/DESIGN_BRIEF.md でアクティブな機能の仕様書を探します。.design/ の下に複数の機能フォルダが存在する場合は、ユーザーにどの機能をレビューするかを尋ねます。.design/ フォルダが存在しない場合は、プロジェクトルートの DESIGN_BRIEF.md にフォールバックします。どちらも存在しない場合は、ユーザーに想定される設計方向を尋ねます。

2. 構築されたコードを調べる。 作成または変更されたすべてのコンポーネント、ページ、スタイルファイルを検査します。特に以下の点をスキャンします：

   • すべての新規または変更されたコンポーネントと既存コンポーネントとの関係
   • トークン/変数の使用：コンポーネントが共有トークンを使用しているか、ハードコードされた値を使用しているか
   • 統合されるべき重複コンポーネント
   • ファイル命名と組織：新しいファイルがプロジェクトの慣例に従っているか
   • 実際に構築されたもの、計画されたものではなく理解する

3. 実行されているアプリケーションのスクリーンショットを取得します。

   このステップは 必須 です。スキップしないでください。ユーザーから提供されたスクリーンショットのみに依存しないでください。

   スクリーンショットツールの優先度

   各オプションを順番に試します。利用可能な最初のものを使用します：

   1. Playwright MCP（推奨）。 plugin-playwright-playwright MCP サーバーが利用可能かどうかを確認します。利用可能な場合は、それを使用してください。ビューポートサイズ、全ページキャプチャ、ファイル命名を正確に制御できます。
   2. Cursor IDE ブラウザ（第二選択肢）。 Playwright MCP が利用できない場合は、代わりに cursor-ide-browser MCP サーバーの browser_take_screenshot ツールを使用します。同じコア機能があります。
   3. ユーザーに依頼する（最後の手段）。 MCP サーバーもアプリ内ブラウザも利用できない場合は、ユーザーにスクリーンショットの手動提供を依頼する 必須 です。具体的に説明してください：
      • "I don't have access to a browser tool. To complete the visual review I need screenshots of the running application. Please provide:"
      • デスクトップ 幅（1280px）の全ページスクリーンショット
      • タブレット 幅（768px）の全ページスクリーンショット
      • モバイル 幅（375px）の全ページスクリーンショット
      • ダークモードバリアント（該当する場合）
      • レビュー対象の特定のコンポーネントまたはインタラクティブ状態
      • ユーザーに画像をチャットに直接貼り付け/添付するか、自分で screenshots/ フォルダに保存するよう依頼します。
      • ビジュアルレビューをスキップしないでください。 チェックリストを進める前に、ユーザーがスクリーンショットを提供するのを待ちます。

   スクリーンショット保存場所

   すべてのスクリーンショットは、機能の .design/ ディレクトリ内の screenshots/ サブフォルダに保存する 必須 です。DESIGN_BRIEF.md と他の設計フロー ファイルが存在するのと同じフォルダです。

   パスパターン：.design/<feature-slug>/screenshots/

   仕様書が .design/onboarding-flow/DESIGN_BRIEF.md にある場合、スクリーンショットは .design/onboarding-flow/screenshots/ に移動します。フォルダが存在しない場合は作成します。

   .design/ フォルダが存在しない場合（レガシープロジェクトまたはスタンドアロンレビュー）、プロジェクトルートの screenshots/ フォルダにフォールバックします。

   キャプチャされた内容をエンコードする説明的なファイル名を使用します：

   .design/
   └── onboarding-flow/
       ├── DESIGN_BRIEF.md
       ├── DESIGN_REVIEW.md
       └── screenshots/
           ├── review-homepage-desktop-1280.png
           ├── review-homepage-tablet-768.png
           ├── review-homepage-mobile-375.png
           ├── review-homepage-dark-mode-desktop-1280.png
           └── review-card-component-hover.png
   

   スクリーンショット取得プロトコル

   a. アプリケーションに移動します。 プロジェクトから明らかでない場合（例：http://localhost:3000）、ユーザーに URL を尋ねます。browser_navigate を使用して開きます。

   b. レスポンシブブレークポイントをキャプチャします。 最低限、すべての主要なページ/ビューに対してこれら3つのビューポートをキャプチャします：

   ブレークポイント	幅 × 高さ	ファイル名サフィックス
   Mobile	375 × 812	-mobile-375
   Tablet	768 × 1024	-tablet-768
   Desktop	1280 × 800	-desktop-1280

   各スクリーンショットの前に browser_resize を使用してビューポートを設定します。fullPage: true で browser_take_screenshot を使用してスクロール可能なページ全体をキャプチャし、screenshots/ フォルダを指す filename パラメータで保存します。

   Playwright MCP の例シーケンス（機能スラッグが onboarding-flow と仮定）：

   1. browser_navigate → { url: "http://localhost:3000" }
   2. browser_resize   → { width: 1280, height: 800 }
   3. browser_take_screenshot → { type: "png", filename: ".design/onboarding-flow/screenshots/review-homepage-desktop-1280.png", fullPage: true }
   4. browser_resize   → { width: 768, height: 1024 }
   5. browser_take_screenshot → { type: "png", filename: ".design/onboarding-flow/screenshots/review-homepage-tablet-768.png", fullPage: true }
   6. browser_resize   → { width: 375, height: 812 }
   7. browser_take_screenshot → { type: "png", filename: ".design/onboarding-flow/screenshots/review-homepage-mobile-375.png", fullPage: true }
   

   c. インタラクティブな状態をキャプチャします（関連する場合）。

   • ボタン、カード、リンクのホバー状態
   • フォームフィールドのフォーカス状態
   • ドロップダウン、モーダル、メニューのオープン状態
   • フォームのエラー/成功状態
   • ローディングおよび空の状態

   d. ダークモードをキャプチャします（プロジェクトがサポートしている場合）。 ダークモードを切り替え、ファイル名に -dark-mode を含めてレスポンシブブレークポイントキャプチャを繰り返します。

   e. 特定のコンポーネントをキャプチャします。 レビューが特定のコンポーネントに焦点を当てている場合、element および ref パラメータを使用してそのコンポーネントのみをスクリーンショットします。

   すべてのスクリーンショットを分析します

   キャプチャ後、設計仕様書に対して各スクリーンショットをビジュアルで分析します。各スクリーンショットについて：

   • 仕様書の美的方向と比較
   • ビジュアルヒエラルキーをチェック：最も重要な要素が最も目立っているか
   • スペーシング一貫性をチェック：マージンとパディングが均等で意図的に見えるか
   • 色をチェック：パレットが仕様書の方向と一致しているか
   • タイポグラフィをチェック：フォントサイズ、ウェイト、スペーシングが視覚的に正しいか
   • レスポンシブ適応をチェック：レイアウトが適切に再構成されているか（単に縮小されていないか）
   • コードレビューだけでは見逃すレンダリング問題に注意（フォント読み込み失敗、破損した画像、レイアウトオーバーフロー、z-indexの問題、不正なborder-radius、色の不一致）

   レビュー出力で特定のスクリーンショットをファイル名で参照し、調査結果をトレース可能にします。

4. 以下のレビューチェックリストを実行します。 各カテゴリについて、何が合格し、何が改善が必要かを注記します。具体的に。正確なコンポーネント、ファイル、行番号、スクリーンショット ファイル名を参照します。

5. 優先順位付けされた改善リストを作成します。 問題を重大度でグループ化します：

   • 必須修正：破損した機能、アクセシビリティの失敗、仕様書からの大きな逸脱。
   • 修正すべき：矛盾、欠落した状態、レスポンシブの問題。
   • 改善可能：ポーランド、アニメーション調整、タイポグラフィの微調整。

6. 機能の .design/<feature-slug>/ フォルダ内（DESIGN_BRIEF.md の隣）にレビューを DESIGN_REVIEW.md として保存します。.design/ フォルダが存在しない場合は、プロジェクトルートに保存します。取得されたすべてのスクリーンショットをそのパスで一覧にした「スクリーンショット取得」セクションを含めます。ユーザーが希望する場合は、レビューを直接提示します。

レビューチェックリスト

ビジュアルヒエラルキー

• 各ページ/ビューで最も重要なコンテンツが最も視覚的に目立っているか
• タイプスケールが明確な重要度レベル（見出し、副見出し、本文、キャプション）を作成しているか
• インタラクティブ要素（ボタン、リンク、入力）に見つけるために検索する必要がないほどの視覚的な重さがあるか
• 明確な読む順序があるか。視線がどこに最初に、2番目に、3番目に行くかを追跡できるか

一貫性

• スペーシング値は一貫しているか。確立されたスケール（4px/8px ベースなど）に対してパディングとマージンをチェック
• 色は一貫して使用されているか。同じセマンティック意味が常に同じ色にマップされているかを確認（プライマリアクション、エラー、成功状態、無効状態）
• border-radius、影の値、フォントサイズが共有セットから再利用されているか、またはワンオフ値があるか
• 類似コンポーネントは似ているように見えて動作しているか。（例：すべてのカード、すべてのフォームフィールド、カテゴリ内のすべてのボタン）

美的忠実度

• 実装は仕様書からの名前付きの哲学と一致しているか
• これを見た人が想定される美的方向を即座に認識するか
• 美学を壊す要素があるか（一般的なコンポーネントが他とは違うインターフェース、矛盾するフォント、不適切な場所の色）
• 詳細のレベルは哲学と一致しているか。（ミニマリスト設計は不要な装飾を持つべきではありません。マキシマリスト設計は空の、未完成の領域を持つべきではありません。）

コンポーネント品質

• コードベースの既存コンポーネントが正しく表示されるか、または再実装されたか
• 新しいコンポーネントは既存コンポーネントと同じ API パターン（props、命名、ファイル組織）に従っているか
• 統合されるべき重複コンポーネントがあるか

状態とインタラクション

• インタラクティブ要素にはすべての必要な状態があるか：デフォルト、ホバー、フォーカス、アクティブ、無効
• フォームフィールドの状態があるか：空、入力済み、エラー、成功、無効
• ローディング状態は処理されるか。空の状態
• トランジションとアニメーションは哲学のモーション ガイドラインと一致しているか
• すべてのユーザーアクションに視覚的フィードバックがあるか

レスポンシブ動作

• レイアウトはモバイル（375px）、タブレット（768px）、デスクトップ（1280px+）で機能するか
• コンポーネントは適切に適応するか。（単に縮小するのではなく、必要に応じて再構成する。）
• タッチターゲット サイズはモバイルで十分か（最小 44x44px）
• テキストはすべてのブレークポイントで読める状態か。小さすぎるテキストなし、太すぎる行なし（最大 65-75文字）。

アクセシビリティ

• 色コントラスト：テキスト/背景の組み合わせは WCAG AA（本文テキストの 4.5:1、大きいテキストの 3:1）を満たしているか
• キーボード ナビゲーション：すべてのインタラクティブ要素にキーボードのみでアクセスして有効化できるか
• フォーカス インジケータ：フォーカス リングが表示されており、一貫してスタイル設定されているか
• セマンティック HTML：見出しは順序か。ランドマークは使用されているか（main、nav、header、footer）。フォーム ラベルは関連しているか
• スクリーン リーダー：画像に alt テキストがあるか。アイコンにラベルがあるか。装飾的な要素は支援技術から隠されているか
• モーション：reduced-motion メディア クエリがあるか

タイポグラフィ

• フォントが実際に読み込まれているか。（FOIT/FOUT フラッシュを確認します。）
• 行の長さは読みやすいか（本文テキストで 45-75 文字）
• 行の高さは適切か（本文の 1.4-1.6、見出しはより小さい）
• タイプ スケールは意図的か、またはランダムなサイズがあるか

ダークモード

• プロジェクトにダークモード トークンがある場合、正しく適用されているか
• すべてのカラー値が CSS 変数を使用しているか（切り替わらないハードコードされた 16 進値はないか）
• ダークパレットは選択した哲学に対して意図的に見えるか、単純な反転か
• 影はダークモード用に調整されているか（暗く、より透明か）
• アクセント色はダーク背景に対して十分なコントラストを保っているか
• 機能的なトグル メカニズムまたは prefers-color-scheme サポートはあるか

モバイルファースト

• レイアウトはモバイルファースト（max-width ではなく min-width メディアクエリを使用）で構築されたか
• モバイル レイアウトは 375px で水平スクロールなしで機能するか
• ナビゲーションはモバイル向けに適応されているか（オーバーフローするだけのデスクトップナビゲーションではない）
• タッチ ターゲットは最小 44x44px か
• モバイルで本文テキストは最小 16px か

出力形式

# Design Review: [Feature/Page Name]

Reviewed against: DESIGN_BRIEF.md
Philosophy: [named philosophy]
Date: [date]

## Screenshots Captured

| Screenshot                                   | Breakpoint         | Description     |
| -------------------------------------------- | ------------------ | --------------- |
| `screenshots/review-[page]-desktop-1280.png` | Desktop (1280×800) | [what it shows] |
| `screenshots/review-[page]-tablet-768.png`   | Tablet (768×1024)  | [what it shows] |
| `screenshots/review-[page]-mobile-375.png`   | Mobile (375×812)   | [what it shows] |

> All screenshots are in `.design/<feature-slug>/screenshots/`.

## Summary

[2-3 sentences on overall quality and the biggest finding.]

## Must Fix

1. **[Issue]**: [Specific description with file/component reference]. See [`screenshots/[relevant-screenshot].png`]. _Fix: [concrete suggestion]._

## Should Fix

1. **[Issue]**: [Description]. See [`screenshots/[relevant-screenshot].png`]. _Fix: [suggestion]._

## Could Improve

1. **[Issue]**: [Description]. _Suggestion: [idea]._

## What Works Well

[Note the strongest aspects of the implementation. This is not padding. Designers need to know what to keep doing.]