ux-review

!bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" resolve_config --keys workflow

上記で解決済みです。そのまま使用してください。ブロックがない場合は、 .claude/docs/config-resolution.md のデフォルト値を使用します。

UX レビュー

概要

UX デザイン文書が実装パイプラインに入る前に検証します。 /team-ui パイプラインにおいて、UX デザインとビジュアルデザイン／実装の間の 品質ゲートとして機能します。

このスキルを実行するタイミング：

• /ux-design で UX 仕様を完成させた後
• ui-programmer または art-director に引き渡す前
• プリプロダクションからプロダクションへのゲートチェックの前（主要画面の UX 仕様がレビュー済みであることが必須です）
• UX 仕様の大幅な改訂後

判定レベル：

• APPROVED — 仕様が完全で、一貫性があり、実装可能な状態です
• NOT ASSESSED — 1 つ以上のレビュー観点に照合基準がない、または仕様を 読み取れませんでした。該当するものを明記してください
• NEEDS REVISION — 具体的な不足点が見つかりました。引き渡し前に修正が 必要ですが、全面的な再設計は不要です
• MAJOR REVISION NEEDED — スコープ、プレイヤーのニーズ、または完全性に 根本的な問題があり、大幅なやり直しが必要です

NOT ASSESSED は APPROVED より上位で、2 つの改訂判定より下位です。 ある観点を評価できなかったレビューでは、その仕様が実装可能な状態であることを 確認できていません。一方、誰も確認できなかった不足点より、誰かが見つけた不足点の ほうが対応しやすいため、後者の判定を押しのけてはいけません。仕様ファイルを 読み取れない場合、チェックリストの観点を照合するための信頼できる情報源がない場合、 またはアクセシビリティティアが未確定の場合（下記）に出力してください。

---

フェーズ 1：引数を解析する

• 特定のファイルパス（例：/ux-review design/ux/inventory.md）：その文書を 検証します
• all：design/ux/ 内のすべてのファイルを見つけて検証します
• hud：design/ux/hud.md を指定して検証します
• patterns：design/ux/interaction-patterns.md を指定して検証します
• 引数なし：どの仕様を検証するかユーザーに尋ねます

all の場合、まず概要テーブル（ファイル | 判定 | 主な問題）を出力し、その後、 各ファイルの詳細を出力します。

各ファイルに適用するチェックリスト（ファイルパスで指定された場合、または all の各ファイル）：/ux-design が記述する > **Template**: ヘッダー行を 確認します。UX Spec → フェーズ 3A、HUD Design → 3B、 Interaction Pattern Library → 3C です。この行がないファイルは、ファイル名で 分類します。hud.md → 3B、interaction-patterns.md → 3C、それ以外 → 3A です。 レポートには、どのチェックリストを想定したかとその理由を記載します。

---

フェーズ 2：相互参照用のコンテキストを読み込む

仕様を検証する前に、以下を読み込みます。

1. 入力とプラットフォームの設定：project.yaml の platform ブロック （platform.targets、platform.primary_input、platform.gamepad_support、 platform.touch_support）を読み込みます。project.yaml に platform ブロックが ない場合は、.claude/docs/technical-preferences.md の ## Input & Platform セクションを参照します。対応する入力方式の一覧は、 project.yaml を読む場合、そこから導出します。targets に PC または Web が 含まれていればキーボード／マウス、gamepad_support が Full または Partial であればゲームパッド、touch_support が Full または Partial であればタッチを 含め、さらに primary_input も含めます。technical-preferences.md を参照する 場合は、そこに明記された Input Methods フィールドを使用します。これは フェーズ 3A の入力方式カバレッジチェックにおける信頼できる情報源です。 仕様自体のヘッダーは参照しません。どちらの情報源にも設定がない場合は、 仕様のヘッダーを参照します。
2. design/accessibility-requirements.md が存在する場合は、そこで確定している アクセシビリティティア
3. design/ux/interaction-patterns.md が存在する場合は、インタラクションパターン ライブラリ
4. 仕様のヘッダーで参照されている GDD（UI Requirements セクションを読みます： Grep ツールで見出しを検索し（パターン ^#、content モード）、offset と limit を 指定して該当範囲を読み込みます）
5. コンテキスト到着時の検証用に、design/player-journey.md が存在する場合は プレイヤージャーニーマップ

