Guidelines

コンポーネント選定

似ている UI の責務を分け、どのコンポーネントを選ぶべきかを判断するためのガイドです。見た目の近さではなく、ユーザーの目的と状態の持ち方で選びます。

Actions

操作コンポーネントの選び方

操作は、状態を変えるのか、移動するのか、補足情報を出すのかで選びます。

Button

保存、送信、削除、検索、開くなど、現在の画面やデータの状態を変える操作に使います。外部ページへの移動を Button に見せかけません。

TextLink

別ページ、外部資料、詳細ページへ移動する時に使います。`target="_blank"` には外部タブアイコンと支援技術向けラベルを付けます。

TooltipButton

アイコンだけのボタン、状態切替、危険操作、意味が曖昧な操作には、見た目より先に説明をセットで用意します。

CopyButton

クリップボード操作専用です。コピー対象、成功、失敗、ラベル付き / アイコンのみの違いが preview と code に出る必要があります。

判断例

抽象的な原則を、実装・レビュー時の具体的な判断に落とします。

場面避ける推奨理由
外部資料を開くButton でリンクのように見せるTextLink + 外部タブアイコン + 補足ラベル移動はリンク、状態変更はボタンに分けるため。
保存できない理由を伝えるdisabled の見た目だけにするdisabled control を wrapper に入れ、Tooltip で理由を出すユーザーが次に何をすればよいか判断できるため。

Disclosure

情報を一時的に出す UI

Tooltip

短い説明、disabled 理由、アイコンの意味に使います。中にボタンや選択肢を置くなら Tooltip ではありません。

Popover

補足情報、軽い選択、短い設定に使います。選択した結果があるなら、トリガーや周辺表示にも反映します。

DropdownMenu

コマンドのリストに使います。情報カードや長い説明を入れるなら Popover や Dialog を検討します。

HoverCard

リンク先や人物、ファイルなどの概要を見せる用途です。タッチ端末ではタップで開く導線と閉じ方を確認します。

判断例

抽象的な原則を、実装・レビュー時の具体的な判断に落とします。

場面避ける推奨理由
アイコンの意味だけを説明するPopover にボタンや状態を入れるTooltip で短く説明する操作を含まない短い補足だから。
軽い設定をその場で変えるDropdownMenu に説明文とフォームを詰めるPopover で状態を持ち、選択結果をトリガーに反映する情報と選択を同じ小さな面で扱うため。

Overlays

画面の上に出す UI

Dialog / AlertDialog

短いフォームや確認に使います。削除など取り消せない操作は、操作前に AlertDialog で確認します。

Drawer / Sheet

現在の画面文脈を残したまま、補助操作や詳細設定を出す時に使います。Dialog と同じ内容を横から出すだけにしません。

Modal

複数ステップ、タブ、広い本文など、Dialog より構成が大きいブロックに使います。小さな確認だけなら AlertDialog に寄せます。

MediaLightbox / MediaPickerDialog

メディア閲覧と選択は分けます。閲覧は画像中心、選択は一覧・状態・確定操作を中心に設計します。

確認チェック

PR 前、または人間の目視確認前に見る項目です。

  • 開く理由が明確

    Dialog、Drawer、Sheet、Modal のどれを使うかを、サイズではなく文脈保持・作業量・確認の強さで選んでいます。

  • 閉じ方とフォーカス復帰を確認した

    Escape、閉じるボタン、外側クリック、保存後の挙動、フォーカス復帰を確認しています。

Data

データ表示の選び方

Table と DataTable

静的な比較は Table。検索、並び替え、ページング、選択、行アクションが必要なら DataTable を使います。

List / MetadataList / Timeline

同質の項目は List、属性の集合は MetadataList、時系列の進行や履歴は Timeline に分けます。

Chart と Statistic

単一の現在値は Statistic。比較、推移、構成比、分布を読むなら chart を選び、データ定義を code に含めます。

Card

ひとまとまりの情報や操作を区切る時に使います。ページセクション全体をカード化したり、カードの中にカードを重ねたりしません。

判断フロー

上から順に確認し、途中で判断できる場合はそこで決めます。

  1. 1

    対象が単一値か集合かを分ける

    単一の現在値は Statistic、項目集合は List、属性集合は MetadataList、行列は Table / DataTable にします。

  2. 2

    操作があるか確認する

    検索、並び替え、選択、ページング、行アクションがあるなら DataTable を選びます。

  3. 3

    コピー可能なデータを含める

    docs では、表示している配列や値が code に含まれているか確認します。

このガイドは固定ルールではなく、GunjoUI のコンポーネントや docs で繰り返し確認する判断基準です。迷った場合は、既存コンポーネント、SSOT、アクセシビリティ、プレビューとコードの一致を優先します。