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

本番環境テスト済み: WordPress Auditor (https://wordpress-auditor.webfonts.workers.dev) 最終更新: 2025-12-04 ステータス: 本番環境対応 ✅

目次

1. はじめに
2. クイックスタート
3. 4ステップアーキテクチャ
4. ダークモードセットアップ
5. 重要なルール
6. セマンティックカラートークン
7. 一般的な問題と修正方法
8. ファイルテンプレート
9. セットアップチェックリスト
10. 高度なトピック
11. 依存パッケージ
12. Tailwind v4 プラグイン
13. リファレンスドキュメント
14. リファレンス読み込みのタイミング

---

⚠️ はじめに（読んでください！）

AI エージェント向けの重要な事項: Claude Code がユーザーに Tailwind v4 のセットアップを支援する場合:

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

ユーザーアクション必須: Claude にこのスキルを最初に確認するように伝える！

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

なぜこれが重要なのか（実際の結果）

スキル有効化なし:

• ❌ セットアップ時間: ~5 分
• ❌ エラー: 2～3 個
• ❌ 手動修正: 2 コミット以上
• ❌ トークン使用量: ~65k
• ❌ ユーザーの信頼: デバッグが必要

スキル有効化あり:

• ✅ セットアップ時間: ~1 分
• ✅ エラー: 0 個
• ✅ 手動修正: 0 個
• ✅ トークン使用量: ~20k (70% 削減)
• ✅ ユーザーの信頼: 即座に成功

このスキルが防ぐ既知の問題

1. tw-animate-css インポートエラー (v4 で廃止)
2. @layer base ブロックの重複 (shadcn init が独自に追加)
3. テンプレート選択の誤り (vanilla TS vs React)
4. 初期化後のクリーンアップ不足 (互換性のない CSS ルール)
5. プラグイン構文の誤り (@import や require() を使用、@plugin ディレクティブは使用しない)

これらはすべてスキル有効化時に自動的に処理されます。

---

クイックスタート（5 分 - この順序で従ってください）

1. 依存パッケージをインストール

bun add tailwindcss @tailwindcss/vite
# または: npm install tailwindcss @tailwindcss/vite

bun add -d @types/node

# 注: shadcn init に pnpm を使用 (既知の Bun 互換性の問題)
# (bunx に「Script not found」と postinstall/msw の問題)
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": "",              // ← 重要: v4 では空
    "css": "src/index.css",
    "cssVariables": true
  }
}

4. tailwind.config.ts を削除

rm tailwind.config.ts  # v4 はこのファイルを使用しません

---

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

このパターンは必須 - ステップを省くとテーマが壊れます。

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

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

:root {
  --background: hsl(0 0% 100%);      /* ← hsl() ラッパーが必須 */
  --foreground: hsl(222.2 84% 4.9%);
  --primary: hsl(221.2 83.2% 53.3%);
  /* ... すべてのライトモード色 */
}

.dark {
  --background: hsl(222.2 84% 4.9%);
  --foreground: hsl(210 40% 98%);
  --primary: hsl(217.2 91.2% 59.8%);
  /* ... すべてのダークモード色 */
}

重要なルール:

• ✅ ルートレベルで定義 (@layer base 内ではない)
• ✅ すべてのカラー値に hsl() ラッパーを使用
• ✅ ダークモードに .dark を使用 (.dark { @theme { } } ではない)

ステップ 2: 変数を Tailwind ユーティリティにマップ

@theme inline {
  --color-background: var(--background);
  --color-foreground: var(--foreground);
  --color-primary: var(--primary);
  /* ... すべての CSS 変数をマップ */
}

なぜこれが必須:

• ユーティリティクラスを生成 (bg-background、text-primary)
• これなしでは、bg-primary などは存在しません

ステップ 3: ベーススタイルを適用

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

重要なルール:

• ✅ 変数を直接参照: var(--background)
• ❌ 二重ラッピングなし: hsl(var(--background))

ステップ 4: 結果 - 自動ダークモード

<div className="bg-background text-foreground">
  {/* dark: バリアントは不要 - テーマが自動的に切り替わります */}
</div>

---

ダークモードセットアップ

1. ThemeProvider を作成

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

// コピー元: 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%);  /* ✅ 正しい */
   

2. @theme inline を使用してすべての CSS 変数をマップ

   @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 内に配置

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

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

   /* 間違い - v4 はネストされた @theme をサポートしていません */
   .dark {
     @theme {
       --color-primary: hsl(...);
     }
   }
   

3. カラーを二重ラップ

   /* 間違い */
   body {
     background-color: hsl(var(--background));
   }
   

4. tailwind.config.ts でテーマ色を設定

   /* 間違い - v4 はこれを無視します */
   export default {
     theme: {
       extend: {
         colors: { primary: 'hsl(var(--primary))' }
       }
     }
   }
   

5. @apply ディレクティブを使用 (v4 で廃止)

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

   /* 間違い */
   <div className="bg-primary dark:bg-primary-dark" />
   
   /* 正しい */
   <div className="bg-primary" />
   

---

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

カラーには常にセマンティック名を使用してください:

:root {
  --destructive: hsl(0 84.2% 60.2%);        /* 赤 - エラー、重大 */
  --success: hsl(142.1 76.2% 36.3%);        /* 緑 - 成功状態 */
  --warning: hsl(38 92% 50%);               /* 黄 - 警告 */
  --info: hsl(221.2 83.2% 53.3%);           /* 青 - 情報、プライマリ */
}

使用方法:

