interaction-patterns-components

インタラクションパターンのコンポーネント

目的

効果的な UI インタラクションパターンと再利用可能なプロダクトコンポーネントを選び、評価し、設計できるようエージェントを支援します。

このスキルでは、ナビゲーションパターン、メニュー、カード、テーブル、ダッシュボード、モーダル、フロー、状態、コンポーネントの振る舞いを扱います。ビジュアルの洗練は、インタラクションの明確さ、階層、アクセシビリティ、コンポーネントの使いやすさに影響する場合にのみ扱います。

このスキルを使う場面

ユーザーから次のような依頼があった場合に、このスキルを使います。

• アプリ画面、ウェブサイト、プロダクトのフロー、ワイヤーフレーム、コンポーネント、フロントエンド実装の評価、再設計、UX レビュー。
• ナビゲーション、メニュー、パンくずリスト、ダッシュボード、カード、テーブル、フォーム、モーダル、ウィザード、分割ペイン、タブ、アコーディオン、ツールバー、ホバーツール、リスト、グリッド、フィードバック状態などの UI パターンの選定。
• 再利用可能なコンポーネントやデザインシステムの振る舞いの設計。
• インタラクションの振る舞い、アクセシビリティ、レスポンシブな振る舞い、コンポーネント API、UI の状態管理に関するフロントエンドのガイダンス。
• タスク、ユーザーのスキル、デバイスの状況、データの複雑さ、リスクによって最適な答えが変わる場合の、プロダクト UX に関する提案の作成。

このスキルを使わない場面

ユーザーが主に次のことを必要としている場合は、このスキルを主要なフレームワークとして使わないでください。

• インタラクションの明確さと結び付かないブランドアイデンティティ、イラスト、ムードボード、ビジュアルの洗練。
• ラベル、ヘルプテキスト、エラー、マイクロコピーを超える、詳細なコピーライティング、メッセージ戦略、コンテンツ設計。
• 純粋なグラフィックデザイン、ロゴデザイン、マーケティングクリエイティブ。
• ネイティブ音声、AR／VR、空間、または画面を使わないインタラクションデザイン。ただし、画面上のコントロールや連携 UI も含むタスクは除きます。
• コンポーネントの振る舞いに影響する実装上の制約を除く、バックエンドアーキテクチャ、データベース設計、API 設計。

基本原則

1. 人、目標、状況から始める

コンポーネントを選ぶ前に、ユーザーが何を達成しようとしているのかを特定します。フォーム、メニュー、テーブル、モーダル、ダッシュボードは、いずれもユーザーの目標を達成するための手段にすぎません。最もシンプルで役立つインターフェースを設計できるほど、作業内容、リスク、成功基準が明確になるまで「なぜ」を問い続けます。

デフォルト：機能からユーザーの目標を推測して進めます。エキスパートと初心者、モバイルとデスクトップ、高リスクと低リスクのアクションなど、不足している状況によってパターンの選択が変わる場合に限り、質問します。

2. インタラクションを対話として捉える

すべての UI は、思いやりのあるパートナーのように応答する必要があります。入力を受け止め、応答し、進行状況を示し、混乱を防ぎ、次のステップを明確にします。可視状態、フィードバック、ラベル、フォーカスの挙動、復帰手段を通して、これをコンポーネントに反映します。

デフォルト：インタラクティブなコンポーネントには、少なくともデフォルト、該当する場合はホバー／押下、フォーカス、読み込み中、無効、成功、空、エラーの各状態を定義する必要があります。

3. 状況を保てる最もシンプルなパターンを選ぶ

ユーザーが現在の位置を把握でき、不必要なナビゲーションを減らせるパターンを優先します。ツールは対象の近くに配置しますが、重要なアクションをホバー時のみ使える機能や、曖昧なアイコンの背後に隠さないでください。

デフォルト：コンテキストの切り替えを減らし、かつ見つけやすさを保てる場合は、画面内での編集、コンテキストに応じたツール、インライン検証、同一ページ内のプレビューを使います。

4. 位置を把握できる手がかりを保つ

