shadcn

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

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

適用するタイミング

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

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

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

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

クイックリファレンス

1. コンポーネントアーキテクチャ（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 - 基本スタイルとバリアント固有のスタイルを分離します

2. アクセシビリティの維持（CRITICAL）

• 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 の色コントラスト比を維持します

3. スタイリングとテーマ設定（HIGH）

• 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 変数でダークモードをサポートします

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

• 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 - 送信後にフォームの状態をリセットする

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

• 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 - 次の操作につながる空の状態を提供する

6. コンポーネントの合成（中）

• 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 - 柔軟なコンテンツにスロットパターンを使用する

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

• 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 - 検索やフィルターの入力をデバウンスする

8. 状態管理（低〜中）

• 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	バージョンと参照情報