shadcn

shadcn/ui コミュニティのベストプラクティス

shadcn/ui コミュニティが管理する、shadcn/ui アプリケーション向けの包括的なベストプラクティスガイドです。影響度に基づいて優先順位付けされた10カテゴリ、58のルールが含まれており、自動リファクタリングとコード生成を支援します。

適用するタイミング

次のような場合に、このガイドラインを参照してください。

• プロジェクトに shadcn/ui をインストールして設定するとき
• 新しい shadcn/ui コンポーネントを作成したり、プリミティブを組み合わせたりするとき
• React Hook Form と Zod のバリデーションを使ってフォームを実装するとき
• データテーブルを構築したり、大規模なデータセットの表示を処理したりするとき
• テーマをカスタマイズしたり、ダークモードのサポートを追加したりするとき
• アクセシビリティへの準拠を確認するためにコードをレビューするとき

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

優先度	カテゴリ	影響度	プレフィックス
1	CLI とプロジェクトのセットアップ	CRITICAL	setup-
2	コンポーネントアーキテクチャ	CRITICAL	arch-
3	アクセシビリティの維持	CRITICAL	ally-
4	スタイリングとテーマ設定	HIGH	style-
5	フォームのパターン	HIGH	form-
6	データ表示	MEDIUM-HIGH	data-
7	レイアウトとナビゲーション	MEDIUM	layout-
8	コンポーネントの合成	MEDIUM	comp-
9	パフォーマンスの最適化	MEDIUM	perf-
10	状態管理	LOW-MEDIUM	state-

クイックリファレンス

1. CLI とプロジェクトのセットアップ（CRITICAL）

• setup-components-json - コンポーネントを追加する前に components.json を設定します
• setup-path-aliases - components.json に合わせて TypeScript のパスエイリアスを設定します
• setup-cn-utility - コンポーネントを使用する前に cn ユーティリティを作成します
• setup-use-cli-not-copy - コピー＆ペーストではなく CLI を使ってコンポーネントを追加します
• setup-css-variables-theme - 一貫したテーマ設定のために CSS 変数を有効にします
• setup-rsc-configuration - フレームワークのサポート状況に応じて RSC フラグを設定します

2. コンポーネントアーキテクチャ（CRITICAL）

• arch-use-asChild-for-custom-triggers - カスタムのトリガー要素には asChild プロパティを使用します
• arch-preserve-radix-primitive-structure - Radix の複合コンポーネントの階層構造を維持します
• arch-extend-variants-with-cva - 型安全なバリアントには Class Variance Authority を使用します
• arch-use-cn-for-class-merging - Tailwind のクラスを安全にマージするには cn() ユーティリティを使用します
• arch-forward-refs-for-composable-components - フォームやフォーカスとの連携のために ref を転送します
• arch-isolate-component-variants - ベーススタイルとバリアント固有のスタイルを分離します

3. アクセシビリティの維持（重要）

• ally-preserve-aria-attributes - Radix の ARIA 属性をそのまま維持します
• ally-provide-sr-only-labels - アイコンボタンにスクリーンリーダー用のラベルを追加します
• ally-maintain-focus-management - モーダルのフォーカストラップを維持します
• ally-preserve-keyboard-navigation - WAI-ARIA のキーボード操作パターンを維持します
• ally-ensure-color-contrast - WCAG のカラーコントラスト比を維持します
• ally-dialog-title-required - スクリーンリーダー向けに、必ず DialogTitle を含めます
• ally-form-field-labels - ラベルをフォームコントロールに関連付けます
• ally-aria-invalid-errors - フォームのエラー状態には aria-invalid を使用します
• ally-checkbox-label-association - クリック可能な領域を広げるため、Checkbox を Label で囲みます
• ally-focus-visible-styles - キーボード操作用のフォーカス表示スタイルを維持します

4. スタイリングとテーマ設定（高）

