shadcn-v3

スキル：shadcn

対象範囲

• 対象：shadcn/ui のセットアップを使用する Tailwind v4、CSS 変数アーキテクチャ、ダークモード、テーマ設定、コンポーネントの合成パターン、アクセシビリティ、フォーム連携
• 対象外：Tailwind v3、PostCSS の設定

前提条件

• Tailwind CSS v4+
• shadcn/ui 最新版
• Next.js 16（このリポジトリ）；CSS ファーストの Tailwind v4 を使用し、Vite は使用しません
• React 18+ または Next.js 14+
• TypeScript 6+

原則

• CSS 変数を Tailwind トークンに対応付けるには @theme inline を使用します
• :root と .dark の色の値には hsl() ラッパーを使用します
• components.json で "tailwind.config": "" を設定します（v4 では空にします）
• tailwind.config.ts がある場合は削除します（v4 では CSS ベースの設定を使用します）
• Next アプリでは CSS ファーストの Tailwind v4 を使用します（@tailwindcss/vite は使用しません）
• 条件付きクラスには cn() ユーティリティを使用します
• セマンティックカラーはダークモードに自動で適応します（dark: バリアントは不要です）
• プラグインには @plugin ディレクティブを使用します（@import や require() は使用しません）
• 複雑なコンポーネントは、小さな shadcn プリミティブから合成します
• ラッパーパターンを使ってコンポーネントを拡張します（元のコンポーネントは変更しません）
• バリアントシステムには CVA（class-variance-authority）を使用します
• 親コンポーネントから ref を渡す必要がある場合にのみ forwardRef を使用します（React 19 ではデフォルトで不要です）
• Radix UI プリミティブを活用して、組み込みのアクセシビリティを利用します

制約事項

必須

• :root と .dark の色の値を hsl() で囲みます
• すべての CSS 変数の対応付けに @theme inline を使用します
• components.json で "tailwind.config": "" を設定します
• tailwind.config.ts がある場合は削除します
• Next アプリでは CSS ファーストの Tailwind v4 を使用します（CSS に @import "tailwindcss" を記述します）

推奨

• セマンティックカラーのトークン（--background、--foreground など）を使用します
• 条件付きクラスには cn() ユーティリティを使用します
• プラグインには @plugin ディレクティブを使用します
• 小さな shadcn プリミティブからコンポーネントを合成します
• ラッパーパターンを使ってコンポーネントを拡張します（元のコンポーネントは変更しません）
• カスタムコンポーネントのバリアントシステムには CVA を使用します
• 親コンポーネントから ref を渡す必要がある場合は forwardRef を使用します
• キーボード操作とスクリーンリーダーでアクセシビリティをテストします
• 複雑な操作（ダイアログ、ドロップダウンなど）には Radix UI プリミティブを使用します
• アイコンのみのボタンやインタラクティブ要素には ARIA ラベルを付けます
• @tailwindcss/vite はアプリが Vite ベースの場合にのみ使用します（Next.js では使用しません）

避けること

• :root や .dark を @layer base の中に置くこと
• .dark { @theme { } } パターンを使用すること（v4 はネストされた @theme をサポートしません）
• 色を二重にラップすること（body 内の hsl(var(--background)) など）
• テーマカラーに tailwind.config.ts を使用すること
• @apply ディレクティブを使用すること（v4 では非推奨です）
• セマンティックカラーに dark: バリアントを使用すること
• プラグインに @import や require() を使用すること（@plugin を使用します）
• shadcn の基本コンポーネントを直接変更すること（ラッパーパターンを使用します）
• ドロップダウンやダイアログを一から独自に作成すること（Radix プリミティブを使用します）
• 状態の表示を色だけに頼ること
• アクセシビリティテストを省略すること

連携

• App Router のセットアップには next を使用します
• 型安全性には typescript を使用します

パターン

CSS 変数のセットアップ

/* src/index.css */
@import "tailwindcss";

@theme inline {
  --color-background: var(--background);
  --color-foreground: var(--foreground);
}

:root {
  --background: hsl(0 0% 100%);
  --foreground: hsl(222.2 84% 4.9%);
}

.dark {
  --background: hsl(222.2 84% 4.9%);
  --foreground: hsl(210 40% 98%);
}

Vite の設定（Vite アプリのみ）

// vite.config.ts — skip for Next.js CSS-first setups
import tailwindcss from '@tailwindcss/vite'

export default defineConfig({
  plugins: [react(), tailwindcss()],
})

コンポーネント設定

{
  "tailwind": {
    "config": "",
    "css": "src/index.css",
    "baseColor": "slate",
    "cssVariables": true
  }
}

完全なセットアップについては、テンプレート（コンポーネントの拡張を含む）とアーキテクチャを参照してください。

参考資料

• アーキテクチャ - セットアップパターンの全体
• ダークモード - ダークモードの実装
• よくある落とし穴 - よくある問題と解決方法
• 移行ガイド - v3 からの移行
• コンポーネントパターン - 合成、CVA、拡張パターン
• アクセシビリティ - ARIA、キーボード操作、スクリーンリーダー
• フォームパターン - React Hook Form との連携

Resources

• shadcn/ui Tailwind v4 Guide
• Tailwind v4 Docs