UX Playbook は何をしますか？
ビジネスに正しく、使いやすく、一貫性のあるUIを構築します。Mantineがコンポーネントを提供し、このプレイブックがいつどれを使うか、画面に必要な状態、結果の確認方法を伝えます。タスクの必要に応じて該当ページだけを読んでください。
優先順位
情報源が矛盾する場合、優先順位が高い方が優先されます：
- ビジネス要件: 仕様、チケット、オーナーの指示。黙って変更しないでください。
- プロダクト独自のルール:
AGENTS.md/CLAUDE.md、そのUX・デザインドキュメント、既存コンポーネント。 - このプレイブック
- Mantineのドキュメントとデフォルト
2と3が矛盾する場合は2に従ってください。2または1が間違っていると思っても、それに従い、UX提案を提起してください。
UI作業の前に、プロダクトのUXルールを探してください（リポジトリのドキュメント内で「UX」「UI」「design」「panel」を検索）。存在しない場合は、プロダクト概要テンプレートを使って草案を作成し、計画またはPR内でその草案を提案してください。その際、推測にはすべて [Assumption] とラベルを付けてください。
階層を選ぶ
| 階層 | 変更内容 | すべきこと |
|---|---|---|
| S | 既存画面への小さな変更：フィールド、ボタン、メッセージ、列 | 触るコンポーネントのページを読み、チェックリストを実行。レイアウトが変わった場合はスクリーンショットを撮る。 |
| M | 新しい画面、ダイアログ、フォーム、または画面への大規模な変更 | 最初に簡潔なUX仕様書を書く。構築後、ビジュアルチェックを実施。ルーブリックでセルフレビュー。 |
| L | 画面をまたがる新しいフロー、新機能領域、ナビゲーションの変更 | 2～3の選択肢を提示するリサーチノートを作成。安全な選択肢Aを構築。その後、各画面を階層Mとして扱う。 |
各階層の詳細と成果物についてはワークフローを参照。
該当ページを見つける
| 判断したいこと | 読むページ |
|---|---|
| ページ構造、階層、スペーシング、レスポンシブレイアウト | decisions/layout |
| ボタン、プライマリ vs セカンダリ、アイコンボタン、アクションメニュー | decisions/actions |
| モーダル vs ドロワー vs ポップオーバー vs インライン、ツールチップ | decisions/overlays |
| アプリナビゲーション、タブ、パンくずリスト、ステッパー、ページネーション、リンク vs ボタン | decisions/navigation |
| テーブル、リスト、カード、ステータスラベル、日付、長いテキスト | decisions/data-display |
| トースト、アラート、バナー、インラインメッセージ | decisions/feedback |
| 選択に使う入力：チェックボックス、スイッチ、ラジオ、セグメントコントロール、セレクト、コンボボックス、チップ | decisions/selection |
| フォーム、ラベル、バリデーション、必須項目 | patterns/forms |
| 保存ボタン、オートセーブ、未保存の変更 | patterns/saving |
| まだ何も表示するものがない、検索結果なし | patterns/empty-states |
| データまたは処理の完了を待っている | patterns/loading |
| 詳細オプション、「さらに表示」、オンデマンド詳細 | patterns/progressive-disclosure |
| 機能の紹介、初回起動、ヒント | patterns/feature-onboarding |
| バックエンドダウン、オフライン、部分的な障害、権限不足 | patterns/degraded-experiences |
| 削除、リセット、失効、上書き | flows/destructive-actions |
| ラベル、ボタンテキスト、エラーテキスト、空状態テキスト | writing |
| キーボード、フォーカス、ラベル、コントラスト、ARIA | accessibility |
| Mantine API、テーマトークン、バージョンの確認 | mantine |
| ルールの背後にある理由 | principles |
常に守ること
- 独自のコンポーネントを作成する前に、プロダクトの既存コンポーネントとMantineを使用すること。1つの仕事に1つのコンポーネントを使う。
- すべてのデータビューにローディング、空、エラーの各状態を用意する。すべてのアクションに進行中状態と結果を用意する。
- ビューごとに1つのプライマリアクションを維持する。セカンダリアクションは控えめに。稀なアクションはメニューに配置する。
- 現在利用できないアクションは表示されたままにして理由を説明する。そのテキストはキーボードとタッチでアクセス可能とし、ツールチップだけに頼らない。
disabled属性よりも非アクティブな外観（data-disabled）を優先し、送信ボタンは決して無効にしない：actions参照。 - データを破壊する操作は確認を取るか、元に戻せるようにする。エラー時にユーザーの入力を失ってはならない。
- すべての入力に表示ラベルを付ける。意味を色だけで伝えてはならない。すべての要素がキーボードで操作可能であること。
- 電話幅とデスクトップ幅、ライトモードとダークモードで結果を確認する：ビジュアルチェック参照。
- ここの例はリテラルな英語の文字列を使用。プロダクトのi18n機構を使用すること。
改善の余地があると思ったとき
より良いフローやコンポーネントを提案してもよいし、すべきです。ルールは安全なデフォルトを構築し、提案を添付することです：
- 仕様で要求されたものを、ここにあるパターンを使って構築してください。
- あなたのアイデアを、UX提案として計画またはPR内に固定フォーマットで追加してください。
- 仕様がデータを失う、秘密を漏洩する、キーボードやスクリーンリーダーに依存するユーザーをブロックする、または自己矛盾している場合にのみ、構築を止めて確認を取ってください。
レポート
すべてのUIタスクは、PRまたはレポートに UX notes セクションを付けて終了します：
## UX notes
- 階層: M — 新規「Mods」タブ
- 状態: loading ✓ empty ✓ error ✓ disabled-with-reason ✓
- スクリーンショット: 1280 light/dark, 390 light/dark (添付)
- ルーブリック: すべて合格；該当なし: 破壊的操作（なし）
- 仮定: [Assumption] modsリストは短い（< 50）ため、ページネーションなし
- UX提案: 1件（以下参照）