ユーザーは、自分がどこにいるのか、どこへ進めるのか、何が変わったのか、どう復旧できるのかを把握する必要があります。ナビゲーションは単なる UI の装飾ではありません。道しるべ、階層、パンくずリスト、進行状況インジケーター、ディープリンク、抜け道、安定した画面領域も含まれます。

デフォルト：安定した主要ナビゲーションモデル、明確なページタイトル、現在地の表示、直前または親のコンテキストに戻れる可逆的な経路を用意します。

5. 情報構造をレイアウトに反映する

レイアウトは装飾ではなく、タスクの構造を反映する必要があります。グループ化、近接性、整列、視覚的階層、段階的な情報開示、画面領域を使い、関係性と優先順位を示します。

デフォルト：タスク領域ごとに明確な主アクションを 1 つ設け、関連するコントロールをまとめ、最も重要なコンテンツまたは対象を中心的に目立たせます。

6. パターンをデータとタスクに合わせる

テーブル、カードグリッド、リスト、ダッシュボード、フィード、ウィザード、詳細ページが適切なのは、ユーザーが比較、一覧、選択、作成、監視、編集する対象に合っている場合に限ります。

基本方針：構造化され、比較や並べ替えが可能なデータには、テーブルまたは情報密度の高いリストを使用します。種類が異なり、見た目で識別しやすい項目には、カードまたはサムネイルを使用します。手順を踏む、慣れていないタスクにはウィザードを使用します。熟練者が繰り返し行う作業には、ショートカットと表示可能なツールを備えた、より情報密度の高いワークスペースを使用します。

7. 安全に操作できるようにする

プレビュー、取り消し、キャンセル、明確なラベル、重大な操作に限った確認、確実な復旧手段を用意して、安全に試せるようにします。日常的で取り消し可能な操作を、確認で妨げないでください。

基本方針：取り消し可能な操作では、確認よりも取り消しを優先します。破壊的、高コスト、不可逆、プライバシーに関わる、金銭に関わる、または広範囲に波及する操作に限り、確認または一時保留の手順を設けます。

8. 中断、再開、反復を想定して設計する

ユーザーは方向を変え、作業を中断して再開し、操作を繰り返し、記憶に頼ります。状態を安定させ、コントロールの予期しない配置換えを避け、安全な進捗を記憶し、役立つ場合は最近使った操作や繰り返し使う操作を前面に表示します。

基本方針：可能な限り未保存の作業を保持し、詳細画面から戻った後もフィルターとスクロール位置を維持し、ユーザーがタスクを始めた後にコントロールを移動しないでください。

9. フォームは短く、目的を明確にし、柔軟に対応できるものにする

今必要な情報だけを尋ねます。ラベル、ヒント、適切な入力タイプ、スマートなデフォルト値、検証、入力例、エラーからの復旧手段を用意します。プレースホルダーテキストだけをラベルや説明として使わないでください。

基本方針：ラベルを常に表示し、ほとんどのフォームは1列の構成にし、フィールドに紐づくインラインエラーを表示します。可能な限り柔軟な入力形式を採用し、確度が高く、ユーザーが編集できる場合にのみスマートな事前入力を行います。

10. パターンを再利用可能なシステムとして構築する

状況に応じて必要な場合を除き、その場限りのコンポーネントを作らないでください。コンポーネントの役割、バリエーション、状態、アクセシビリティの動作、レスポンシブ時の動作、コンテンツのルール、代替手段を定義します。

基本方針：既存のデザインシステムまたは一般的な UI フレームワークを出発点とし、意図を持って拡張します。ライブラリは最低限の基盤として扱い、その限界と見なさないでください。

各原則を再利用可能なカードとしてまとめたものについては、references/principle-cards.md を参照してください。

デフォルトの推奨事項

ユーザーの状況から別の選択が妥当と判断できる場合を除き、以下をデフォルトとして使用します。

