tailwind-v4-shadcn

Tailwind v4 + shadcn/ui の本番環境向けスタック

本番環境で検証済み：WordPress Auditor (https://wordpress-auditor.webfonts.workers.dev) 最終更新日：2025-10-29 ステータス：本番環境対応済み ✅

---

⚠️ 開始前にお読みください！

AI エージェントにとって重要：Tailwind v4 のセットアップをユーザーに支援する Claude Code の場合：

1. 会話の冒頭で、このスキルを使用していることを明示します
2. 一般的な知識ではなく、このスキルのパターンを参照します
3. reference/common-gotchas.md に記載されている既知の問題を防ぎます
4. 推測せず、不明な場合はスキルのドキュメントを確認します

ユーザーによる操作が必要です：最初にこのスキルを確認するよう Claude に伝えてください！

次のように伝えてください：「Tailwind v4 + shadcn/ui をセットアップします。最初に tailwind-v4-shadcn スキルを確認してください」

重要な理由（実際の結果）

スキルを有効にしない場合：

• ❌ セットアップ時間：約5分
• ❌ 発生するエラー：2～3件（tw-animate-css、重複した @layer base）
• ❌ 手動で必要な修正：2件以上のコミット
• ❌ トークン使用量：約65k
• ❌ ユーザーの安心感：デバッグが必要

スキルを有効にした場合：

• ✅ セットアップ時間：約1分
• ✅ 発生するエラー：0件
• ✅ 手動で必要な修正：0件
• ✅ トークン使用量：約20k（70%削減）
• ✅ ユーザーの安心感：すぐに成功

このスキルで防げる既知の問題

1. tw-animate-css のインポートエラー（v4 で非推奨）
2. 重複した @layer base ブロック（shadcn の初期化で追加される）
3. テンプレートの選択ミス（vanilla TS と React）
4. 初期化後のクリーンアップ漏れ（互換性のない CSS ルール）
5. プラグイン構文の誤り（@plugin ディレクティブではなく @import または require() を使用）

スキルが有効な場合、これらはすべて自動的に処理されます。

---

クイックスタート（5分 — 次の順序どおりに進めてください）

1. 依存関係をインストールする

pnpm add tailwindcss @tailwindcss/vite
pnpm add -D @types/node
pnpm dlx shadcn@latest init

2. Vite を設定する

// vite.config.ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import tailwindcss from '@tailwindcss/vite'
import path from 'path'

export default defineConfig({
  plugins: [react(), tailwindcss()],
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src')
    }
  }
})

3. components.json を更新する

{
  "tailwind": {
    "config": "",              // ← CRITICAL: Empty for v4
    "css": "src/index.css",
    "cssVariables": true
  }
}

4. tailwind.config.ts を削除する

rm tailwind.config.ts  # v4 doesn't use this file

---

4ステップのアーキテクチャ（重要）

このパターンは必須です。手順を省略すると、テーマが正しく動作しません。

ステップ 1：ルートレベルで CSS 変数を定義する

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

:root {
  --background: hsl(0 0% 100%);      /* ← hsl() wrapper required */
  --foreground: hsl(222.2 84% 4.9%);
  --primary: hsl(221.2 83.2% 53.3%);
  /* ... all light mode colors */
}

.dark {
  --background: hsl(222.2 84% 4.9%);
  --foreground: hsl(210 40% 98%);
  --primary: hsl(217.2 91.2% 59.8%);
  /* ... all dark mode colors */
}

重要なルール：

• ✅ ルートレベルで定義する（@layer base の内側ではなく）
• ✅ すべての色の値に hsl() を使用する
• ✅ ダークモードには .dark を使用する（.dark { @theme { } } ではなく）

ステップ 2：変数を Tailwind ユーティリティにマッピングする

@theme inline {
  --color-background: var(--background);
  --color-foreground: var(--foreground);
  --color-primary: var(--primary);
  /* ... map ALL CSS variables */
}

これが必要な理由：

• ユーティリティクラス（bg-background、text-primary）を生成します
• これを設定しないと、bg-primary などが使えません