---

フェーズ 3A：UX 仕様の検証チェックリスト

ux-spec.md ベースの文書を対象にすべてのチェックを実施します。

完全性（必須セクション）

• Status、Author、Platform Targetを含むドキュメントヘッダーがある
• 目的とプレイヤーのニーズ — プレイヤー視点のニーズを記述している（開発者視点ではない）
• 到着時のプレイヤーの状況 — プレイヤーの状態と、それまでの行動を記述している
• ナビゲーション上の位置 — 画面が階層のどこに位置するかを示している
• 入場ポイントと退出ポイント — すべての入場元と退出先を記載している
• レイアウト仕様 — ゾーンを定義し、コンポーネント一覧表を含んでいる
• 状態とバリエーション — 少なくとも読み込み中、空／データあり、エラーの各状態を記載している
• インタラクションマップ — 対象となるすべての入力方法を網羅している（ヘッダーのPlatform Targetを確認）
• データ要件 — 表示されるすべてのデータ要素について、ソースシステムと所有者を記載している
• 発火するイベント — すべてのプレイヤーアクションに対応するイベント、またはイベントがない場合の説明がある
• トランジションとアニメーション — 少なくとも入場／退出時のトランジションを指定している
• 入力方法の網羅性チェックリスト — Platform Targetの行に記載された各入力方法のブロックがある。チェックされていない項目は「未解決の質問」に記載している
• アクセシビリティ要件 — 画面レベルの要件がある
• ローカライズに関する考慮事項 — テキスト要素の最大文字数がある
• 受け入れ条件 — 具体的でテスト可能な条件が少なくとも5つある

品質チェック

プレイヤーのニーズの明確さ

• 目的をプレイヤー視点で記述している。システム／開発者視点ではない
• 到着時のプレイヤーの目標が明確である（「プレイヤーは___したいと思って到着する」）
• 到着時のプレイヤーの状況が具体的である（単に「インベントリを開いた」ではない）

状態の完全性

• エラー状態を記載している（正常系だけではない）
• 空の状態を記載している（データがない場合）
• 画面が非同期データを取得する場合、読み込み中の状態を記載している
• タイマーまたは自動的に閉じる動作を伴う状態について、継続時間を記載している

入力方法の網羅性

• プラットフォームにPCが含まれる場合：キーボードのみでのナビゲーションを完全に指定している
• プラットフォームにコンソール／ゲームパッドが含まれる場合：十字キーのナビゲーションと各ボタンの割り当てを記載している
• ゲームパッドでマウスのような精密操作を必要とするインタラクションがない
• フォーカス順序を定義している（キーボードではTab順、ゲームパッドでは十字キーの順序）

データアーキテクチャ

• 所有者に「UI」と記載されたデータ要素がない（UIがゲーム状態を所有してはならない）
• すべてのリアルタイムデータについて更新頻度を指定している（単に「リアルタイム」ではなく、更新のトリガーを記載）
• すべてのデータ要素について、データが利用できない場合の表示など、nullの扱いを指定している

アクセシビリティ

• accessibility-requirements.mdのアクセシビリティティアを満たしているか、それを上回っている
• Basicティアの場合：色だけで情報を伝えるインジケーターがない
• Standardティア以上の場合：フォーカス順序を記載し、テキストのコントラスト比を指定している
• Comprehensiveティア以上の場合：重要な状態変化をスクリーンリーダーで通知する
• 色覚チェック：色分けされた要素に、色以外の代替手段がある

GDDとの整合性

• ヘッダーで参照しているGDD UI要件をすべて仕様内で扱っている
• 対応するGDD要件なしに、ゲーム状態を表示または変更するUI要素がない
• この仕様に記載漏れのGDD UI要件がない（参照先のGDDセクションと照合する）

