design-review

このスキルでは、構築したものをデザインブリーフおよび選択した美的方針と照らし合わせ、体系的なデザインレビューを行います。

重大 — ビジュアルスクリーンショットの撮影

すべてのデザインレビューで、実行中のアプリケーションのスクリーンショットを必ず撮影してください。コードレビューだけでは不十分です。ユーザーが目にするものを確認する必要があります。以下のステップ 3 にあるスクリーンショット撮影の手順に従ってください。これは必須です。

プロンプトの例

• 「たった今作ったものをレビューして」
• 「ランディングページのデザインを批評して」
• 「これをブリーフと照らし合わせて確認して」
• 「スクリーンショットはこちらです。見た目はどうですか？」［スクリーンショットを貼り付ける］
• 「リリース前に QA をして」

プロセス

1. ブリーフを読みます。 現在の機能のブリーフが .design/<feature-slug>/DESIGN_BRIEF.md にあるか確認します。.design/ の下に機能フォルダーが複数ある場合は、どの機能をレビューするかユーザーに尋ねます。.design/ フォルダーがない場合は、プロジェクトのルートにある DESIGN_BRIEF.md を確認します。どちらもない場合は、意図していたデザインの方向性をユーザーに尋ねます。

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

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

3. 実行中のアプリケーションのスクリーンショットを撮影します。

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

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

   以下の順に試し、利用可能な最初のものを使います。

   1. Playwright MCP（推奨）。 plugin-playwright-playwright MCP サーバーが利用可能か確認します。利用可能な場合は、それを使用します。ビューポートサイズ、ページ全体のキャプチャ、ファイル名を正確に制御できます。
   2. Cursor IDE Browser（次点）。 Playwright MCP が利用できない場合は、cursor-ide-browser MCP サーバーの browser_take_screenshot ツールを使用します。基本的な機能は同じです。
   3. ユーザーに依頼（最終手段）。 どちらの MCP サーバーもアプリ内ブラウザーも利用できない場合は、スクリーンショットを手動で提供するようユーザーに必ず依頼します。必要なものを具体的に伝えてください。
      • 「ブラウザーツールを利用できません。ビジュアルレビューを完了するには、実行中のアプリケーションのスクリーンショットが必要です。以下を提供してください。」
      • デスクトップ幅（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. アプリケーションに移動します。 プロジェクトから URL が明らかでない場合（例：http://localhost:3000）は、ユーザーに尋ねます。browser_navigate を使用して開きます。

   b. レスポンシブのブレークポイントを撮影します。 主要な各ページ／ビューについて、最低限、以下の 3 つのビューポートを撮影します。

   ブレークポイント	幅 × 高さ	ファイル名のサフィックス
   モバイル	375 × 812	-mobile-375
   タブレット	768 × 1024	-tablet-768
   デスクトップ	1280 × 800	-desktop-1280

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

   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/ フォルダが存在しない場合は、プロジェクトのルートに保存します。撮影したすべてのスクリーンショットとそのパスを一覧にした「Screenshots Captured」セクションを含めます。ユーザーが希望する場合は、レビューを直接提示します。

レビューチェックリスト

視覚的階層

• 各ページ/ビューで最も重要なコンテンツが最も視覚的に目立っていますか？
• タイプスケールは明確な重要度のレベル（見出し、小見出し、本文、キャプション）を生み出していますか？
• インタラクティブな要素（ボタン、リンク、入力欄）は、探し回らなくても見つけられる十分な視覚的重みを持っていますか？
• 明確な読み取り順序はありますか？ 目が最初に、次に、その次にどこへ向かうかをたどれますか？

一貫性

• スペーシングの値は一貫していますか？ パディングとマージンを確立されたスケール（4px/8px ベース、またはプロジェクトが使用しているもの）と照らし合わせて確認してください。
• 色は一貫して使用されていますか？ 同じ意味が常に同じ色にマッピングされているか確認してください（主要アクション、エラー、成功状態、無効状態）。
• ボーダー半径、シャドウの値、フォントサイズは共有セットから再利用されていますか、それとも一度きりの値がありますか？
• 類似したコンポーネントは類似した見た目と動作をしていますか？（例: すべてのカード、すべてのフォームフィールド、カテゴリ内のすべてのボタン。）

美的忠実度

• 実装はブリーフで指定されたデザイン哲学に合っていますか？
• 見た人が、意図された美的方向性をすぐに認識できますか？
• 美的方向性を損なう要素はありませんか？（独自性のあるインターフェースに汎用的なコンポーネントが混在している、フォントが競合している、色が場違いになっているなど）
• デザイン哲学に見合った細部の作り込みになっていますか？（ミニマリストデザインに不要な装飾がないか、マキシマリストデザインに空白だらけの未完成な箇所がないか）

コンポーネントの品質

• コードベースに既存のコンポーネントがある場合、それらは正しく使用されていますか、それとも再実装されていますか？
• 新しいコンポーネントは、既存のコンポーネントと同じ API パターン（props、命名、ファイル構成）に従っていますか？
• 統合すべき重複コンポーネントはありませんか？

状態とインタラクション

• インタラクティブな要素には、デフォルト、ホバー、フォーカス、アクティブ、無効のすべての必要な状態がありますか？
• フォームフィールドには、空、入力済み、エラー、成功、無効の状態がありますか？
• 読み込み中の状態は適切に処理されていますか？空の状態はありますか？
• トランジションやアニメーションは、デザイン哲学のモーションガイドラインに沿っていますか？
• すべてのユーザー操作に視覚的なフィードバックがありますか？

レスポンシブな動作

• モバイル（375px）、タブレット（768px）、デスクトップ（1280px 以上）でレイアウトは適切に機能しますか？
• コンポーネントは適切に対応していますか？（単に縮小するのではなく、必要に応じて再構成されていますか？）
• モバイルでタッチターゲットのサイズは十分ですか？（最小 44x44px）
• すべてのブレークポイントでテキストは読みやすく保たれていますか？小さすぎるテキストや、長すぎる行（最大 65～75 文字）はありませんか？

アクセシビリティ

• 色のコントラスト：テキストと背景の組み合わせは WCAG AA（本文テキストは 4.5:1、大きなテキストは 3:1）を満たしていますか？
• キーボード操作：すべてのインタラクティブな要素にキーボードだけで移動し、操作できますか？
• フォーカスインジケーター：フォーカスリングは見やすく、一貫したスタイルになっていますか？
• セマンティック HTML：見出しの順序は適切ですか？ランドマーク（main、nav、header、footer）は使われていますか？フォームラベルは関連付けられていますか？
• スクリーンリーダー：画像には alt テキストがありますか？アイコンにはラベルがありますか？装飾的な要素は支援技術から隠されていますか？
• モーション：配慮が必要なユーザー向けに、動きを減らすメディアクエリはありますか？

タイポグラフィ

• フォントは実際に読み込まれていますか？（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.]