コンポーネント命名規則と役割の用語集
このドキュメントは、デザインシステム内で使用するUIコンポーネントの名称と、それぞれの役割を定義したものだ。 デザイナーとエンジニアが共通の言語でコミュニケーションを取り、プロジェクト全体で一貫したUI手法を維持することを目的としている。
命名の基本方針
- 役割ベースの命名: 見た目ではなく、UIがシステム内でどう機能するか（例： 色を選択する機能なら
ColorPicker）で命名する。 - 標準的な名称の採用: Radix UI、Adobe Spectrum、Material Designなど、業界で広く使われている名称を優先する。
紛らわしい名称の使い分け（アンチパターンと推奨事項）
似たような機能や見た目を持つコンポーネントについて、本デザインシステムでの取り扱いを定義する。
Dialog vs Modal
- 推奨:
Dialog。 - 理由:「Modal（モーダル）」は「背景の操作をブロックする状態」を指す言葉であり、コンポーネントの名称としては機能を表す「Dialog（対話窓）」を優先する。
Toast vs Snackbar
- 推奨: 両者を使い分ける。
Toast(トースト): システムからの通知（「保存が完了しました」「新着メッセージがあります」等）。ユーザーのアクションを伴わないことが多く、自動で消える。Snackbar(スナックバー): ユーザーの操作に対する直接的なフィードバック。元に戻す（Undo）などのアクションボタンを含むことが多く、画面下部に表示される。
Select vs Menu vs Dropdown
- 推奨: 用途で使い分ける。「Dropdown」は一般名詞として極力避ける。
Select: リストから値を選択するためのコンポーネント（フォーム入力の一部）。Menu/DropdownMenu: アクション（「編集」「削除」など）のリストを表示・実行するためのコンポーネント。
Switch vs Toggle
- 推奨:
Switch。 - 理由: Toggle（トグル）は「状態の切り替え」という概念やToggleButtonなどの派生コンポーネントを指す場合がある。物理的なスイッチを模したON/OFFのUIは「Switch」に統一する。
コンポーネント一覧と役割
アクション (Action)
ユーザーがシステムに対して何らかの操作をするためのコンポーネント群だ。
Button: 最も基本的なアクションの実行に使用する。IconButton: アイコンのみでアクションを示すボタンだ。Toolbarなどで使用する。SplitButton: メインアクションのボタンと、関連する別アクションを選ぶドロップダウンを組み合わせたボタンだ。ButtonGroup: 関連する複数のボタンを視覚的にグループ化して配置する。ToggleButton: 押された状態（ON）と押されていない状態（OFF）を切り替えられるボタンだ。Link: 他のページやセクションへのナビゲーションに使用する。アクションの実行には原則としてButtonを使用する。FAB(Floating Action Button): 画面上に浮遊して表示され、その画面の主要なアクションを表す。CopyButton: テキストやリンクをクリップボードにコピーする専用のボタンだ。
入力・選択 (Input & Selection)
ユーザーからテキストや値を受け取るためのコンポーネント群だ。
TextField: 1行の短いテキスト入力フィールドだ。（注：InputはHTMLタグ名と混同しやすいためTextFieldを推奨する）。TextArea: 複数行の長いテキスト入力フィールドだ。Checkbox: 独立した設定のON/OFF、または複数選択に使用する。CheckboxGroup: 関連付けられた複数のCheckboxをまとめるコンポーネントだ。Radio: 排他的な選択肢の1項目だ。RadioGroup: 複数のRadioをまとめ、1つだけを選択可能にするコンポーネントだ。Switch: 即座に設定が反映されるON/OFFの切り替えに使用す る。Select: ドロップダウンリストから1つの値（または複数）を選択するコンポーネント全体だ。SelectItem:Selectリスト内の個々の選択肢だ。ComboBox: テキスト入力による選択肢の絞り込み機能が付いたセレクトボックスだ。（注：Autocompleteも同義で使われますが、本システムではComboBoxに統一する）。Slider: 連続した範囲の中から値を感覚的に選択します（音量調節など）。RangeSlider: 上限と下限の2つの値の範囲を選択できるSliderだ。DatePicker: カレンダーUIをポップアップ等で表示し、日付を入力・選択する。DateRangePicker: 開始日と終了日の範囲を選択するDatePickerだ。TimePicker: 時刻を入力・選択する。Calendar: 日付選択のポップアップではなく、月間カレンダー等を画面に直接静的に表示するコンポーネントだ。FileInput: クリックしてファイルを選択する、標準的なファイルアップロード用の入力フィールドだ。Dropzone: ドラッグ＆ドロップによるファイルアップロードに最適化された専用の領域だ。Rating: 星マークなどで評価を入力・表示するコンポーネントだ。ColorPicker: 色を選択するためのUIだ。PinInput: ワンタイムパスワードや暗証番号など、1桁ずつ入力するフィールドだ。（注： 汎用性を持たせるためOTPInputではなくPinInputを推奨する）。NumberInput: 数値の増減ボタン（スピンボタン）がついた入力フィールドだ。TagInput: テキストを入力してEnter等でタグを追加していく入力フィールドだ。Form: データを送信するフォーム全体を囲むコンポーネントだ。FormField: 個別の入力エリア（ラベル、入力フィールド、エラーメッセージなど）を1つのグループとしてまとめるコンポーネントだ。Label: 入力要素に関連付ける見出しテキストだ。SearchField: 検索に特化した入力フィールド（虫眼鏡アイコンやクリアボタン付き）だ。
タイポグラフィ (Typography)
テキストベースの情報を構造化し、一貫したスタイルで表示するためのコンポーネント群だ。
Heading: ページやセクションの見出しとして使用する。（注：TitleよりもHTML構造を反映しやすく汎用性の高いHeadingを推奨する）。Text: 一般的なテキストを表示する。weight="bold"等のPropsを通じて、様々なテキスト表現を1つのコンポーネントで管理する。Code: ソースコードの断片（インライン）を等幅フォントなどで表示する。CodeBlock: 複数行にわたるソースコードのブロックを表示する。シンタックスハイライト等を含む場合がある。Label: フォームの入力項目などに対する「見出しラベル」だ。（※ フォーム定義でも参照されますが、基本はタイポグラフィの一部として扱う）。
ナビゲーション (Navigation)
アプリケーション内の移動や、情報の階層構造を示すコンポーネント群だ。
Tabs: 関連するビューやコンテンツを切り替えるコンポーネント全体を指す。Tab:Tabs内の個々の見出し（選択可能なタブ）だ。TabPanel:Tabが選択された時に表示されるコンテンツ領域だ。Breadcrumbs（パンくずリスト）: 現在のページの階層位置を示すナビゲーション全体だ。BreadcrumbItem:Breadcrumbs内の個々のリンク項目だ。Pagination: 長いリストやテーブルを複数ページに分割し、ページ間を移動する。Drawer: 画面の端からオーバーレイ（覆いかぶさるよう）にスライドインして表示される一時的なメニュー領域だ。Sidebar: コンテンツの横に常時、またはレイアウトの一部として固定で配置されるナビゲーション領域だ。BottomNavigation: 主にモバイル端末向けの、画面下部に固定される主要ナビゲーションだ。Menu: アクションリストをポップアップで表示する。（注：DropdownMenuと同義だが、シンプルにMenuに統一する）。MenuItem:Menu内の個々のアクション項目だ。ContextMenu: 右クリック等の操作でカーソル位置に表示されるアクションメニューだ。NavigationMenu: ヘッダー等に配置される、複雑な階層を持つメガメニュー用のコンポーネントだ。Stepper: ウィザード形式など、複数のプロセスの進行状況とナビゲーションを提供するコンポーネント全体だ。Step:Stepper内の個々の工程を示す項目だ。Anchor: ページ内の特定のセクションへの目次リンクを提供するコンポーネントだ。ScrollSpy: スクロール位置に合わせて現在のAnchorをハイライトする機能を持ったナビゲーションラッパーだ。
フィードバック (Feedback)
システムの状態や処理結果をユーザーに伝えるコンポーネント群だ。
Alert: エラーや警告など、ユーザーの注意を引くべき重要な静的メッセージをインラインで表示する。Toast: 画面の隅に一時的に表示されるシステムからの通知だ。アクションを持たず自動で消える。Snackbar: 画面下部等に一時的に表示される操作後のフィードバックだ。Undo等のアクションを含むことがある。Spinner: 丸いインジケーターで、処理中であることを示す。進捗が不明な場合によく使われる。（注：CircularProgressは避けSpinnerを推奨する）。ProgressBar: 線状のインジケーターで、処理中であることを示す。進捗割合(%)が明確な場合に使われる。（注：LinearProgressは避けProgressBarを推奨する）。Skeleton: コンテンツのロード中に、レイアウトの枠組みだけをプレースホルダーとして表示する。Badge: アバターやアイコンの隅に情報のステータスや通知数（赤丸や数字）を表示する。Banner: 画面最上部などに表示され、システム全体に関する重要なお知らせ（メンテナンスなど）を伝える。Message: 特定の要素やセクションに対するエラー文言や説明文を表示する 汎用的なコンポーネントだ。FormMessage: フォームの入力フィールド (FormField) に特化し、バリデーションエラーや説明を自動的に連携して表示するコンポーネントだ。Notification: Toastよりリッチな通知（タイトル、本文、アイコン、閉じるボタン等）を表示するためのパネルだ。Callout: 記事やドキュメント内で、補足情報やヒントを視覚的に強調して表示するブロックだ。
データ表示 (Data Display)
データを整理してわかりやすく提示するためのコンポーネント群だ。
Avatar: ユーザーのプロフィール画像やイニシャルを表示する。AvatarGroup: 複数のAvatarを重ねて表示し、参加者一覧などを示す。Card: 関連する情報やアクションをひとまとまりの矩形領域にグループ化して表示する。Carousel: 複数枚の画像やカードなどのコンテンツを横にスライドして表示するコンポーネント全体だ。CarouselItem/Slide:Carousel内の個々のスライド要素だ。Table: データを表形式（行と列）で整理して表示するコンポーネント全体だ。TableRow/TableCell/TableHeader:Tableを構成する行、セル、見出しの各要素だ。Tooltip: 補足説明を表示するツールチップ全体を管理するコンポーネントだ。TooltipTrigger: ホバーまたはフォーカスによってTooltipを表示させる引き金となる要素だ。TooltipContent: 実際に表示される吹き出しとその中身だ。Popover: 詳細情報や設定を表示するポップオーバー全体を管理するコンポーネントだ。PopoverTrigger: クリックによってPopoverを表示させる引き金となる要素だ。PopoverContent: 実際に表示されるパネルとその中身だ。Accordion: 複数の項目があり、1つを開くと他の項目が自動で閉じる（排他的な）開閉パネルのリスト全体だ。AccordionItem:Accordion内の個々の開閉可能なパネル項目だ。Disclosure: 単一、または複数の項目がそれぞれ独立して開閉可能なパネルだ。List: アイテムを縦に並べて表示するコンポーネント全体だ。ListItem:List内の個々の項目だ。TreeView: ファイルシステムのような階層構造を持つデータを、折りたたみ可能なリストで表示する。（注：Treeよりコンポーネントとして明確なTreeViewを推奨する）。Tag: カテゴリ、属性、ステータスなどの短い情報を視覚的に表現する小さな要素だ。（注：ChipやPillなどの類義語は避け、Tagに統一する）。Stat: 数値とそのラベルを強調して表示するダッシュボード向けコンポーネントだ。（注：StatisticやMetricより短く扱いやすいStatを推奨する）。EmptyState: データがない場合やエラー時に、ただの空白ではなくイラストや案内文を表示して次のアクションを促す。Kbd: ユーザー入力に必要なキーボードのキー（例：Ctrl+C）を視覚的にスタイリングして表示する。DescriptionList: 用語（または項目名）と、その定義（値）のペアをリスト状に並べて表示するコンポーネント全体だ。DescriptionTerm/DescriptionDetails:DescriptionList内の用語（DTに相当）とその定義内容（DDに相当）を示す各要素だ。
構造・レイアウト (Layout & Structure)
他のコンポーネントを配置し、ページ全体の骨格を作るためのコンポーネント群だ。
Box: 最も汎用的なコンポーネント。div要素のラッパーとして、背景色や余白などのスタイルを適用する。Stack(VStack / HStack): 子要素を縦（VStack）または横（HStack）に等間隔で一直線に並べるレイアウトだ。Grid: CSS Gridを利用し、子要素を2次元（行と列）のあみだ目状に配置する。Container: コンテンツの最大幅を制限し、中央揃えにするためのレイアウト要素だ。Divider: コンテンツ間を区切る線だ。（注：Separator同義だがDividerに統一する）。AspectRatio: 画像や動画などを、指定したアスペクト比（縦横比）を維持したまま表示するための枠組みだ。ScrollArea: ネイティブのスクロールバーをカスタマイズ可能なカスタムスクロールバーに置き換える領域だ。Spacer: FlexboxやStack内で、要素間に余白を確保するための空のコンポーネントだ。
オーバーレイ (Overlay)
現在のコンテンツの上に覆いかぶさるように表示されるコンポーネント群だ。
Dialog(Modal): ユーザーに情報を伝えたり要求するために表示されるウィンドウ全体だ（背景の操作はブロックされる）。DialogTrigger:Dialogを開くためのボタン等の要素だ。DialogContent:Dialogとして実際に画面中央等に表示されるパネルだ。AlertDialog: データの削除など、破壊的または重要なアクションの実行を確認するためのDialogだ。HoverCard: リンクや要素へホバーした際、リンク先のプレビューなどを表示するカード全体だ。HoverCardTrigger: ホバーによってHoverCardを表示させる要素だ。HoverCardContent: 実際に表示されるプレビューカードだ。Sheet: 画面の端からスライドインし、一時的なアクションや追加情報を提供するパネル全体だ。（注：BottomSheetは下部からの登場に限定されるため、より汎用的なSheetを推奨する）。SheetTrigger:Sheetを開くための要素だ。SheetContent: 実際にスライドインしてくるパネルコンテンツだ。