k2works/developing-uiux-review

UI/UX 成果物レビュー

開発フェーズの UI/UX 成果物（画面設計、画面遷移図、ワイヤーフレーム、コンポーネント設計、フロントエンド実装など）を XP エージェントで並列レビューし、デザイン品質とユーザー価値の両面からフィードバックを統合する。

レビューの価値

UI/UX のレビューは見た目の良し悪しを判断する活動ではない。システムメタファーとの整合性、ユーザーの心理モデルへの適合、業務フローとの自然さ、アクセシビリティを同時に検証することで、「ユーザーの問題を本当に解決する」インターフェースを実現する。デザイナーの視点とユーザーの視点を同時に当てることで、設計者のバイアスを早期に発見できる。

加えて、Material Design 3 をはじめとするモダンデザインシステムの原則に照らし合わせることで、業界標準のユーザー体験を担保する。ユーザーは日常的にモダンなアプリケーションに触れており、その操作感覚からの逸脱は学習コストと離脱率の上昇に直結する。

モダンデザイン評価基準

レビュー時に以下のモダンデザイン原則への準拠を評価する。プロジェクトが採用するデザインシステムに応じて適用する。

Material Design 3（M3）

• Dynamic Color: カラーシステムが一貫しているか、セマンティックカラー（primary / secondary / tertiary / error）の使い分けが適切か
• Typography: Type Scale（Display / Headline / Title / Body / Label）の使い分けが情報階層を正しく表現しているか
• Elevation & Surface: 要素間の階層関係が Elevation（影 / overlay）で明確に表現されているか
• Shape: 角丸やコンテナの形状がコンポーネントの役割を反映しているか（FAB: Full / Card: Medium / Chip: Small）
• Motion: アニメーションとトランジションが意味を持ち、ユーザーの注意を適切に誘導しているか
• Adaptive Layout: 画面サイズに応じた適応的レイアウト（Compact / Medium / Expanded）が実装されているか

共通のモダンデザイン原則

• デザイントークン: 色・サイズ・間隔がトークンとして体系化されているか（マジックナンバーの排除）
• コンポーネント一貫性: 同じ役割のコンポーネントが同じ見た目・振る舞いをしているか
• 空白とリズム: 8px グリッドシステム等のスペーシングルールに従っているか
• ダークモード対応: ライト / ダーク両テーマで可読性とコントラストが確保されているか
• マイクロインタラクション: ホバー、フォーカス、プレスなどの状態変化が明確にフィードバックされているか
• レスポンシブデザイン: ブレークポイントでのレイアウト切り替えが自然で情報の優先順位が保たれているか
• 空状態・ローディング・エラー状態: 各状態が設計されており、ユーザーが次に何をすべきか分かるか

レビューエージェント

| エージェント | 視点 | 着眼点 | |:---|:---|:---| | xp-interaction-designer | デザイン品質 | システムメタファーとの整合、情報設計、画面遷移の論理性、レイアウト・視覚的階層、アクセシビリティ（WCAG 2.1 AA）、レスポンシブ対応、インタラクションパターンの一貫性、モダンデザインシステムへの準拠（Material Design 3 / デザイントークン / Adaptive Layout / Motion） | | xp-user-representative | 業務適合性 | 実際の業務フローとの自然さ、操作の直感性、学習コスト、エラー時のリカバリ、業務効率、例外ケースへの対応、ユーザーが本当に求めている体験、モダンなアプリとの操作感の一貫性（他アプリで慣れた操作パターンとの整合） |

レビュー対象の判定

ユーザーのリクエストに応じてレビュー範囲を決定する。

| リクエスト | レビュー範囲 | |:---|:---| | 「画面設計をレビュー」 | UI 設計ドキュメント（PlantUML salt 図、画面遷移図） | | 「コンポーネントをレビュー」 | フロントエンドコンポーネントの実装 | | 「画面遷移をレビュー」 | 画面遷移図と遷移ロジック | | 「UX をレビュー」 | ユーザーフロー全体（設計 + 実装） | | 「アクセシビリティをチェック」 | WCAG 2.1 AA 準拠の観点で全体評価 | | 「ワイヤーフレームをレビュー」 | ワイヤーフレーム / モックアップ |

レビューワークフロー

1. レビュー対象の収集

レビュー対象の UI/UX 成果物を特定し、内容を把握する。

• 画面設計の場合: 関連する PlantUML ファイル、salt 図、画面遷移図を収集
• フロントエンド実装の場合: コンポーネントファイルとスタイルシートを収集
• 関連するユーザーストーリー、ドメインモデル、業務フローも収集する

2. エージェントの並列起動

Agent ツールを使い、2 つのエージェントを 同一メッセージで並列起動 する。各エージェントには以下を指示する。