領域	デフォルトの推奨事項	通常これが最適な理由	別の選択が妥当な場合
プロダクトの目標	機能を見せることではなく、ユーザーのタスク完了を最優先します。	ユーザーにとって、UI は目的を達成するための手段です。	画面が主に探索、学習、またはプロモーションを目的としている場合。
対象ユーザー	幅広い専門知識を持つ、能力は高いものの時間に余裕がないユーザーを想定して設計します。	ほとんどのプロダクトでは、初心者とリピーターの両方が同時に利用します。	プロダクトが明確に専門家専用、キオスク型、または一度きりの利用を想定している場合。
プラットフォーム	まずレスポンシブ対応とモバイルへの配慮を行い、その後、大画面向けに拡張します。	小さな画面では優先順位付けと再利用可能なコンテンツ単位が必要になります。	ツールがデスクトップ専用の高密度なプロフェッショナル向けワークスペースである場合。
ナビゲーション	安定したグローバルナビゲーションと、各画面内の案内を組み合わせます。	予測しやすさにより、認知負荷が軽減されます。	プロダクトが単一タスクのフロー、または没入型のキャンバスである場合。
情報密度	適度な密度にし、段階的に情報を開示します。	圧倒されることなく、情報をざっと確認できます。	専門家向けのワークフローで、高密度なデータとキーボード操作の効率性が必要な場合。
画面構成	概要、集中、作成、実行のいずれかを、画面の主な種類として選びます。	明確な構成原則により、画面を理解しやすくなります。	ダッシュボードやワークベンチに、複数の領域が本当に必要な場合。
リスト	比較にはリストやテーブルを、情報量の多い項目や視覚的な項目にはカードを使います。	パターンは、ユーザーが情報を確認する目的に合わせて選びます。	項目の内容や選択時の動作が一般的でない場合。
主なアクション	タスクの各領域で、視覚的に最も目立つ主なアクションを1つにします。	注意が分散するのを防ぎ、次のステップを明確にできます。	複数のアクションが実際に同等で、頻繁に使われる場合。
モーダル	複雑なワークフローにはモーダルを避け、対象が明確で、割り込みが必要な限定的なタスクに使います。	モーダルは作業の文脈を中断し、ナビゲーションやフォーカスを複雑にします。	ページ遷移よりも、軽量なオーバーレイのほうが作業の文脈を保てる場合。
ウィザード	不慣れで、順序が決まった複数ステップのタスクに限って使います。	順番に進むセットアップの認知負荷を軽減できます。	専門家ユーザーが、順序に縛られない編集や比較を必要としている場合。
ダッシュボード	装飾的な指標ではなく、対応につながるモニタリング情報を表示します。	ダッシュボードは、意思決定と優先順位付けを支援する必要があります。	ダッシュボードが、周囲の状況を継続的に把握することを明確な目的としている場合。
フォーム	入力項目を最小限にし、すべてにラベルを付け、セクションをグループ化し、インラインで検証します。	入力の負担を軽減し、エラーを防げます。	法律、コンプライアンス、または運用上の要件により、追加の入力項目が必要な場合。
デフォルト値	正しい可能性が高く、簡単に変更できる場合に限り、値を事前入力します。	適切なデフォルト値は、ユーザーの制御を奪わずに手間を減らします。	誤ったデフォルト値によって、大きな損失や誤解が生じる場合。
エラー処理	まずエラーを防ぎ、その後、原因を説明して復旧できるようにします。	エラーからの復旧も、インタラクションの一部です。	リアルタイムでエラーを防ぐと、専門家の作業フローを中断してしまう場合。
モーション	装飾ではなく、ユーザーが状況を把握し続けられるようにトランジションを使います。	モーションは、原因、連続性、変化を示せます。	ユーザーがモーション低減を希望している場合、またはモーションによって遅延が生じる場合。
アクセシビリティ	キーボード操作、フォーカス、ラベル、コントラスト、スクリーンリーダー向けのセマンティクスを基本要件として扱います。	アクセシビリティは、インタラクションの品質そのものです。	決して別の要件で置き換えず、実装方法のみを調整します。
デザインシステム	既存のコンポーネントを再利用し、バリエーションや状態を文書化します。	一貫性の欠如と UX の負債を減らせます。	既存のコンポーネントにアクセシビリティ上の問題がある場合、またはタスクに適合しない場合。

