shadcn

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

shadcn/ui アプリケーション向けの最新ベストプラクティスガイドです。プリミティブ固有のガイダンスを適用する前に、チェックイン済みのコンポーネントが Radix UI と Base UI のどちらを使用しているか確認してください。現在の shadcn は両方をサポートしており（新規プロジェクトでは Base UI がデフォルトです）、それぞれコンポジション API が異なります。コンポーネントのインストールとアップグレードには、名前空間付きレジストリを解決する現在の CLI（v4）を使用します。

適用する場面

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

• 新しい 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 - 生成されたプリミティブのコンポジション API を使用します
• arch-current-cli-registry - コンポーネントのライフサイクルには現在の CLI（v4、レジストリ、MCP）を使用します
• arch-unified-radix-package - プリミティブは統合された radix-ui パッケージからインポートします
• 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 - CSS で Tailwind v4 のテーマトークンを定義します
• 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 - 状態を使用箇所の近くに配置する

使用方法

まず、プロジェクトのルートで実行します。

npx -y @pymodel/react-frontend-skills detect  # installed vs. targeted versions

上記のルールのうちタスクに該当するものについて、references/<rule-id>.md を読み、重要である理由と、誤ったコードと正しいコードを確認してください。