React Composition Patterns

柔軟で保守性の高い React コンポーネントを構築するためのコンポジションパターンです。複合コンポーネント、状態のリフティング、内部構成の組み合わせを使用することで、ブール型プロップの増殖を回避できます。これらのパターンにより、コードベースはスケーリング時に人間とAIエージェントの両者にとって扱いやすくなります。

トリガー

• composition
• layout
• grid
• flexbox
• responsive
• breakpoint
• container
• spacing
• alignment
• structure
• page layout
• component composition

適用する場合

以下の場合にこれらのガイドラインを参照してください:

• 多くのブール型プロップを持つコンポーネントのリファクタリング
• 再利用可能なコンポーネントライブラリの構築
• 柔軟なコンポーネント API の設計
• コンポーネントアーキテクチャのレビュー
• 複合コンポーネントまたはコンテキストプロバイダーの操作

ルールカテゴリー(優先度順)

優先度	カテゴリー	影響度	プレフィックス
1	コンポーネントアーキテクチャ	HIGH	architecture-
2	状態管理	MEDIUM	state-
3	実装パターン	MEDIUM	patterns-
4	React 19 API	MEDIUM	react19-

クイックリファレンス

1. コンポーネントアーキテクチャ (HIGH)

• architecture-avoid-boolean-props - 動作をカスタマイズするためにブール型プロップを追加しないこと。代わりにコンポジションを使用してください
• architecture-compound-components - 共有コンテキストを使用して複雑なコンポーネントを構造化してください

2. 状態管理 (MEDIUM)

• state-decouple-implementation - プロバイダーのみが状態管理方法を認識する唯一の場所です
• state-context-interface - 状態、アクション、メタデータを含む汎用インターフェースを定義し、依存性注入に使用してください
• state-lift-state - 兄弟コンポーネント間でのアクセスのために、状態をプロバイダーコンポーネントに移動してください

3. 実装パターン (MEDIUM)

• patterns-explicit-variants - ブール型モードの代わりに、明示的なバリアントコンポーネントを作成してください
• patterns-children-over-render-props - renderX プロップの代わりに children を使用してコンポジションしてください

4. React 19 API (MEDIUM)

⚠️ React 19+ のみ。 React 18 以前を使用している場合はこのセクションをスキップしてください。

• react19-no-forwardref - forwardRef を使用しないこと。useContext() の代わりに use() を使用してください

使い方

詳しい説明とコード例については、個別のルールファイルをお読みください:

rules/architecture-avoid-boolean-props.md
rules/state-context-interface.md

各ルールファイルには以下が含まれています:

• なぜそれが重要なのかについての簡潔な説明
• 説明付きの誤ったコード例
• 説明付きの正しいコード例
• 追加のコンテキストと参考資料

完全なコンパイル済みドキュメント

すべてのルールを展開した完全なガイドについては: AGENTS.md

検証

• 変更がブラウザ/シミュレーターでレンダリングされ、スクリーンショットまたはDOM スナップショットが取得されたこと。コードレビューだけではないこと
• コンポジションパターンガイドで指定されているブレークポイント(最低限モバイル + デスクトップ)でレイアウトが確認されたこと。各ブレークポイントの証拠が添付されていること
• 使用されている色、タイポグラフィ、スペーシング値がプロジェクトのデザイントークン/テーマから取得されており、ハードコーディングされたアドホック値ではないこと
• すべてのインタラクティブ要素でキーボードナビゲーションとフォーカス順序が実行されたこと
• モーション削減/ダークモード(サポートされている場合)バリアントが検証されたこと。継承されたと仮定されていないこと
• 検証レンダリング中にコンソールエラーまたはハイドレーション警告が発生していないこと