必須の質問

パターンの選択やリスクモデルに回答が影響する場合に限り、焦点を絞った質問をしてください。一般的なベストプラクティスについて、定型的な質問はしないでください。

次のいずれかが不明で、判断に実質的な影響がある場合は質問してください。

1. 主なタスクと成功の条件：複数の目標が競合する場合。
2. 対象ユーザーのスキルレベルと利用頻度：ガイド付きフローとエキスパート向けワークスペースのどちらを選ぶか判断する場合。
3. プラットフォーム／デバイスのコンテキスト：モバイル、タッチ操作、デスクトップでの情報密度、キーボード利用、レスポンシブ動作が重要な場合。
4. データの形状と規模：リスト、テーブル、カードグリッド、ダッシュボード、フィード、フィルター、ページネーション、可視化のどれを選ぶか判断する場合。
5. 操作のリスク／可逆性：取り消し、確認、プレビュー、バッファーステップのどれを選ぶか判断する場合。
6. ナビゲーションの深さと情報アーキテクチャ：フラット型、ハブアンドスポーク型、ツリー型、ピラミッド型、ウィザード型、ワークスペース型のどれを選ぶか判断する場合。
7. デザインシステム／フロントエンドの制約：ユーザーが実装可能なガイダンスを必要としている場合。
8. アクセシビリティまたはコンプライアンスの制約：ドメイン固有の要件が基本的なアクセシビリティ要件を上回る可能性がある場合。

次のパターンを使用してください。

question({
  question: "What is the primary task users must complete on this screen?",
  recommended_default: "Optimize for the most frequent task and make secondary actions available but less prominent.",
  options: [
    "Find or browse items",
    "Compare and select items",
    "Create or edit something",
    "Monitor status or metrics",
    "Complete a step-by-step process",
    "Other / custom"
  ]
})

質問ツールですぐに使用できるプロンプトの一覧は、references/decision-prompts.md を参照してください。

ワークフロー

A. 既存の UI の批評

次の順序で確認してください。

1. ユーザーの目標とタスクへの適合性
   画面がユーザーの達成を支援しようとしていることを特定します。ユーザーよりもプロダクトの都合を優先するコントロール、文言、画面があれば指摘します。

2. 情報アーキテクチャと画面タイプ
   画面が概要、集中、作成、実行、ダッシュボード、フロー、ワークスペースのいずれであるかを判断します。パターンがタスクに合っているか確認します。

3. 道案内とナビゲーション
   現在位置の手がかり、入口、終了経路、パンくずリスト、進行状況インジケーター、ディープリンク、行き止まりからユーザーが復帰できるかを確認します。

4. 階層、グループ化、レイアウト
   主な対象やアクションが明確か、関連要素がグループ化されているか、視覚的な強さが優先度に合っているか、適切に段階的開示が使われているかを確認します。

5. 操作の明確さとコンポーネントの動作
   アフォーダンス、ラベル、アクションの配置、フィードバック、状態変化、ホバー／タッチの動作、キーボード操作、読み込み中、空、エラーの各状態を確認します。

6. 安全性と復旧
   取り消し、キャンセル、プレビュー、確認、エラー防止、中断されたワークフローへの耐性を確認します。

7. フォームと入力の動作
   ラベル、必須／任意の表示、入力タイプ、ヒント、デフォルト値、バリデーション、エラー文言を確認します。

8. データ表示とスキャンのしやすさ
   テーブル、カード、ダッシュボード、フィルター、並べ替え、データチップ、可視化が比較や意思決定を支援するか確認します。

9. アクセシビリティとインクルージョン
   キーボード操作、フォーカス順序、セマンティクス、ラベル、コントラスト、モーションの低減、ターゲットサイズ、色以外の手がかり、スクリーンリーダーでの動作を確認します。

10. フロントエンドの実現可能性とデザインシステムへの適合性
    コンポーネントの再利用、レスポンシブレイアウト、トークン化、状態の複雑さ、パフォーマンス、保守性を確認します。

次の形式で批評を返してください。