ステップ 3：ベーススタイルを適用する

@layer base {
  body {
    background-color: var(--background);  /* NO hsl() here */
    color: var(--foreground);
  }
}

重要なルール：

• ✅ 変数を直接参照する：var(--background)
• ❌ 二重にラップしない：hsl(var(--background))

ステップ 4：結果 — ダークモードの自動適用

<div className="bg-background text-foreground">
  {/* No dark: variants needed - theme switches automatically */}
</div>

---

ダークモードの設定

1. ThemeProvider を作成する

完全な実装については reference/dark-mode.md を参照するか、次のテンプレートを使用してください：

// Copy from: templates/theme-provider.tsx

2. アプリをラップする

// src/main.tsx
import { ThemeProvider } from '@/components/theme-provider'

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <ThemeProvider defaultTheme="dark" storageKey="vite-ui-theme">
      <App />
    </ThemeProvider>
  </React.StrictMode>,
)

3. テーマ切り替えを追加する

pnpm dlx shadcn@latest add dropdown-menu

ModeToggle コンポーネントのコードについては reference/dark-mode.md を参照してください。

---

重要なルール（必ず守ってください）

✅ 必ず行うこと：

1. :root と .dark の色の値を hsl() でラップする

   --background: hsl(0 0% 100%);  /* ✅ Correct */
   

2. すべての CSS 変数のマッピングに @theme inline を使用する

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

3. components.json で "tailwind.config": "" を設定する

   { "tailwind": { "config": "" } }
   

4. tailwind.config.ts が存在する場合は削除する

5. PostCSS ではなく @tailwindcss/vite プラグインを使用する

6. 条件付きクラスには cn() を使用する

   import { cn } from "@/lib/utils"
   <div className={cn("base", isActive && "active")} />
   

❌ 絶対に行わないこと：

1. :root や .dark を @layer base の内側に置く

   /* WRONG */
   @layer base {
     :root { --background: hsl(...); }
   }
   

2. .dark { @theme { } } パターンを使用する

   /* WRONG - v4 doesn't support nested @theme */
   .dark {
     @theme {
       --color-primary: hsl(...);
     }
   }
   

3. 色を二重にラップする

   /* WRONG */
   body {
     background-color: hsl(var(--background));
   }
   

4. テーマカラーに tailwind.config.ts を使用する

   /* WRONG - v4 ignores this */
   export default {
     theme: {
       extend: {
         colors: { primary: 'hsl(var(--primary))' }
       }
     }
   }
   

5. @apply ディレクティブを使用する（v4 では非推奨）

6. セマンティックカラーに dark: バリアントを使用する

   /* WRONG */
   <div className="bg-primary dark:bg-primary-dark" />
   
   /* CORRECT */
   <div className="bg-primary" />
   

---

セマンティックカラートークン

色には常にセマンティックな名前を使用してください：

:root {
  --destructive: hsl(0 84.2% 60.2%);        /* Red - errors, critical */
  --success: hsl(142.1 76.2% 36.3%);        /* Green - success states */
  --warning: hsl(38 92% 50%);               /* Yellow - warnings */
  --info: hsl(221.2 83.2% 53.3%);           /* Blue - info, primary */
}

使用例：

<div className="bg-destructive text-destructive-foreground">Critical</div>
<div className="bg-success text-success-foreground">Success</div>
<div className="bg-warning text-warning-foreground">Warning</div>
<div className="bg-info text-info-foreground">Info</div>

---

よくある問題と簡単な解決方法

症状	原因	解決方法
bg-primary が機能しない	@theme inline のマッピングがない	@theme inline ブロックを追加します
色がすべて黒または白になる	hsl() による二重ラップ	hsl(var(--color)) ではなく var(--color) を使います
ダークモードに切り替わらない	ThemeProvider がない	アプリを <ThemeProvider> で囲みます
ビルドに失敗する	tailwind.config.ts が存在する	ファイルを削除します
テキストが見えない	コントラストの色が不適切	:root／.dark の色定義を確認します

