components-build

Components.build 仕様

モダンで合成可能、かつアクセシブルな UI コンポーネントを構築するための包括的なガイドラインです。Hayden Bleasel と shadcn が共同執筆した、基本原則から配布までを網羅する 16 のルールカテゴリで構成されています。

適用する場面

以下の際に、これらのガイドラインを参照してください：

• 新しい React コンポーネントやコンポーネントライブラリを作成するとき
• コンポーネントの API やプロパティのインターフェースを設計するとき
• アクセシビリティ機能（キーボード、ARIA、フォーカス管理）を実装するとき
• 合成可能なコンポーネントアーキテクチャを構築するとき
• Tailwind CSS と CVA でコンポーネントをスタイリングするとき
• コンポーネントをレジストリや npm に公開するとき

優先度別のルールカテゴリ

優先度	カテゴリ	焦点	接頭辞
1	概要	仕様の範囲と目標	overview
2	原則	中核となる設計思想	principles
3	定義	共通用語	definitions
4	合成	複雑なコンポーネントの分割	composition
5	アクセシビリティ	キーボード、スクリーンリーダー、ARIA	accessibility
6	状態	制御あり／制御なしのパターン	state
7	型	TypeScript のプロパティとインターフェース	types
8	ポリモーフィズム	as プロパティによる要素の切り替え	polymorphism
9	As-Child	Radix Slot の合成パターン	as-child
10	データ属性	data-state と data-slot	data-attributes
11	スタイリング	Tailwind CSS、cn ユーティリティ、CVA	styling
12	デザイントークン	CSS 変数とテーマ設定	design-tokens
13	ドキュメント	コンポーネントのドキュメント	documentation
14	レジストリ	コンポーネントレジストリ	registry
15	NPM	npm への公開	npm
16	マーケットプレイス	コンポーネントマーケットプレイス	marketplaces

クイックリファレンス

1. 概要

• overview - 仕様の範囲、目標、思想

2. 原則

• principles - 合成可能性、アクセシビリティ、カスタマイズ性、透明性

3. 定義

• definitions - 共通用語（プリミティブ、複合、ヘッドレスなど）

4. 合成

• composition-root - 共有状態に Context を使用するルートコンポーネント
• composition-item - アイテムのラッパーコンポーネント
• composition-trigger - インタラクティブなトリガーコンポーネント
• composition-content - コンテンツ表示コンポーネント
• composition-export - 名前空間エクスポートパターン

5. アクセシビリティ

• accessibility-semantic-html - 適切な HTML 要素を使用する
• accessibility-keyboard - 完全なキーボードナビゲーションをサポートする
• accessibility-aria - 適切な ARIA ロール、状態、プロパティを使用する
• accessibility-focus - フォーカスを管理し、復元する
• accessibility-live-regions - スクリーンリーダーに通知する
• accessibility-contrast - 色のコントラスト要件

6. 状態

• state-uncontrolled - 内部状態の管理
• state-controlled - 外部への状態管理の委譲
• state-controllable - useControllableState で両方のパターンをサポートする

7. 型

• types-extend-html - ネイティブ HTML 属性を拡張する
• types-export - 利用者向けにプロパティの型をエクスポートする
• types-single-element - 1 つのコンポーネントで 1 つの要素をラップする

8. ポリモーフィズム

• polymorphism-as-prop - レンダリングする要素の型を変更する
• polymorphism-typescript - 型安全なポリモーフィックコンポーネント
• polymorphism-defaults - セマンティックな要素のデフォルト値

9. As-Child

• as-child-slot - プロパティのマージに Radix Slot を使用する
• as-child-composition - 子コンポーネントと合成する

10. データ属性

• data-attributes-state - 状態のスタイリングに data-state を使用する
• data-attributes-slot - サブコンポーネントの指定に data-slot を使用する

11. スタイリング

• styling-cn-utility - clsx と tailwind-merge を組み合わせる
• styling-order - ベース → バリアント → 条件付きスタイル → ユーザーによる上書き
• styling-cva - バリアントに Class Variance Authority を使用する
• styling-css-variables - CSS 変数で動的な値を設定する

12. デザイントークン

• design-tokens-css-variables - トークンを CSS 変数として定義する
• design-tokens-theming - ライト／ダークモードとテーマをサポートする

13. ドキュメント

• documentation-props - すべての props を JSDoc でドキュメント化する
• documentation-examples - 使用例を示す

14. レジストリ

• registry-structure - レジストリファイルの構造
• registry-schema - コンポーネントのメタデータスキーマ

15. NPM

• npm-package-json - パッケージの設定
• npm-exports - モジュールのエクスポート

16. マーケットプレイス

• marketplaces-distribution - コンポーネントの配布戦略

使用方法

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

rules/composition/SKILL.md
rules/accessibility/SKILL.md
rules/styling/SKILL.md

各ルールファイルには、次の内容が含まれています。

• 重要である理由の簡単な説明
• 説明付きの誤ったコード例
• 説明付きの正しいコード例
• ベストプラクティスとよくある落とし穴

完全版ドキュメント

すべてのルールを詳しく記載した完全版ガイドについては、AGENTS.md をご覧ください。

重要な原則

1. 設定よりコンポジション - コンポーネントを組み合わせ可能なサブコンポーネントに分割する
2. デフォルトでアクセシブルに - 後付けではなく、必須要件として扱う
3. 単一要素でラップする - 各コンポーネントは 1 つの HTML 要素をラップする
4. HTML 属性を拡張する - 常にネイティブ要素の props を拡張する
5. 型をエクスポートする - 利用者が props の型を使用できるようにする
6. 両方の状態パターンをサポートする - 制御ありと制御なしの両方に対応する
7. クラスをインテリジェントにマージする - tailwind-merge と cn() ユーティリティを使用する

著者

共同執筆者：

• Hayden Bleasel (@haydenbleasel)
• shadcn (@shadcn)

AI スキルとしての適応：

• Jordan Gilliam (@nolansym)

components.build の仕様に基づいています。