## Overall diagnosis
[1-3 sentence summary]

## Highest-impact fixes
1. [Fix] — [why it matters] — [pattern/component recommendation]
2. ...

## Component-level notes
- [Component]: [issue] → [recommended behavior]

## Accessibility and implementation notes
- [Specific requirement or constraint]

## Tradeoffs
- [When another pattern might be better]

B. デザインの作成または改善

次の順序で進めてください。

1. ユーザーの課題と成功の条件を明確にします。
2. 必要な場合に限り、対象ユーザーのスキル、プラットフォーム、データ規模、操作のリスクを特定します。
3. 画面タイプを選択します：概要、集中、作成、実行、ダッシュボード、フロー、ワークスペース。
4. ナビゲーションモデルと道案内の手がかりを選択します。
5. レイアウトの階層とグループ化を定めます。
6. コンポーネントを選択し、それぞれの役割を定義します。
7. 動作を定義します：インタラクション、フィードバック、状態、バリデーション、遷移、キーボード／フォーカス、復旧。
8. レスポンシブ動作とデザインシステムのバリエーションを定義します。
9. 品質チェックリストを実施します。
10. 推奨事項を、スタイルの好みではなく、ユーザータスクにもたらすメリットとして説明します。

新しい推奨事項は次の形式で返してください。

## Recommended pattern
[Pattern and why it fits]

## Structure
[Regions, navigation, hierarchy]

## Component behavior
[States, actions, feedback, validation]

## Accessibility and frontend notes
[Semantics, keyboard, responsive, state management]

## Alternatives considered
[Why not the likely alternatives]

意思決定フレームワーク

これらのパターンを出発点として選択してください。

画面とフローのパターン

• 概要画面：次に確認する項目をユーザーが選ぶ、リスト、グリッド、検索結果、フィード、ダッシュボード、コレクションに使用します。
• フォーカス画面：1つのオブジェクト、メディア項目、レコード、キャンバス、マップが中心となる場合に使用します。
• 制作ワークスペース：ユーザーがコンテンツを作成または操作する場合に使用します。ツールバー、パレット、インスペクター、直接操作は慎重に取り入れます。
• 実行画面：支払い、予約、インポート、エクスポート、セットアップ、確認など、範囲が限定された1つのタスクに使用します。
• ウィザード：依存関係のある、順序が決まった不慣れな手順に使用します。熟練者が繰り返し行うタスクには使用しません。
• ダッシュボード：モニタリング、トリアージ、意思決定に使用します。指標を装飾的に寄せ集めた画面にはしません。
• モーダル／オーバーレイ：背後のページのコンテキストを中断する必要がある、または維持する必要がある、範囲の限定されたタスクに使用します。複雑なフロー、大きなフォーム、背後のページと比較する必要があるコンテンツには使用しません。
• 複数ワークスペース／分割表示：複数のオブジェクトを比較・編集する必要がある、熟練者向けのタスクや多くのコンテキストが求められるタスクに使用します。
• 設定エディター：永続的な設定や構成に使用します。実装モデルではなく、ユーザーのメンタルモデルに沿って分類します。

ナビゲーションのパターン

• フラットナビゲーション：同じ階層の遷移先が少数ある場合に使用します。
• ハブ・アンド・スポーク：タスク間でユーザーが中央の場所に戻る場合に使用します。
• ツリー／多階層：大規模な階層型の情報空間に使用します。
• ピラミッド型：トップレベルの探索からより具体的なページに進み、分岐間の移動手段も維持する場合に使用します。
• ステップ形式：順序の決まったフローに使用します。
• 大規模メニュー／メニューページ：多くの遷移先を一覧で確認し、直接アクセスする必要がある場合に使用します。
• パンくずリスト：深い階層で使用します。主要なナビゲーションとして単独で使用しないでください。
• 進行状況インジケーター：複数ステップのプロセスでユーザーが現在地を把握する必要がある場合に使用します。
• 離脱手段：モーダル、ウィザード、深いナビゲーションから安全に離脱できる手段を必ず用意します。

リストとコンテンツのパターン

