components-build

Components.build 仕様

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

適用する場面

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

• 新しい 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. 型をエクスポートする - prop の型を利用者が使えるようにする
6. 両方の状態パターンをサポートする - 制御型と非制御型
7. インテリジェントなクラスのマージ - tailwind-merge と cn() ユーティリティを使用する

著者

共同執筆者：

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

AI スキルとしての適応：

• Jordan Gilliam (@nolansym)

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