component-patterns

コンポーネントパターン

Web アプリケーション向けの最新 UI コンポーネントパターンです。現在の標準（21st.dev SDK、Tailwind、Radix UI）に沿った、コンポーネントの選定、合成、テーマ設定、トークンシステムを扱います。

対象範囲

以下の場合にこのスキルを使用します。

• UI コンポーネントを設計または選定するとき
• デザイントークンシステムを構築するとき
• テーマ設定（ダーク／ライト／カスタム）を実装するとき
• 複合コンポーネントやバリアントシステムを計画するとき
• フォームのアーキテクチャを設計するとき
• レスポンシブなコンポーネント戦略を定義するとき

原則

1. 継承より合成

小さく専門化されたパーツを組み合わせてコンポーネントを構築します。設定には props、コンテンツには children、バリエーションには slots を使います。

2. サーバー優先、必要な場合のみクライアント

デフォルトではサーバーコンポーネントを使用します。クライアントコンポーネントは、インタラクティブ性（状態、イベントハンドラー、ブラウザー API）が必要な場合にのみ使用します。

3. トークンベースのテーマ設定

デザイントークン（CSS カスタムプロパティ）ですべての視覚的要素を制御します。色、間隔、フォントサイズをハードコードしないでください。

4. アクセシビリティをアーキテクチャの一部に

ARIA ロール、キーボードナビゲーション、フォーカス管理は後付けではなく、コンポーネント定義の一部です。

5. 合成可能なプリミティブ

基本プリミティブ（Button、Input、Text、Box）はスタイルを持たず、最大限に柔軟です。デザインシステムのコンポーネントは、これらを基に構築します。

ルール

コンポーネント構造

• 推奨：各コンポーネントを、明確なエクスポートを持つ単一ファイルにします。1 コンポーネントにつき責務は 1 つです。
• 推奨：props インターフェースを明示的に型付けします（TypeScript）。検証対象の入力には Zod スキーマを使用します。
• 推奨：複雑な UI 要素には複合コンポーネントを使用します。

  <Card>
    <Card.Header />
    <Card.Body />
    <Card.Footer />
  </Card>
  

• 推奨：条件付きクラスの代わりに class-variance-authority（cva）でバリアントを定義します。
• 非推奨：props が 10 個を超えるコンポーネント。責務が増えすぎたら分割します。
• 非推奨：実行時の CSS-in-JS。静的なスタイルには Tailwind CSS または CSS Modules を使用します。
• 非推奨：div だらけの構造。意味のある HTML 要素（section、article、nav、header、footer、main）を使用します。

テーマ設定とデザイントークン

• 推奨：3 層のトークンシステムを使用します。
  • グローバルトークン：生の値（colors.blue.500、spacing.4、radius.md）
  • セマンティックトークン：用途に紐づく値（color.primary、color.surface、spacing.section）
  • コンポーネントトークン：コンポーネント固有の値（button.bg、card.padding、input.border）
• 推奨：html／body の data 属性またはクラスと CSS カスタムプロパティを使ってテーマを切り替えます。
• 推奨：最低限、ダークとライトに対応します。必要に応じて、ハイコントラストやブランド固有のテーマも追加します。
• 非推奨：テーマ対応が必要な値へのインラインスタイル。常にトークンを参照します。
• 非推奨：色を表すトークン名（--blue-500）。セマンティックな名前（--color-primary）を使用します。

フォームコンポーネント

• 推奨：スキーマ駆動のフォームを使います。Zod スキーマでフィールドと検証を定義します。
• 推奨：パフォーマンス向上のため、React Hook Form などを使用します（非制御コンポーネント）。
• 推奨：一貫したフィールド構成にします。ラベル > 入力欄 > 補助テキスト > エラーメッセージ。
• 非推奨：キーボード操作に対応していないカスタムセレクト。ネイティブの Select または Radix UI Select を使用します。
• 非推奨：送信後の読み込み状態と成功状態がないフォーム。