• style-use-css-variables-for-theming - テーマカラーには CSS 変数を使用します
• style-avoid-important-overrides - スタイルの上書きに !important は使用しないでください
• style-use-tailwind-theme-extend - デザイントークンに合わせて Tailwind のテーマを拡張します
• style-consistent-spacing-scale - Tailwind のスペーシングスケールを一貫して使用します
• style-responsive-design-patterns - モバイルファーストのレスポンシブデザインを適用します
• style-dark-mode-support - CSS 変数を使ってダークモードに対応します

5. フォームのパターン（高）

• form-use-react-hook-form-integration - React Hook Form と連携します
• form-use-zod-for-schema-validation - 型安全なバリデーションには Zod を使用します
• form-show-validation-errors-correctly - 適切なタイミングでエラーを表示します
• form-handle-async-validation - 非同期バリデーションの呼び出しをデバウンスします
• form-reset-form-state-correctly - 送信後にフォームの状態をリセットします

6. データ表示（中〜高）

• data-use-tanstack-table-for-complex-tables - 並べ替えやフィルタリングには TanStack Table を使用します
• data-virtualize-large-lists - 100 件を超えるリストを仮想化します
• data-use-skeleton-loading-states - 読み込み状態には Skeleton を使用します
• data-paginate-server-side - 大規模なデータセットをサーバー側でページネーションします
• data-empty-states-with-guidance - 次の操作につながる案内を空の状態に表示します

7. レイアウトとナビゲーション（中）

• layout-sidebar-provider - レイアウトを SidebarProvider で囲みます
• layout-sidebar-collapsible - サイドバーの折りたたみ動作を設定します
• layout-sidebar-groups - グループを使ってサイドバーのナビゲーションを整理します
• layout-sheet-mobile-nav - モバイルのナビゲーションオーバーレイには Sheet を使用します
• layout-breadcrumb-navigation - 階層の深いナビゲーションにはパンくずリストを実装します

8. コンポーネントの組み合わせ（中）

• comp-compose-with-compound-components - 複合コンポーネントのパターンを使用する
• comp-use-drawer-for-mobile-modals - モバイルデバイスでは Drawer を使用する
• comp-combine-command-with-popover - Command で検索可能なセレクトを作成する
• comp-nest-dialogs-correctly - ネストされたダイアログのフォーカスを適切に管理する
• comp-create-reusable-form-fields - 再利用可能なフォームフィールドコンポーネントを抽出する
• comp-use-slot-pattern-for-flexibility - 柔軟なコンテンツのためにスロットパターンを使用する

9. パフォーマンスの最適化（中）

• perf-lazy-load-heavy-components - 50KB を超えるコンポーネントを遅延読み込みする
• perf-memoize-expensive-renders - リスト項目や処理コストの高いコンポーネントをメモ化する
• perf-optimize-icon-imports - Lucide アイコンを直接インポートする
• perf-avoid-unnecessary-rerenders-in-forms - フォームフィールドの監視を分離する
• perf-debounce-search-inputs - 検索やフィルターの入力にデバウンスを適用する

10. 状態管理（低〜中）

• state-prefer-uncontrolled-for-simple-inputs - シンプルなフォームでは非制御コンポーネントを使用する
• state-lift-state-to-appropriate-level - 状態を最も近い共通の祖先まで引き上げる
• state-use-controlled-dialog-state - プログラムからアクセスできるようにダイアログを制御する
• state-colocate-state-with-components - 状態を使用する場所の近くに置く

使用方法

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

• セクションの定義 - カテゴリーの構成と影響度
• ルールのテンプレート - 新しいルールを追加するためのテンプレート

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

すべてのルールを含む単一ファイルのリファレンスについては、AGENTS.md をご覧ください。

リファレンスファイル

ファイル	説明
AGENTS.md	すべてのルールを含む完全なコンパイル済みガイド
references/_sections.md	カテゴリーの定義と順序
assets/templates/_template.md	新しいルール用のテンプレート
metadata.json	バージョンとリファレンス情報