• テーブル：属性で行を比較する、並べ替えやフィルタリングを行う、正確な値を確認する、一括操作を行う構造化データに使用します。
• 高密度リスト：テキスト中心の項目や、受信トレイのようなトリアージに使用します。
• カード：画像、タイトル、概要、アクションを備え、各項目が独立したオブジェクトとなる場合に使用します。
• サムネイルグリッド：画像を見ながら項目を確認することが重要な、視覚的に認識しやすい項目に使用します。
• カルーセル：少数の任意の視覚的に豊かな項目に限って使用します。必須の選択肢をカルーセルに隠さないでください。
• ページネーション：位置、有限の項目数、SEO、パフォーマンスが重要な場合に使用します。
• 無限リスト：正確な位置がそれほど重要でないフィードや探索に使用します。読み込み状態と戻ったときの位置を維持します。
• 2パネルセレクター／分割表示：リストのコンテキストを失わずに、ユーザーがリストを見ながら詳細を確認する場合に使用します。
• リスト内表示：詳細が短く関連性がある場合に、画面全体を遷移せずに詳細を表示します。

アクションとコマンド

• 頻繁に使うアクションは、対象となるオブジェクトの近くに配置します。
• 破壊的なアクションやリスクの高いアクションは、日常的なアクションと視覚的にも空間的にも区別します。
• 関連性の高い少数のアクションにはボタングループを使用します。優先度の異なるアクションを混在させないでください。
• 対象のオブジェクトや操作がわかる、明確なメニューラベルを使用します。
• 結果が予測しにくい変更には、プレビューを用意します。
• 長時間実行される操作はキャンセルできるようにします。
• 元に戻せる操作や探索には、元に戻す機能や履歴を用意します。
• マクロや保存済みアクションは、熟練者が繰り返し行うタスクに限って使用します。

フォームとコントロール

• データに合った入力方法を選びます。選択肢が限られている場合はセレクトまたはラジオボタン、複数選択の場合はチェックボックス、おおよその範囲にはスライダー、小さな数値の増減にはステッパー、自由入力にはテキストフィールド、候補が多い既知の選択肢にはオートコンプリートを使います。
• システムが安全に解析できる場合は、既知の構造化文字列に柔軟な形式を使います。
• 精度、エラー防止、またはコンプライアンスが柔軟性より重要な場合は、構造化形式を使います。
• 該当するフィールドの近くにヒントを表示します。
• プレースホルダーは補助的に使います。表示ラベルは必ず残してください。
• 入力中にユーザーに負担をかけず、動的に入力値を検証します。
• 適切である可能性が高く、表示され、編集可能な場合は、適切なデフォルト値や事前入力を設定します。

フィードバックとマイクロインタラクション

• 直接操作の結果をすぐに表示します。
• 目立った時間がかかる処理では、進捗状況を表示します。
• 通知は、タイムリーで関連性があり、ユーザーが対処できる場合にのみ使用します。
• 比較、予測、または行動に役立つ場合は、定量的な状態を視覚化します。
• 通知のアクションは最小限にし、直接的なものにします。
• トランジションは連続性を示すために使い、タスクを遅らせないようにします。
• 視覚効果を減らす設定を尊重します。

実践的なルール

1. コンポーネントを推奨する際は、必ずそのコンポーネントがどのユーザータスクに役立つかを明記します。
2. 手順を見栄えよくするより、手順を減らすことを優先します。
3. 主要なアクションをメニュー、ホバー時のみ表示されるコントロール、または曖昧なアイコンの中に隠さないでください。
4. ユーザーが背後の内容を比較、参照、または移動する必要がある場合は、モーダルを使わないでください。
5. ユーザーが非線形の編集や熟練者向けのスピードを必要とする場合は、ウィザードを使わないでください。
6. 複数の属性で並べ替え、比較、または一括編集する必要があるデータに、カードを使わないでください。
7. 画像認識が主な操作となる、視覚的に豊かな閲覧には、テーブルを使わないでください。
8. 状態や選択を色だけで伝えないでください。
9. 大きなメリットがあり、テスト済みでない限り、ユーザーが位置を覚えた後にコントロールの配置を変えないでください。
10. ラベルの代わりにプレースホルダーテキストを使わないでください。
11. 元に戻せる操作の実行前に確認を求めず、元に戻す機能を提供します。
12. 明確なフィードバックと復旧手段なしに、自動で次へ進む、自動送信、自動削除を行わないでください。
13. 考えられるアクションをすべて一度に表示せず、状況に応じて関連する場面で高度なアクションを表示します。
14. タスクを完了する唯一の方法として、キーボードショートカットを使わないでください。
15. コンポーネントライブラリを完全な UX ソリューションとみなさず、タスク固有の動作と状態を定義します。