<div className="bg-destructive text-destructive-foreground">重大</div>
<div className="bg-success text-success-foreground">成功</div>
<div className="bg-warning text-warning-foreground">警告</div>
<div className="bg-info text-info-foreground">情報</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 にパスエイリアスが設定されている
• components.json が存在し、"config": "" が設定されている
• tailwind.config.ts ファイルが存在しない
• src/index.css が v4 パターンに従っている:
  • :root と .dark がルートレベル (@layer 内ではない)
  • カラーが hsl() でラップされている
  • @theme inline がすべての変数をマップしている
  • @layer base がラップされていない変数を使用している
• ThemeProvider がインストールされ、アプリをラップしている
• ダークモードトグルコンポーネントが作成されている
• ブラウザでテーマ切り替えが機能することを確認

---

高度なトピック

references/advanced-usage.md を読み込んで、以下を含む高度なパターンを確認してください:

• カスタムカラー: デフォルトパレット以上のセマンティックカラーを追加
• v3 移行: 完全なガイドについては references/migration-guide.md を参照
• コンポーネントベストプラクティス: セマンティックトークン、cn() ユーティリティ、構成パターン

簡単な例:

:root { --brand: hsl(280 65% 60%); }
@theme inline { --color-brand: var(--brand); }

使用方法: <div className="bg-brand">ブランド</div>

詳細なパターンとコンポーネント構成の例については、references/advanced-usage.md を読み込んでください。

---

依存パッケージ

✅ これらをインストール

{
  "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.554.0",
    "react": "^19.2.0",
    "react-dom": "^19.2.0"
  },
  "devDependencies": {
    "@types/node": "^24.10.1",
    "@vitejs/plugin-react": "^5.1.1",
    "vite": "^7.2.4",
    "typescript": "~5.9.3"
  }
}

❌ これらは決してインストールしないでください (v4 で廃止)

# これらのパッケージはビルドエラーを引き起こします:
bun add tailwindcss-animate  # ❌ 廃止
# または: npm install tailwindcss-animate  # ❌ 廃止

bun add tw-animate-css      # ❌ 存在しません

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

---

Tailwind v4 プラグイン

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

簡単な例:

@import "tailwindcss";
@plugin "@tailwindcss/typography";
@plugin "@tailwindcss/forms";

一般的なエラー: ❌ 間違い: @import "@tailwindcss/typography" (機能しません) ✅ 正しい: @plugin "@tailwindcss/typography" (@plugin ディレクティブを使用)

組み込み機能: コンテナクエリはコアに含まれています (@tailwindcss/container-queries プラグインは不要)。

Typography プラグイン (prose クラス)、Forms プラグイン、インストールステップ、一般的なプラグインエラーなど、完全なドキュメントについては references/plugins-reference.md を読み込んでください。

---

リファレンスドキュメント

より深い理解については、以下を参照してください:

• common-gotchas.md - すべての問題が発生する方法 (と修正方法)
• dark-mode.md - 完全なダークモード実装
• migration-guide.md - ハードコードされたカラーを CSS 変数に移行
• plugins-reference.md - 公式 Tailwind v4 プラグイン (Typography、Forms)
• advanced-usage.md - カスタムカラーと高度なパターン

---

リファレンス読み込みのタイミング

ユーザーの特定のニーズに基づいてリファレンスファイルを読み込んでください:

references/common-gotchas.md を読み込むタイミング:

• ユーザーが「色が機能しない」または「bg-primary が存在しない」と報告している場合
• ダークモードが適切に切り替わらない場合
• Tailwind エラーでビルドが失敗する場合
• ユーザーが CSS/設定の問題に遭遇した場合
• テーマの問題をデバッグする場合

references/dark-mode.md を読み込むタイミング:

• ユーザーがダークモードを実装するよう要求している場合
• テーマ切り替えが機能していない場合
• ThemeProvider コンポーネントコードが必要な場合
• システムテーマ検出についての質問がある場合

references/migration-guide.md を読み込むタイミング:

• Tailwind v3 から v4 に移行する場合
• ユーザーがハードコードされたカラーを移行する必要がある場合
• v3 → v4 の変更についての質問がある場合
• 移行チェックリストが必要な場合

references/plugins-reference.md を読み込むタイミング:

• ユーザーが Typography プラグイン (prose クラス) を必要とする場合
• ユーザーが Forms プラグインを必要とする場合
• @plugin ディレクティブについての質問がある場合
• プラグインインストールエラーが発生した場合

references/advanced-usage.md を読み込むタイミング:

• ユーザーがデフォルト以上のカスタムカラーについて尋ねている場合
• 高度なコンポーネントパターンが必要な場合
• コンポーネントベストプラクティスについての質問がある場合
• コンポーネント構成についての質問がある場合

---

公式ドキュメント

• 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

---

セキュアなインストール

Tailwind と shadcn/ui パッケージをインストールする場合、サプライチェーンセキュリティのベストプラクティスに従ってください:

• ポストインストールスクリプトをブロック — npm config set ignore-scripts true (または Bun: デフォルトで無効)
• クールダウン期間 — コミュニティによる検証のため、新しいパッケージバージョンは 7 日間待機
• インストール前に監査 — socket package score npm <pkg> を実行するか、socket npm install <pkg> を使用してパッケージを確認

完全なセキュリティ設定 (Socket CLI 統合、クールダウンセットアップ、ロックファイル検証、CI 強制を含む) については、dependency-upgrade スキルを読み込んでください。

本番環境の例

このスキルは WordPress Auditor プロジェクトに基づいています:

• ライブ: https://wordpress-auditor.webfonts.workers.dev
• スタック: Vite + React 19 + Tailwind v4 + shadcn/ui + Cloudflare Workers
• ダークモード: フルシステム/ライト/ダーク対応
• バージョン: Tailwind v4.1.17 + shadcn/ui 最新 (2025 年 11 月)

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

---

質問がありますか? 問題がありますか?

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