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

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

適用する場合

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

• プロジェクトで shadcn/ui をインストールおよび設定する
• 新しい shadcn/ui コンポーネントを作成またはプリミティブを合成する
• React Hook Form と Zod 検証を使用してフォームを実装する
• データテーブルを構築または大規模データセット表示を処理する
• テーマをカスタマイズまたはダークモードサポートを追加する
• コードをアクセシビリティ準拠について確認する

ルールカテゴリ（優先度別）

優先度	カテゴリ	インパクト	プレフィックス
1	CLI & プロジェクト設定	重大	setup-
2	コンポーネントアーキテクチャ	重大	arch-
3	アクセシビリティ保全	重大	ally-
4	スタイリング & テーミング	高	style-
5	フォームパターン	高	form-
6	データ表示	中程度-高	data-
7	レイアウト & ナビゲーション	中程度	layout-
8	コンポーネント合成	中程度	comp-
9	パフォーマンス最適化	中程度	perf-
10	ステート管理	低-中程度	state-

クイックリファレンス

1. CLI & プロジェクト設定（重大）

• 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. コンポーネントアーキテクチャ（重大）

• 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 - cn() ユーティリティを Tailwind クラスマージに使用
• 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	バージョンと参照情報