tailwind-v4-shadcn

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

本番環境で検証済み：WordPress Auditor (https://wordpress-auditor.webfonts.workers.dev) 最終更新日：2025-11-09 ステータス：本番環境で利用可能 ✅

---

⚠️ 始める前に（必ずお読みください！）

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",
    "baseColor": "slate",      // Base color palette
    "cssVariables": true,
    "prefix": ""               // No prefix for utility classes
  }
}

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. @tailwindcss/vite プラグインを使用する（PostCSS ではありません）

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.17",
    "@tailwindcss/vite": "^4.1.17",
    "clsx": "^2.1.1",
    "tailwind-merge": "^3.3.1",
    "@radix-ui/react-*": "latest",
    "lucide-react": "^0.553.0",
    "react": "^19.2.0",
    "react-dom": "^19.2.0"
  },
  "devDependencies": {
    "@types/node": "^24.10.0",
    "@vitejs/plugin-react": "^5.1.0",
    "vite": "^7.2.2",
    "typescript": "~5.9.0",
    "tw-animate-css": "^1.4.0"
  }
}

アニメーションパッケージ（2025年11月更新）

shadcn/ui は、Tailwind v4 との互換性のため、tailwindcss-animate を非推奨とし、tw-animate-css を採用しました。

✅ インストールする（v4 互換）：

pnpm add -D tw-animate-css

次に、src/index.css に追加します。

@import "tailwindcss";
@import "tw-animate-css";

❌ インストールしない：

npm install tailwindcss-animate  # Deprecated - v3 only

理由：tw-animate-css は、アニメーション用の公式 v4 互換代替パッケージであり、shadcn/ui コンポーネントで必要です。

参考：https://ui.shadcn.com/docs/tailwind-v4

---

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 ユーティリティでフォーム要素をスタイリングできるようにする
• input、select、checkbox、radio のブラウザー間の不整合を修正する

注： 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 最新版（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