コア原則

合成性と再利用性

継承より合成を優先してください — 深いクラス階層に頼るのではなく、組み合わせたり入れ子にしたりしてより複雑なUIを作れるコンポーネントを構築します。

合成可能なコンポーネントは明確なAPI（props/slots経由）を公開し、子要素やコールバックを差し込むことで開発者が振る舞いや外観をカスタマイズできるようにします。

これによりコンポーネントはさまざまなコンテキストで高い再利用性を持ちます。（Reactの設計はこれを強化しています： “Propsと合成により、コンポーネントの外観と振る舞いを明示的かつ安全にカスタマイズするために必要なすべての柔軟性が得られます。”）

デフォルトでアクセシブル

コンポーネントはすべてのユーザーが利用できるようにする必要があります。コンポーネントの役割に適したセマンティックなHTML要素を使用してください（例：クリック可能な操作には <button>、リストには <ul>/<li> など）および必要に応じてWAI-ARIA属性で補強します。

キーボード操作やフォーカス管理をサポートしていることを確認してください（例：メニュー内の矢印キーによるナビゲーション、モーダルのフォーカストラップなど）。各コンポーネントはデフォルトでアクセシビリティ基準とガイドラインに準拠しているべきです。

これは適切なARIAのロール／ステートを提供し、スクリーンリーダーでのテストを行うことを意味します。アクセシビリティはオプションではなく、すべてのコンポーネントにとっての基準機能です。

カスタマイズ性とテーマ対応

コンポーネントは異なるデザイン要件に合わせて簡単に再スタイルできるか適応できるべきです。上書きできない形で視覚スタイルをハードコーディングするのは避けてください。

CSS変数、明確にドキュメント化されたクラス名、あるいはstyle propsなどのテーマ付けやスタイリングの仕組みを提供してください。理想的には、コンポーネントは妥当なデフォルトスタイルを持ちながらも、開発者が最小限の手間で外観をカスタマイズできるようにします（例えば、classNameを渡す、あるいはdesign tokensを使うなど）。

この原則により、コンポーネントはデフォルトスタイルと「争う」ことなく、どんなブランドやデザインシステムにも馴染むことができます。

軽量かつ高パフォーマンス

コンポーネントはアセットや依存関係の面で可能な限り軽量であるべきです。大きなライブラリ依存や過度に複雑なロジックでコンポーネントを肥大化させるのは避けてください。特にそのロジックが常に必要でない場合は注意が必要です。

不要な再レンダリングを最小限に抑え、重いタスクには効率的なアルゴリズムを使うことで、レンダリングとインタラクションの両面で良好なパフォーマンスを目指してください。コンポーネントが大量のデータを扱う場合（大きなリストやテーブルなど）には、仮想化やインクリメンタルレンダリングのようなパターンを検討しますが、そうした機能はオプションとして保持してください。

軽量なコンポーネントは保守が容易であり、エンドユーザーにとっても高速です。

透明性とコードの所有権

オープンソースでは、利用者がコンポーネントのコードを完全に可視化し制御できることがしばしば利点になります。本仕様は「オープンソースファースト」の考え方を推奨します：コンポーネントをブラックボックスにしてはいけません。

開発者があなたのコンポーネントをインポートまたはコピーしたときに、その動作を検査し必要に応じて修正できるようにすべきです。この原則は、開発者がコンポーネントコードを直接プロジェクトに統合する「コピー＆ペースト」配布モデル（後で議論します）に基づいています。

ユーザーにコードの所有権を与えることで、信頼が高まり、より深いカスタマイズが可能になります。

たとえパッケージで配布する場合でも、ソースマップ、可読性の高いコード、そして充実したドキュメントを提供して透明性を追求してください。

十分に文書化され、DXに配慮した

優れたコンポーネントは単なるコードではなく、明確なドキュメントと例を備えています。開発者体験（DX）の観点から、あなたのコンポーネントは学習・統合が容易であるべきです。

各コンポーネントの目的、props、および使用例を文書化してください。キーボード制御や使用しているARIA属性などアクセシビリティに関する注記や、カスタマイズオプションについても含めてください。

良いドキュメントは誤用を減らし、採用の障壁を下げます。ドキュメントの期待事項については公開セクションで扱いますが、良いドキュメントとDXの計画は設計／構築フェーズの間に行うべきであるため、ここでも原則として挙げています。