アクセシビリティとインクルージョンに関する要件

すべての推奨事項に適用される基本要件：

• まずセマンティック HTML またはプラットフォーム標準のセマンティクスを使います。
• 入力には視認できるラベルを、コントロールにはアクセシブルな名前を付けます。
• すべてのインタラクティブ要素をキーボードで操作できるようにします。
• 論理的なフォーカス順序と視認できるフォーカス状態を定義します。
• フォーカスを閉じ込めるのは本当のモーダル内だけにし、閉じた後はトリガーにフォーカスを戻します。
• ネイティブのセマンティクスでは不十分な場合に限り、適切な ARIA を使います。
• エラーメッセージをプログラムでフィールドに関連付けます。
• ホバー時のみの操作に頼らず、クリック、タップ、キーボードでの代替手段を用意します。
• 色だけに頼らず、テキスト、アイコン、形状、または位置を組み合わせます。
• 視覚効果を減らす設定を尊重します。
• モバイルまたはタッチインターフェースを設計する場合は、タッチ操作に適したターゲットサイズを使います。
• 必要に応じて、読み込み中、空、成功、エラーの各状態が通知されるようにします。
• 無効化されたコントロールの意味が分かるようにし、可能であればアクションを実行できない理由を説明します。
• 対象ユーザーが使うことが分かっている場合を除き、高度なデスクトップ操作の慣習を必要とするインタラクションパターンは避けます。

フロントエンド実装ガイダンス

出力に実装ガイダンスが含まれる場合は、次の項目を指定します。

コンポーネントの構成要素

ルート、ラベル、トリガー、コンテンツ、項目、アクション、補助テキスト、エラーテキスト、アイコン、バッジ、オーバーレイ、背景、フッター、および各種スロットなどのサブパーツを定義します。

状態

各コンポーネントについて、次の状態を定義します。

• デフォルト
• 該当する場合は、ホバー、押下、選択、展開、折りたたみ
• フォーカス可視
• 無効および読み取り専用
• 読み込み中およびスケルトン
• 空
• 成功
• 警告
• エラー
• 該当する場合は、オフラインまたは古いデータ
• モーション低減時の代替

セマンティック構造

ネイティブ要素を優先します。

• アクションには、クリック可能な div ではなく button を使用します。
• ナビゲーションには a を使用します。
• 入力には関連付けられた label を使用します。
• 真の表形式データには、table、thead、tbody、th、td を使用します。
• 真のモーダルには、dialog またはアクセシブルなモーダルパターンを使用します。
• リスト構造にはリスト（ul、ol）を使用します。
• ページ領域にはランドマーク（nav、main、aside、header、footer）を使用します。

キーボード操作

メニュー、ダイアログ、タブ、アコーディオン、テーブル、グリッド、オートコンプリート、ドラッグ操作のキーボード操作を指定します。ドラッグ＆ドロップ操作には、ドラッグを使わない代替手段を用意します。

レスポンシブ動作

コンポーネントがどのように適応するかを定義します。

• セカンダリー領域を縦に並べるか、折りたたみます。
• 主要なタスクとアクションを維持します。
• 発見可能な代替手段なしに、必須のナビゲーションを隠さないようにします。
• タッチターゲットに十分な大きさを確保します。
• ビューポートの変更後も状態を維持します。

デザインシステムとの統合