あなたは {エージェント名} です。
.claude/agents/{エージェント名}.md の定義に従ってレビューしてください。

## レビュー対象
{画面設計 / コンポーネント / 画面遷移図}

## 関連コンテキスト
{ユーザーストーリー、業務フロー、ドメインモデル、システムメタファー}

## レビュー観点
{エージェント固有の着眼点}

## モダンデザイン評価基準
このスキルの「モダンデザイン評価基準」セクションに基づき、
Material Design 3 および共通のモダンデザイン原則への準拠も評価してください。

## 出力形式
以下の形式でフィードバックを返してください：

### 評価サマリー
（1-2 文で全体評価）

### 良い点
- （具体的に）

### モダンデザイン準拠状況
- （Material Design 3 / デザイントークン / レスポンシブ等の準拠状況）

### 改善提案
- 【重要度: 高/中/低】（対象箇所）（具体的な改善提案と理由）

### 懸念事項
- （ユーザビリティリスク、アクセシビリティ問題、業務フローとの不整合、デザインシステムとの乖離など）

### スコープ外の発見
- （レビュー対象外だが報告すべき問題）

Agent ツールが利用できない場合のフォールバック

Agent ツールが利用できない環境では、2 つの視点を逐次的にシミュレートする。各エージェントの定義ファイル（.claude/agents/{エージェント名}.md）を読み、その視点でレビューを順次実施する。出力形式は同一のテンプレートに従う。

3. フィードバックの統合

全エージェントのフィードバックを受け取った後、以下の形式で統合レポートを作成する。

## UI/UX レビュー結果

### レビュー対象
- {画面名 / コンポーネント名 / 画面遷移}

### 総合評価
（全エージェントの評価を統合した 2-3 文の評価）

### モダンデザイン準拠サマリー
| 評価項目 | 状態 | 備考 |
|---|---|---|
| カラーシステム | OK / 要改善 | |
| タイポグラフィ | OK / 要改善 | |
| Elevation & Surface | OK / 要改善 | |
| コンポーネント一貫性 | OK / 要改善 | |
| スペーシング | OK / 要改善 | |
| レスポンシブ / Adaptive | OK / 要改善 | |
| ダークモード | OK / 要改善 / 未対応 | |
| 状態デザイン（空 / Loading / Error） | OK / 要改善 | |

### 改善提案（重要度順）

#### 高（リリース前に対応すべき）
| # | 提案 | 箇所 | 指摘元 | 理由 |
|---|------|------|--------|------|

#### 中（対応推奨）
| # | 提案 | 箇所 | 指摘元 | 理由 |
|---|------|------|--------|------|

#### 低（改善の余地あり）
| # | 提案 | 箇所 | 指摘元 | 理由 |
|---|------|------|--------|------|

### 矛盾事項

デザイナー視点とユーザー視点が相反する場合、ここに記載する。

| # | 視点 A | 視点 B | 論点 | 推奨判断 |
|---|--------|--------|------|----------|

### エージェント別フィードバック詳細

<details>
<summary>xp-interaction-designer（高: N / 中: N / 低: N）</summary>
（フィードバック全文）
</details>

<details>
<summary>xp-user-representative（高: N / 中: N / 低: N）</summary>
（フィードバック全文）
</details>

4. 改善アクションの提案

重要度「高」の指摘については具体的な改善案を提案する。

• デザイン改善: 修正後の PlantUML salt 図や画面遷移図を提示
• 実装改善: 修正後のコンポーネントコードを提示
• 改善を適用するかはユーザーの判断に委ねる

5. レビュー結果の保存

統合レポートを docs/review/{対象名}_uiux_review_{YYYYMMDD}.md に保存する。過去のレビュー結果と比較できるようにし、改善のトレーサビリティを確保する。

レビュー完了条件

以下をすべて満たした場合にレビュー完了とする。

• 全エージェントのフィードバックが収集済み
• 統合レポートが作成済み
• 重要度「高」の指摘について対応方針（修正する / 許容する / 保留する）が決定済み
• レビュー結果がドキュメントとして保存済み

注意事項

• UI/UX レビューは「ユーザーの問題を本当に解決する」インターフェースを実現するための協調的な活動
• アクセシビリティに関する指摘は重要度「高」として扱う
• デザイナー視点（理想）とユーザー視点（現実）の間にある緊張関係を活かし、より良い解を導く

関連スキル

• analyzing-ui-design -- UI 設計（画面遷移図・salt 図の作成）
• developing-frontend -- フロントエンド TDD 開発
• developing-review -- 開発成果物の総合レビュー（コード品質中心）
• analyzing-review -- 分析成果物のレビュー