パターンライブラリとの一貫性

• すべてのインタラクティブコンポーネントがパターンライブラリを参照している（または新しいパターンであると明記している）
• パターンライブラリにすでに存在する動作を一から再定義していない
• この仕様で考案した新しいパターンに、パターンライブラリへの追加が必要であることを明記している

ローカライズ

• テキスト量の多いすべての要素に文字数制限の警告がある
• レイアウト上重要なテキストに、40％の拡張に対応する必要があると明記している

受け入れ条件の品質

• 設計ドキュメントを見たことがないQAテスターにも理解できるほど具体的である
• パフォーマンス条件がある（画面がXms以内に開く）
• 解像度に関する条件がある
• 評価するために別のドキュメントを読む必要がある条件がない

フェーズ 3B：HUD 検証チェックリスト

hud-design.md に基づくドキュメントに対して、すべてのチェックを実行します。

完全性

• HUD の理念が定義されている
• 情報アーキテクチャの表に、GDD で UI 要件が定められているすべてのシステムが含まれている
• すべての対象プラットフォームについて、安全領域のマージンを含むレイアウトゾーンが定義されている
• すべての HUD 要素に完全な仕様（ゾーン、表示トリガー、データソース、優先度）がある
• ゲームプレイ状況別の HUD 状態に、最低限、探索、戦闘、会話／カットシーン、一時停止が含まれている
• 情報階層ですべての HUD 要素に優先度（必ず表示／表示を推奨／非表示可／常に非表示）が割り当てられている
• 視覚的な予算（同時に表示する要素の最大数、画面に占める割合の上限）が定義されている
• プラットフォームへの適応で、すべての対象プラットフォームが網羅されている
• プレイヤーが調整可能な要素の調整項目が用意されている
• 受け入れ基準に、具体的でテスト可能な基準が少なくとも5つある

品質チェック

• 表示ルールで非表示にできるようになっていない HUD 要素が、プレイ画面の中央領域に重なっていない
• いずれかの GDD に存在するすべての情報項目が、HUD に含まれているか、「非表示／要求時に表示」として明示的に分類されている
• 色で情報を区別するすべての HUD 要素に、色覚多様性に配慮したバリエーションがある
• フィードバックと通知のセクションにある HUD 要素について、キュー／優先度の動作が定義されている
• 視覚的な予算への適合：同時に表示される要素の合計数が予算内に収まっている

GDD との整合性

• design/gdd/systems-index.md で UI カテゴリに分類されているすべてのシステムが、HUD に反映されている（または、反映されていない理由が示されている）

---

フェーズ 3C：パターンライブラリ検証チェックリスト

• パターンカタログのインデックスが最新である（ドキュメント内の実際のパターンと一致している）
• 標準的な操作パターンがすべて指定されている：ボタンのバリエーション、トグル、スライダー、ドロップダウン、リスト、グリッド、モーダル、ダイアログ、トースト、ツールチップ、プログレスバー、入力フィールド、タブバー、スクロール
• 現在の UX 仕様で必要なゲーム固有のパターンがすべて用意されている
• 各パターンに、「使用する状況」、「使用しない状況」、完全な状態仕様、アクセシビリティ仕様、実装メモがある
• アニメーション基準の表がある
• サウンド基準の表がある
• パターン間で動作に矛盾がない（例：「戻る」の動作がすべてのナビゲーションパターンで一貫している）

---

フェーズ 4：判定を出力する

## UX Review: [Document Name]
**Date**: [date]
**Reviewer**: ux-review skill
**Document**: [file path]
**Checklist**: [3A / 3B / 3C — from its Template line, or assumed from the file name]
**Platform Target**: [from header]
**Accessibility Tier**: [from header or accessibility-requirements.md]

### Completeness: [X/Y sections present]
- [x] Purpose & Player Need
- [ ] States & Variants — MISSING: error state not documented

### Quality Issues: [N found]
1. **[Issue title]** [BLOCKING / ADVISORY]
   - What's wrong: [specific description]
   - Where: [section name]
   - Fix: [specific action to take]

