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のpropsとインターフェース | 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 Slotas-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 Authoritystyling-css-variables- CSS変数を用いた動的な値
12. デザイントークン
design-tokens-css-variables- CSS変数としてトークンを定義design-tokens-theming- ライト/ダークモードとテーマのサポート
13. ドキュメント
documentation-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つのHTML要素をラップする
- HTML属性の拡張 - 常にネイティブ要素のプロップを拡張する
- 型のエクスポート - プロップ型をコンシューマが利用できるようにする
- 両方の状態パターンをサポート - 制御と非制御
- インテリジェントなクラス結合 - tailwind-mergeを備えた
cn()ユーティリティを使用
著者
共著:
- Hayden Bleasel (@haydenbleasel)
- shadcn (@shadcn)
AIスキルとして翻案:
- Jordan Gilliam (@nolansym)
components.build仕様に基づく。