トラブルシューティングの完全なガイドについては、reference/common-gotchas.md を参照してください。

---

ファイルテンプレート

すべてのテンプレートは templates/ ディレクトリにあります。

• index.css - すべての色変数を含む CSS の完全な設定
• components.json - shadcn/ui v4 の設定
• vite.config.ts - Vite + Tailwind プラグインの設定
• tsconfig.app.json - パスエイリアスを設定した TypeScript
• theme-provider.tsx - localStorage を使用するダークモードプロバイダー
• utils.ts - クラスをマージするための cn() ユーティリティ

これらのファイルをプロジェクトにコピーし、必要に応じてカスタマイズしてください。

---

セットアップの完全なチェックリスト

• Vite + React + TypeScript プロジェクトを作成済み
• @tailwindcss/vite をインストール済み（postcss ではありません）
• vite.config.ts で tailwindcss() プラグインを使用
• tsconfig.json にパスエイリアスを設定済み
• "config": "" を含む components.json が存在
• tailwind.config.ts ファイルが存在しない
• src/index.css が v4 のパターンに従っている：
  • :root と .dark がルートレベルにある（@layer 内ではない）
  • 色が hsl() でラップされている
  • @theme inline ですべての変数をマッピングしている
  • @layer base でラップされていない変数を使用している
• テーマプロバイダーをインストールし、アプリを囲んでいる
• ダークモード切り替えコンポーネントを作成済み
• ブラウザーでテーマの切り替えが機能することを確認済み

---

高度なトピック

カスタムカラー

新しいセマンティックカラーを追加します。

:root {
  --brand: hsl(280 65% 60%);
  --brand-foreground: hsl(0 0% 100%);
}

.dark {
  --brand: hsl(280 75% 70%);
  --brand-foreground: hsl(280 20% 10%);
}

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

使用例：<div className="bg-brand text-brand-foreground">Branded</div>

v3 からの移行

v3 → v4 の移行手順の完全版については、reference/migration-guide.md を参照してください。

コンポーネントのベストプラクティス

1. 常にセマンティックトークンを使用する

   <Button variant="destructive">Delete</Button>  /* ✅ */
   <Button className="bg-red-600">Delete</Button>  /* ❌ */
   

2. 条件付きスタイルには cn() を使用する

   import { cn } from "@/lib/utils"
   
   <div className={cn(
     "base-class",
     isActive && "active-class",
     hasError && "error-class"
   )} />
   

3. shadcn/ui コンポーネントを組み合わせる

   <Dialog>
     <DialogTrigger asChild>
       <Button>Open</Button>
     </DialogTrigger>
     <DialogContent>
       <DialogHeader>
         <DialogTitle>Title</DialogTitle>
       </DialogHeader>
     </DialogContent>
   </Dialog>
   

---

依存関係

✅ これらをインストールする

{
  "dependencies": {
    "tailwindcss": "^4.1.14",
    "@tailwindcss/vite": "^4.1.14",
    "clsx": "^2.1.1",
    "tailwind-merge": "^3.3.1",
    "@radix-ui/react-*": "latest",
    "lucide-react": "^0.545.0",
    "react": "^19.2.0",
    "react-dom": "^19.2.0"
  },
  "devDependencies": {
    "@types/node": "^24.0.0",
    "@vitejs/plugin-react": "^5.0.4",
    "vite": "^7.0.0",
    "typescript": "~5.9.0"
  }
}

❌ これらは絶対にインストールしない（v4 で非推奨）

# These packages will cause build errors:
npm install tailwindcss-animate  # ❌ Deprecated
npm install tw-animate-css      # ❌ Doesn't exist

これらのパッケージのインポートエラーが表示された場合は、該当パッケージを削除し、代わりにネイティブ CSS アニメーションまたは @tailwindcss/motion を使用してください。

---

Tailwind v4 プラグイン

Tailwind v4 は、CSS 内の @plugin ディレクティブを使った公式プラグインをサポートしています。

公式プラグイン（Tailwind Labs）

