studio-ui-patterns

Studio UI パターン

デザインシステムのドキュメントとデモが正式な情報源です。新しい UI を作成する前に、必ず該当するデモファイルを確認してください。

レイアウト

ドキュメント：apps/design-system/content/docs/ui-patterns/layout.mdx

PageContainer、PageHeader、PageSection を使ってページを構築します。

コンテンツの種類	size
設定 / 構成	"default"
リスト / テーブル	"large"
全画面表示	"full"

• リストページにフィルターや検索がある場合、テーブルのアクションをフィルターに揃えます（それらのアクションに PageHeaderAside / PageSectionAside は使わないでください）
• フィルターがない場合、アクションは PageHeaderAside または PageSectionAside に配置できます

デモ：page-layout-settings.tsx、page-layout-list.tsx、page-layout-list-simple.tsx、page-layout-detail.tsx （すべて apps/design-system/registry/default/example/ にあります）

フォーム

ドキュメント：apps/design-system/content/docs/ui-patterns/forms.mdx

• react-hook-form と zod を使います
• FormItem / FormLabel / FormMessage / FormDescription を手動で組み合わせる代わりに、FormItemLayout を使います
• 入力を FormControl でラップし、プリミティブは ui からインポートします

レイアウトの選択：

コンテキスト	レイアウト	コンテナ
ページ（設定 / 構成）	FormItemLayout layout="flex-row-reverse"	Card（フィールドごとに CardContent、アクションには CardFooter）
サイドパネル — 幅広	FormItemLayout layout="horizontal"	SheetSection
サイドパネル — 狭い（size="sm" 以下）	FormItemLayout layout="vertical"	SheetSection

未保存状態 / 送信：

• isDirty を使ってキャンセルを表示し、保存を無効にします。form.formState からの分割代入は useForm を所有するコンポーネントでのみ行います。それ以外の場所では useFormState({ control }) で購読します（react-hook-form のスキルを参照）
• loading プロパティを使って送信ボタンに読み込み状態を表示します
• 送信ボタンが <form> の外にある場合は、安定した formId を設定し、ボタンの form プロパティを使います

デモ：form-patterns-pagelayout.tsx、form-patterns-sidepanel.tsx

テーブル

ドキュメント：apps/design-system/content/docs/ui-patterns/tables.mdx

パターン	使用する場面
Table	シンプルで静的、セマンティックな表示
Data Table	TanStack ベース。ソート、フィルタリング、ページネーションに対応し、用途ごとに構成
Data Grid	仮想化、列幅の変更、または複雑なセル編集が必要な場合

• アクション：テーブルの上部、右揃え
• 検索 / フィルター：テーブルの上部、左揃え
• フィルターがなく、テーブルが主要コンテンツの場合、アクションはページの主アクション / 副アクションの領域に配置できます

デモ：table-demo.tsx、data-table-demo.tsx、data-grid-demo.tsx

チャート

ドキュメント：apps/design-system/content/docs/ui-patterns/charts.mdx

• 用意されているチャートの構成要素を使います。生の Recharts コンポーネントを ChartContent に渡すのは避けてください
• 読み込み状態 / 無効状態には useChart のコンテキストフラグを使います
• 構成はシンプルに保ち、過度な抽象化は避けてください

デモ（apps/design-system/registry/default/block/ 内）：chart-composed-demo.tsx、chart-composed-basic.tsx、chart-composed-states.tsx、chart-composed-metrics.tsx、chart-composed-actions.tsx、chart-composed-table.tsx

空状態

ドキュメント：apps/design-system/content/docs/ui-patterns/empty-states.mdx

シナリオ	パターン
初回／オンボーディング	提供価値と明確な次のアクションを示す、表示用の空状態
データ量の多いリスト	リスト／テーブルのレイアウトに合わせた、情報を伝える空状態
検索結果がゼロ件	急な切り替わりを避けるため、データ表示時と同じレイアウトを維持する
存在しないルート	中央に配置した Admonition

デモ：empty-state-presentational-icon.tsx、empty-state-initial-state-informational.tsx、empty-state-zero-items-table.tsx、data-grid-empty-state.tsx、empty-state-missing-route.tsx

ナビゲーション

ドキュメント：apps/design-system/content/docs/ui-patterns/navigation.mdx

• 一貫したページレイアウト内で関連するビューを横並びに表示するには、NavMenu を使用します
• 項目を選択したときは、URL の変更を発生させる必要があります。ローカルのみのタブ状態は使用しないでください

カード

• 関連する情報をカードにまとめます
• セクションには CardContent、アクションには CardFooter を使用します
• 周囲のコンテンツですでに文脈が示されている場合は、CardHeader／CardTitle を使用しないでください
• 複数のカードで異なるグループ（複数の設定セクションなど）を表す場合は、ヘッダー／タイトルを使用します

アラート

• 重要なアクション、制限事項、または重要な文脈を目立たせるには、Admonition を使用します
• ページのコンテンツの先頭（ページタイトルの下）または該当セクションの先頭（セクションタイトルの下）に配置します
• 使用は必要最小限にします

シート（サイドパネル）

ページを切り替えると操作が中断され、ユーザーが文脈を維持する必要がある場合（リストから行を選択して編集する場合など）は、Sheet を使用します。

構成：

• 水平方向のレイアウトが必要なフォームには、size="lg" を指定した SheetContent を使用します
• SheetHeader、SheetTitle、SheetSection、SheetFooter を使用します
• 送信／キャンセルのアクションは SheetFooter に配置します

シート内のフォーム：

• 幅の広いシートには layout="horizontal" を使用します
• 幅の狭いシート（size="sm" 以下）には layout="vertical" を使用します
• シートにフォームが含まれる場合は、useConfirmOnClose と DiscardChangesConfirmationDialog を組み合わせて、未保存の変更がある状態で閉じる際の確認を実装します （キャンセル、Escape、背景のクリック）。正とする情報源は apps/design-system/content/docs/ui-patterns/modality.mdx（フォームの未保存変更時の終了）です。 isDirty の分割代入については、react-hook-form スキルも参照してください。

コピー

正とする情報源：apps/design-system/content/docs/copywriting.mdx — センテンスケース、タイトルケース、固有名詞、文体とトーン。

表示コピーを変更する場合は、e2e/studio/ で以前の文字列を grep します。