shadcn

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

shadcn/ui に関する 10 カテゴリ、58 のルールを、影響度順にまとめています。自動リファクタリングとコード生成の指針としてご活用ください。

スタックの前提条件

ルールは、現在の shadcn/ui を対象としています。Tailwind CSS v4（CSS ファースト、tailwind.config.* は不要、トークンは @theme inline に配置）、React 19（ref をプロパティとして使用、data-slot 属性）、統合された radix-ui パッケージ、OKLCH カラートークン、tw-animate-css、Field と React Hook Form の Controller を使ったフォーム、Bun（bunx --bun shadcn@latest ...）を想定しています。例では Radix をベースにしています（--base radix）。CLI では Base UI をベースにすることもできます（--base base）。その場合、トリガーでは asChild ではなく render プロパティを使います。Tailwind v3 のプロジェクトでは、既存の設定を維持し、まず shadcn のアップグレードガイドに従ってください。

セットアップモード

shadcn/ui のインストール、修復、移行（新規プロジェクト、既存プロジェクト、Tailwind v3 から v4 への移行）時に使用します。references/_setup-mode.md に従い、bunx --bun shadcn@latest init の手順を選択してから、Tailwind v4 の CSS ファースト構成（@theme inline、@custom-variant dark）、空の tailwind.config を設定した components.json、cn() ヘルパー、検証チェックリストを用意します。依頼されたセットアップのみを行い、既存のスタイル、設定、コンポーネントを上書きする前に確認してください。セットアップ後は、以下のルールに従ってください。

適用する場面

• プロジェクトへの 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 を設定します（v4 では tailwind.config を空にします）
• setup-path-aliases - components.json に合わせて TypeScript のパスエイリアスを設定します
• setup-cn-utility - コンポーネントを使う前に cn ユーティリティを作成します（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 を基盤となる要素に渡します（React 19 の 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 - @theme inline を使って CSS にデザイントークンを定義します
• style-consistent-spacing-scale - Tailwind の一貫したスペーシングスケールを使用します
• style-responsive-design-patterns - モバイルファーストのレスポンシブデザインを適用します
• style-dark-mode-support - CSS 変数でダークモードをサポートします

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

• form-use-react-hook-form-integration - Field と Controller で 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 - 状態を使用箇所の近くに保つ

使用方法

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

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

リファレンスファイル

ファイル	説明
references/_sections.md	カテゴリーの定義と順序
assets/templates/_template.md	新しいルールのテンプレート