### GDD Alignment: [ALIGNED / GAPS FOUND]
- GDD [name] UI Requirements — [X/Y requirements covered]
- Missing: [list any uncovered GDD requirements]

### Accessibility: [COMPLIANT / GAPS / NON-COMPLIANT / NOT ASSESSED]
- Target tier: [tier]
- [list specific accessibility findings]

> **If `design/accessibility-requirements.md` is absent there is no committed
> tier, so this dimension has no criterion.** Report
> `Accessibility: NOT ASSESSED — no committed tier (design/accessibility-requirements.md absent)`
> and do NOT report it as COMPLIANT — a gate compared against an absent standard
> passes the way an assertion that can never fail passes. The same rule lives in
> `/team-ui` Phase 4 and is mirrored here so the two cannot drift. If the spec's own
> header states a tier, carry it forward as an **assumption** and say plainly that
> it was assumed rather than committed. Recommend `/ux-design accessibility` to
> establish the tier.

### Pattern Library: [CONSISTENT / INCONSISTENCIES FOUND / N/A]
- [findings]

> **For a HUD design there is no Pattern Library checklist to run it against (Phase 3B has none), so Pattern Library is N/A, excluded from the dimension count.**
> Report `Pattern Library: N/A — no pattern library checklist for this document
> type`.
>
> For a UX spec, this dimension does have a checklist — it is checked against
> `design/ux/interaction-patterns.md`. If that file is absent: N/A only where
> the workflow tier does not require the library (`minimal`) — report
> `Pattern Library: N/A — interaction pattern library not required at this
> tier`. At any tier that requires or recommends it (`standard`, `full`), report
> `Pattern Library: NOT ASSESSED — design/ux/interaction-patterns.md not found`
> instead: the library is missing, not out of scope, and NOT ASSESSED counts it
> against the verdict as the unresolved item it is.

### Verdict: APPROVED / NOT ASSESSED / NEEDS REVISION / MAJOR REVISION NEEDED
**Blocking issues**: [N] — must be resolved before implementation
**Advisory issues**: [N] — recommended but not blocking
**Dimensions not assessed**: [N] — [name each, and what would make it checkable]

[For APPROVED]: This spec is ready for handoff to `/team-ui` Phase 2
(Visual Design).

[For NOT ASSESSED]: [N] of the four review dimensions could not be evaluated:
[name them]. The spec may well be sound — this review cannot say either way for
those dimensions. [For each: the one input that would make it checkable.]
Handoff to `/team-ui` is not recommended on this result.

[For NEEDS REVISION]: Address the [N] blocking issues above, then re-run
`/ux-review`.

[For MAJOR REVISION NEEDED]: The spec has fundamental gaps in [areas].
Recommend returning to `/ux-design` to rework [sections].

---

フェーズ 5：協調プロトコル

このスキルは読み取り専用です。ファイルの編集や書き込みは行いません。検出結果のみを報告します。

判定を伝えた後：

• 承認の場合：実装の調整を始めるために /team-ui の実行を提案します
• 未評価の場合：次元ごとに不足している入力を挙げ、それを用意する支援を申し出ます（未確定の層には /ux-design accessibility、UI 要件が不足している場合は GDD のパス）。同じ不足入力に対するレビューを再実行して、異なる判定を報告してはいけません。この判定が変わるのは、新しい入力がある場合のみです
• 修正が必要の場合：具体的な不足箇所の修正を支援することを申し出ます（「不足しているエラー状態の草案作成をお手伝いしましょうか？」など）。ただし、自動修正はせず、ユーザーの指示を待ちます
• 大幅な修正が必要の場合：修正が必要な具体的なセクションを示して、/ux-design に戻ることを提案します

ユーザーが先へ進むのを妨げてはいけません。判定はあくまで助言です。リスクを記録し、検出結果を提示したうえで、懸念があっても続行するかどうかはユーザーに委ねます。「修正が必要」という判定の仕様で進むことを選んだユーザーは、記録されたリスクを引き受けることになります。