レスポンシブコンポーネント

• 推奨：コンポーネント単位のレスポンシブ対応にはコンテナクエリを使用します。
• 推奨：モバイル向けのバリエーションを専用の状態として用意します（チャットパネルは全画面表示、サイドバーはドロワーになります）。
• 推奨：モバイルではタッチターゲットを少なくとも 44x44px にします。
• 非推奨：タッチ操作で代替できない、ホバーに依存するインタラクション。
• 非推奨：モバイルでコンポーネント内に横スクロールを設けること（カルーセルを除く）。

追加のルールとコード例については、references/implementation.md を参照してください。

パターン

パターン	用途	中核となる考え方
3ペインレイアウト	ダッシュボード、チャットアプリ	ナビゲーション（240px）＋コンテンツ（可変幅）＋コンテキスト（320px）
段階的開示カード	複雑なデータ、API レスポンス	概要 ＞ 詳細 ＞ 生データ
フォームとエージェントのハイブリッド	フォームアシスタント	左側にフォーム、右側にチャットを配置し、エージェントがフィールドに入力
リアルタイム状況ダッシュボード	モニタリング、DevOps	WebSocket/SSE によるライブ更新、色分けされたタイル
スキル設定パネル	エージェントの設定	システムプロンプト ＋ スキルライブラリ ＋ デプロイボタン

パターンの詳細については、references/patterns.md を参照してください。

アンチパターン

1. ゴッドコンポーネント -- チャット、ツール、フォーム、ナビゲーションを同時に扱う単一のコンポーネント。分割してください。
2. テーマのプロップドリリング -- テーマ値を5階層以上にわたって渡します。コンテキストまたは CSS カスタムプロパティを使用してください。
3. すべてをクライアント側で実行 -- すべてをクライアントコンポーネントにします。静的コンテンツにはサーバーコンポーネントを使用してください。
4. レイアウトにインラインスタイルを使用 -- トークンベースのユーティリティの代わりに style={{ marginTop: 20 }} を使用します。
5. 何にでもモーダルを使用 -- インライン展開、ドロワー、パネルを優先してください。
6. 制御されていない状態の爆発的な増加 -- 一元管理された状態ストアまたはサーバー状態（React Query/SWR）を使用してください。
7. ブレークポイントのハードコード -- テーマ設定でブレークポイントトークンを定義してください。
8. エラーバウンダリーの欠如 -- 重要なセクションの周囲に React エラーバウンダリーを配置してください。

チェックリスト

• すべてのコンポーネントに型付きの props インターフェースがある（TypeScript）
• 複雑な要素（Card、Dialog、Tabs）には複合コンポーネントを使用する
• cva または類似のシステムでバリアントを定義する
• デザイントークンを3つの階層（グローバル、セマンティック、コンポーネント）で定義する
• テーマの切り替えには JS の実行時処理ではなく CSS カスタムプロパティを使用する
• フォームの検証には Zod スキーマを使用する
• サーバーコンポーネントをデフォルトとし、必要な場合のみクライアントコンポーネントを使用する
• コンポーネントベースのレスポンシブ対応にはコンテナクエリを使用する
• 重要な UI セクションの周囲にエラーバウンダリーを配置する
• モバイルのタッチターゲットは少なくとも 44x44px にする
• すべてのインタラクティブ要素をキーボードで操作できるようにする
• スクリーンリーダー向けに ARIA ロールとラベルを設定する
• div の多用を避け、セマンティックな HTML 要素を使用する

関連項目

• design-trends -- コンポーネント設計に影響するトレンド（モーション、ダークモード）
• ui-patterns -- コンポーネントとして実装された UI パターン
• visual-direction -- トークンシステム用のビジュアルトークン（色、タイポグラフィ、間隔）
• agent-ui-design -- エージェント固有のコンポーネント（チャット、ツール、ストリーミング）
• accessibility -- アクセシビリティ要件
• responsive-design -- ブレークポイント戦略とコンテナクエリ