• 既存のスペーシング、カラー、タイポグラフィ、エレベーション、角丸、モーションのトークンを再利用します。
• 意味のある動作上またはセマンティックな違いがある場合にのみ、バリエーションを作成します。
• コンポーネントの意味を変える場当たり的なスタイルの上書きを避けます。
• コンテンツの制限、切り詰め、折り返し、長い値や空の値の扱いを文書化します。
• コンポーネントを使用すべきでない場合を文書化します。

パフォーマンスと保守性

• 必要な場合に限り、アクセシビリティと位置の復元に対応したうえで仮想化を使用します。
• 位置を復元したり、フッターコンテンツに到達したりする方法のない無限読み込みを避けます。
• 過剰なアニメーションやレイアウトシフトを避けます。
• コストの高いデータビジュアライゼーションやダッシュボードは、段階的に読み込みます。
• 読み込み状態を有用なものにします。まず安定した領域を表示し、読みやすいコンテンツを優先します。

品質チェックリスト

推奨事項を確定する前に、次の点を確認します。

• ユーザーのタスクが明確です。
• 推奨するパターンが、タスク、データの形、ユーザーのスキル、プラットフォーム、リスクに適しています。
• 主要なアクションが明確で、同等の重要度を持つアクションと競合していません。
• ナビゲーションと元に戻る手段が見える状態です。
• 状態の変化に対して、すぐに理解できるフィードバックがあります。
• 空、読み込み中、エラー、成功、無効の状態が定義されています。
• 破壊的またはコストの高いアクションに、適切な防止策または復旧手段があります。
• フォームの入力を最小限にし、ラベルを表示し、ヒントを示し、適切に検証し、問題発生時も無理なく復旧できます。
• コンポーネントはキーボードで操作でき、スクリーンリーダーで理解できます。
• レスポンシブ動作によって主要なタスクが維持されます。
• 推奨事項を再利用可能なコンポーネントとトークンで実装できます。
• トレードオフと代替案が説明されています。

references/checklists.md のチェックリスト全文を使用してください。

よくある避けるべき間違い

• ユーザーのタスクではなく、コンポーネントの好みを基準に設計する。
• ホームページやダッシュボードを何でも置く場所として扱う。
• 複雑なタスクにモーダルを多用する。
• ホバー時にしか表示されないツールの背後に、重要なアクションを隠す。
• すべてのアクションを視覚的に最優先にする。
• ユーザーが比較する必要がある場面でカードを選ぶ。
• ユーザーが視覚的に閲覧したい場面でテーブルを選ぶ。
• エキスパート向けのワークフローにウィザードを使用する。
• 取り消し可能な日常的な操作に確認ダイアログを使用する。
• 不慣れなアクションに、ラベルなしの凝ったアイコンを使用する。
• レイアウトを維持したり進捗を表示したりせずに、スケルトンやスピナーを使用する。
• キーボード操作とフォーカスの挙動を忘れる。
• デザインシステムを迂回する独自コンポーネントを作成する。
• 馴染みのある操作性を犠牲にして目新しさを優先する。

アンチパターンの一覧は、references/anti-patterns.md を参照してください。

推奨事項をユーザーに説明する方法

次の点から説明します。

1. ユーザーのタスク：「ユーザーはステータスと日付で行を比較する必要があるため、カードよりもテーブルのほうが適しています。」
2. 認知負荷：「次の手順を見える状態に保ち、選択した内容をユーザーに覚えておいてもらう必要がありません。」
3. コンテキストの維持：「分割ビューなら、詳細を切り替えてもリストを表示したままにできます。」
4. 安全性：「この操作は元に戻せるうえ、頻繁に行われるため、ここでは確認ダイアログよりも取り消し機能のほうが適しています。」
5. アクセシビリティ：「この操作はキーボードで実行できる必要があり、ホバーに依存してはいけません。」
6. 実装：「既存のテーブルコンポーネントを再利用し、空・エラー・読み込み状態を追加できます。」

視覚的な変更によって情報の階層、読みやすさ、操作のわかりやすさ、またはアクセシビリティが直接向上する場合を除き、「見た目が良くなります」とは言わないでください。