Typography プラグイン - Markdown／CMS コンテンツのスタイル設定

使用する場合： ブログ記事、ドキュメント、または Markdown／CMS の HTML を表示するとき。

インストール：

pnpm add -D @tailwindcss/typography

設定（v4 構文）：

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

使用方法：

<article class="prose lg:prose-xl dark:prose-invert">
  {{ markdown_content }}
</article>

利用可能なクラス：

• prose - 基本的なタイポグラフィスタイル
• prose-sm、prose-base、prose-lg、prose-xl、prose-2xl - サイズバリエーション
• dark:prose-invert - ダークモードのスタイル

---

Forms プラグイン - フォーム要素のスタイルをリセット

使用する場合： shadcn/ui コンポーネントを使わずにカスタムフォームを作成する場合、またはブラウザー間で一貫したフォームスタイルが必要な場合。

インストール：

pnpm add -D @tailwindcss/forms

設定（v4 構文）：

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

機能：

• ブラウザーのフォームのデフォルトスタイルをリセットします
• Tailwind ユーティリティでフォーム要素のスタイルを設定できるようにします
• 入力、選択、チェックボックス、ラジオボタンのブラウザー間の不一致を修正します

注： shadcn/ui のユーザーにとっては重要度が低いプラグインです（フォームコンポーネントにはあらかじめスタイルが設定されています）が、基本的なフォームには引き続き便利です。

---

よくあるプラグインのエラー

これらのエラーは、v4 プロジェクトで v3 構文を使用した場合に発生します。

❌ 誤り（v3 設定ファイルの構文）：

// tailwind.config.js
module.exports = {
  plugins: [require('@tailwindcss/typography')]
}

❌ 誤り（@plugin の代わりに @import を使用）：

@import "@tailwindcss/typography";  /* Doesn't work */

✅ 正しい（v4 の @plugin ディレクティブ）：

/* src/index.css */
@import "tailwindcss";
@plugin "@tailwindcss/typography";
@plugin "@tailwindcss/forms";

---

組み込み機能（プラグイン不要）

コンテナークエリーは Tailwind v4 のコアに組み込まれているため、プラグインは不要です。

<div className="@container">
  <div className="@md:text-lg">
    Responds to container width, not viewport
  </div>
</div>

❌ インストールしない： @tailwindcss/container-queries（非推奨。現在はコア機能です）

---

参考ドキュメント

詳しくは、以下をご覧ください。

• architecture.md - 4ステップパターンの詳細
• dark-mode.md - ダークモードの完全な実装
• common-gotchas.md - 発生する可能性のあるすべての問題と解決方法
• migration-guide.md - ハードコードされた色を CSS 変数に移行する方法

---

公式ドキュメント

• shadcn/ui Vite のセットアップ: https://ui.shadcn.com/docs/installation/vite
• shadcn/ui Tailwind v4 ガイド: https://ui.shadcn.com/docs/tailwind-v4
• shadcn/ui ダークモード（Vite）: https://ui.shadcn.com/docs/dark-mode/vite
• Tailwind v4 ドキュメント: https://tailwindcss.com/docs
• shadcn/ui のテーマ設定: https://ui.shadcn.com/docs/theming

---

本番環境での例

このスキルは、WordPress Auditor プロジェクトをもとにしています。

• 稼働中: https://wordpress-auditor.webfonts.workers.dev
• スタック: Vite + React 19 + Tailwind v4 + shadcn/ui + Cloudflare Workers
• ダークモード: システム／ライト／ダークを完全にサポート
• バージョン: Tailwind v4.1.14 + shadcn/ui latest（2025年10月）

このスキルのすべてのパターンは、本番環境で検証済みです。

---

質問や問題がありますか？

1. まず reference/common-gotchas.md を確認してください
2. 4ステップのアーキテクチャのすべての手順を確認してください
3. components.json に "config": "" が設定されていることを確認してください
4. tailwind.config.ts が存在する場合は削除してください
5. 公式ドキュメントを確認してください: https://ui.shadcn.com/docs/tailwind-v4