tailwind-v4-shadcn

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

本番環境でテスト済み：WordPress Auditor (https://wordpress-auditor.webfonts.workers.dev) 最終更新日：2026-01-20 バージョン：[email protected], @tailwindcss/[email protected] ステータス：本番環境対応済み ✅

---

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

# 1. Install dependencies
pnpm add tailwindcss @tailwindcss/vite
pnpm add -D @types/node tw-animate-css
pnpm dlx shadcn@latest init

# 2. Delete v3 config if exists
rm tailwind.config.ts  # v4 doesn't use this file

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') } }
})

components.json（重要）：

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

---

4段階のアーキテクチャ（必須）

手順を省略すると、テーマが正しく動作しません。必ずこの順序どおりに進めてください。

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

/* src/index.css */
@import "tailwindcss";
@import "tw-animate-css";  /* Required for shadcn/ui animations */

: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() で囲みます。

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

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

理由：ユーティリティクラス（bg-background、text-primary）が生成されます。これを設定しないと、ユーティリティは存在しません。

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

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

重要：変数を直接参照してください。hsl(var(--background)) のように二重に囲まないでください。

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

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

---

ダークモードの設定

1. ThemeProvider を作成する（templates/theme-provider.tsx を参照）

2. App をラップする：

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

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

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

pnpm dlx shadcn@latest add dropdown-menu

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

---

重要なルール

✅ 必ず行うこと：

1. :root/.dark 内の色を hsl() で囲む：--bg: hsl(0 0% 100%);
2. すべての CSS 変数のマッピングに @theme inline を使用する
3. components.json で "tailwind.config": "" を設定する
4. tailwind.config.ts が存在する場合は削除する
5. @tailwindcss/vite プラグインを使用する（PostCSS は使用しない）

❌ 絶対に行わないこと：

1. :root/.dark を @layer base 内に配置する（カスケードの問題が発生します）
2. .dark { @theme { } } パターンを使用する（v4 はネストされた @theme をサポートしていません）
3. 色を二重に囲む：hsl(var(--background))
4. テーマに tailwind.config.ts を使用する（v4 はこれを無視します）
5. @apply ディレクティブを使用する（v4 では非推奨です。エラー #7 を参照）
6. セマンティックカラーに dark: バリアントを使用する（自動的に処理されます）
7. @layer base または @layer components のクラスに @apply を使用する（v4 の破壊的変更です。代わりに @utility を使用してください） | ソース
8. CSS レイヤーの順序を理解せずに、あらゆるスタイルを @layer base で囲む（エラー #8 を参照） | ソース

---

よくあるエラーと解決方法

このスキルは、記録されている8つのエラーを防ぎます。

1. ❌ tw-animate-css のインポートエラー

エラー：「Cannot find module 'tailwindcss-animate'」

原因：shadcn/ui は v4 で tailwindcss-animate を非推奨にしました。

解決方法：

# ✅ DO
pnpm add -D tw-animate-css

# Add to src/index.css:
@import "tailwindcss";
@import "tw-animate-css";

# ❌ DON'T
npm install tailwindcss-animate  # v3 only

---

2. ❌ 色が機能しない

エラー：bg-primary を適用してもスタイルが反映されない

原因：@theme inline のマッピングがありません

解決方法：

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

---

3. ❌ ダークモードが切り替わらない

エラー：テーマがライト／ダークのまま変わらない

原因：ThemeProvider がありません

解決方法：

1. ThemeProvider を作成する（templates/theme-provider.tsx を参照）
2. main.tsx でアプリをラップする
3. <html> 要素の .dark クラスが切り替わることを確認する

---

4. ❌ @layer base の重複

エラー：コンソールに「Duplicate @layer base」と表示される

原因：shadcn の init が @layer base を追加します。もう一つ追加しないでください。

解決方法：

/* ✅ Correct - single @layer base */
@import "tailwindcss";

:root { --background: hsl(0 0% 100%); }

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

@layer base { body { background-color: var(--background); } }

---

5. ❌ tailwind.config.ts が原因でビルドに失敗する

エラー：「Unexpected config file」

原因：v4 は tailwind.config.ts を使用しません（v3 のレガシー形式です）

解決方法：

rm tailwind.config.ts

v4 の設定は、@theme ディレクティブを使って src/index.css で行います。

---

6. ❌ マルチテーマ構成で @theme inline を使うとダークモードが機能しない

エラー：カスタムバリアント（例：data-mode="dark"）で @theme inline を使用すると、ダークモードに切り替わりません
出典：GitHub Discussion #18560

原因：@theme inline は、ビルド時に変数の値をユーティリティに埋め込みます。ダークモードへの切り替えで基になる CSS 変数が変更されても、ユーティリティは変数ではなくハードコードされた値を参照するため、更新されません。

発生する理由：

• @theme inline はビルド時に値をインライン化します：bg-primary → background-color: oklch(...)
• ダークモードで CSS 変数の値が上書きされても、ユーティリティにはすでに値が埋め込まれています
• CSS の詳細度の連鎖が崩れます

解決策：マルチテーマのシナリオでは、@theme（inline なし）を使用します。

/* ✅ CORRECT - Use @theme without inline */
@custom-variant dark (&:where([data-mode=dark], [data-mode=dark] *));

@theme {
  --color-text-primary: var(--color-slate-900);
  --color-bg-primary: var(--color-white);
}

@layer theme {
  [data-mode="dark"] {
    --color-text-primary: var(--color-white);
    --color-bg-primary: var(--color-slate-900);
  }
}

inline を使用する場合：

• 単一テーマ＋ダークモードの切り替え（shadcn/ui のデフォルトなど）✅
• 変更されない他の CSS 変数を参照する場合 ✅

inline を使用しない場合：

• マルチテーマシステム（data-theme="blue" | "green" など）❌
• ライト／ダーク以外の動的なテーマ切り替え ❌

メンテナーからのアドバイス（Adam Wathan）：

「v4 では、生成される実際の CSS がテーマ変数を参照するのが、より慣用的な書き方です。個人的には、inline を使わないとうまく動作しない場合に限って使用します。」

---

7. ❌ @layer base/components での @apply（v4 での破壊的変更）

エラー：Cannot apply unknown utility class: custom-button
出典：GitHub Discussion #17082

原因：v3 では、@layer base および @layer components で定義したクラスを @apply で使用できました。v4 では、アーキテクチャ上の破壊的変更が加えられています。

発生する理由：v4 はネイティブ CSS の @layer アットルールを「乗っ取る」ことをやめました。@apply で使用できるのは、@utility で定義したクラスのみです。

移行：

/* ❌ v3 pattern (worked) */
@layer components {
  .custom-button {
    @apply px-4 py-2 bg-blue-500;
  }
}

/* ✅ v4 pattern (required) */
@utility custom-button {
  @apply px-4 py-2 bg-blue-500;
}

/* OR use native CSS */
@layer base {
  .custom-button {
    padding: 1rem 0.5rem;
    background-color: theme(colors.blue.500);
  }
}

注：このスキルでは、すでに @apply の使用を推奨していません。このエラーは主に、v3 から移行するユーザー向けのものです。

---

8. ❌ @layer base で定義したスタイルが適用されない

エラー：@layer base で定義したスタイルが無視されているように見える
出典：GitHub Discussion #16002 | Discussion #18123

原因：v4 はネイティブ CSS レイヤーを使用します。レイヤーの順序が明示的に指定されていないと、CSS カスケードによってベーススタイルがユーティリティレイヤーに上書きされることがあります。

発生する理由：

• v3：Tailwind は @layer base/components/utilities を横取りし、独自に処理していました
• v4：ネイティブ CSS レイヤーを使用します。レイヤーを正しい順序でインポートしないと、優先順位が崩れます
• スタイルは適用されていますが、ユーティリティに上書きされています

解決策 1：レイヤーを明示的に定義します。

@import "tailwindcss/theme.css" layer(theme);
@import "tailwindcss/base.css" layer(base);
@import "tailwindcss/components.css" layer(components);
@import "tailwindcss/utilities.css" layer(utilities);

@layer base {
  body {
    background-color: var(--background);
  }
}

解決策 2（推奨）：@layer base を使わず、ルートレベルでスタイルを定義します。

@import "tailwindcss";

:root {
  --background: hsl(0 0% 100%);
}

body {
  background-color: var(--background); /* No @layer needed */
}

対象：色変数だけでなく、すべてのベーススタイルが対象です。CSS レイヤーの順序を理解している場合を除き、スタイルを @layer base で囲むのは避けてください。

---

クイックリファレンス

症状	原因	修正方法
bg-primary が機能しない	@theme inline がない	@theme inline ブロックを追加する
色がすべて黒または白になる	hsl() が二重に適用されている	hsl(var(--color)) ではなく var(--color) を使う
ダークモードに切り替わらない	ThemeProvider がない	アプリを <ThemeProvider> で囲む
ビルドに失敗する	tailwind.config.ts が存在する	ファイルを削除する
アニメーションのエラーが発生する	tailwindcss-animate を使用している	tw-animate-css をインストールする

---

Tailwind v4 の新機能

OKLCH カラースペース（2024年12月）

Tailwind v4.0 では、デフォルトのカラーパレット全体が、知覚的に均一なカラースペースである OKLCH に置き換えられました。 ソース：Tailwind v4.0 Release | OKLCH Migration Guide

OKLCH を使う理由：

• 知覚的な一貫性：HSL の「明度 50%」は色相によって見た目にばらつきがあり（同じ明度でも、黄色は青よりかなり明るく見えます）
• より優れたグラデーション：中間色が濁ることなく、滑らかに変化します
• より広い色域：最新のディスプレイで sRGB を超える色に対応します
• より鮮やかな色：これまでは sRGB の制限により使えなかった、目を引く高彩度の色を使えます

ブラウザーのサポート状況（2026年1月）：

• Chrome 111 以降、Firefox 113 以降、Safari 15.4 以降、Edge 111 以降
• 世界全体の対応率：93.1%

自動フォールバック：Tailwind は、古いブラウザー向けに sRGB のフォールバックを生成します。

.bg-blue-500 {
  background-color: #3b82f6; /* sRGB fallback */
  background-color: oklch(0.6 0.24 264); /* Modern browsers */
}

カスタムカラー：カスタムカラーを定義する場合、現在は OKLCH が推奨されています。

@theme {
  /* Modern approach (preferred) */
  --color-brand: oklch(0.7 0.15 250);

  /* Legacy approach (still works) */
  --color-brand: hsl(240 80% 60%);
}

移行：破壊的変更はありません。Tailwind がフォールバックを自動生成します。新しいプロジェクトでは、カスタムカラーに OKLCH 対応のツールを使用してください。

標準搭載機能（プラグイン不要）

コンテナークエリー（v4.0 から標準搭載）：

<div className="@container">
  <div className="@md:text-lg @lg:grid-cols-2">
    Content responds to container width, not viewport
  </div>
</div>

行数制限（v3.3 から標準搭載）：

<p className="line-clamp-3">Truncate to 3 lines with ellipsis...</p>
<p className="line-clamp-[8]">Arbitrary values supported</p>
<p className="line-clamp-(--teaser-lines)">CSS variable support</p>

削除されたプラグイン：

• @tailwindcss/container-queries - 現在は標準搭載です
• @tailwindcss/line-clamp - v3.3 から標準搭載です

---

Tailwind v4 のプラグイン

@plugin ディレクティブを使用してください（require() や @import は使用しません）。

タイポグラフィ（Markdown/CMS コンテンツ向け）：

pnpm add -D @tailwindcss/typography

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

<article class="prose dark:prose-invert">{{ content }}</article>

フォーム（クロスブラウザー対応のフォームスタイル）：

pnpm add -D @tailwindcss/forms

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

コンテナークエリー（標準搭載、プラグイン不要）：

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

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

/* ❌ WRONG - v3 syntax */
@import "@tailwindcss/typography";

/* ✅ CORRECT - v4 syntax */
@plugin "@tailwindcss/typography";

---

セットアップチェックリスト

• @tailwindcss/vite がインストールされている（postcss ではありません）
• vite.config.ts が tailwindcss() プラグインを使用している
• components.json に "config": "" が設定されている
• tailwind.config.ts が存在しない
• src/index.css が 4 ステップのパターンに従っている：
  • :root/.dark がルートレベルにある（@layer 内ではありません）
  • 色が hsl() でラップされている
  • @theme inline がすべての変数をマッピングしている
  • @layer base がラップされていない変数を使用している
• ThemeProvider がアプリをラップしている
• テーマの切り替えが機能する

---

ファイルテンプレート

templates/ ディレクトリで利用できます：

• index.css - すべての色変数を含む完全な CSS
• components.json - shadcn/ui v4 の設定
• vite.config.ts - Vite + Tailwind プラグイン
• theme-provider.tsx - ダークモードプロバイダー
• utils.ts - cn() ユーティリティ

---

v3 からの移行

完全なガイドは reference/migration-guide.md を参照してください。

主な変更点：

• tailwind.config.ts を削除する
• テーマを @theme inline を使って CSS に移す
• @tailwindcss/line-clamp を置き換える（現在は標準搭載：line-clamp-*）
• tailwindcss-animate を tw-animate-css に置き換える
• プラグインを更新する：require() → @plugin

移行時に注意すべきその他の点

自動移行ツールが失敗する場合があります

警告：@tailwindcss/upgrade ユーティリティでは、設定の移行に失敗することがよくあります。 ソース：Community Reports | GitHub Discussion #16642

よくある失敗例：

• Typography プラグインの設定
• 複雑なテーマ拡張
• カスタムプラグインの設定

推奨事項：自動移行に頼らないでください。代わりに、移行ガイドの手順に従って手動で移行してください。

デフォルトの要素スタイルの削除

Tailwind v4 では Preflight をよりミニマルにし、見出し、リスト、ボタンのデフォルトスタイルが削除されています。 出典：GitHub Discussion #16517 | Medium：移行時の問題

影響：

• すべての見出し（<h1> から <h6>）が同じサイズで表示されます
• リストからデフォルトのパディングがなくなります
• 既存プロジェクトで表示上の問題が発生します

解決策：

オプション 1：コンテンツページに @tailwindcss/typography を使用する：

pnpm add -D @tailwindcss/typography

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

<article className="prose dark:prose-invert">
  {/* All elements styled automatically */}
</article>

オプション 2：カスタムのベーススタイルを追加する：

@layer base {
  h1 { @apply text-4xl font-bold mb-4; }
  h2 { @apply text-3xl font-bold mb-3; }
  h3 { @apply text-2xl font-bold mb-2; }
  ul { @apply list-disc pl-6 mb-4; }
  ol { @apply list-decimal pl-6 mb-4; }
}

PostCSS セットアップの複雑さ

推奨：Vite プロジェクトでは PostCSS ではなく、@tailwindcss/vite プラグインを使用してください。 出典：Medium：移行時の問題 | GitHub Discussion #15764

Vite プラグインが優れている理由：

// ✅ Vite Plugin - One line, no PostCSS config
import tailwindcss from '@tailwindcss/vite'

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

// ❌ PostCSS - Multiple steps, plugin compatibility issues
// 1. Install @tailwindcss/postcss
// 2. Configure postcss.config.js
// 3. Manage plugin order
// 4. Debug plugin conflicts

報告されている PostCSS の問題：

• エラー：「PostCSS プラグインとして tailwindcss を直接使用しようとしているようです」
• 複数の PostCSS プラグインが必要です：postcss-import、postcss-advanced-variables、tailwindcss/nesting
• v4 の PostCSS プラグインは別パッケージです：@tailwindcss/postcss

公式ガイダンス：Vite プロジェクトには Vite プラグインが推奨されています。PostCSS はレガシーなセットアップや Vite 以外の環境向けです。

表示上の変更

リング幅のデフォルト値：3px から 1px に変更 出典：Medium：移行ガイド

• ring クラスが以前より細くなりました
• v3 と同じ見た目にするには ring-3 を使用してください

// v3: 3px ring
<button className="ring">Button</button>

// v4: 1px ring (thinner)
<button className="ring">Button</button>

// Match v3 appearance
<button className="ring-3">Button</button>

---

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

• architecture.md - 4 ステップパターンの詳細
• dark-mode.md - ダークモードの完全な実装
• common-gotchas.md - トラブルシューティングガイド
• migration-guide.md - v3 → v4 の移行

---

公式ドキュメント

• shadcn/ui Vite のセットアップ：https://ui.shadcn.com/docs/installation/vite
• shadcn/ui Tailwind v4：https://ui.shadcn.com/docs/tailwind-v4
• Tailwind v4 ドキュメント：https://tailwindcss.com/docs

---

最終更新日：2026-01-20 スキルバージョン：3.0.0 Tailwind v4：4.1.18（最新） 本番環境：WordPress Auditor (https://wordpress-auditor.webfonts.workers.dev)

変更履歴：

• v3.0.0 (2026-01-20)：大幅な調査更新 - TIER 1 のエラーを 3 件（#6-8）追加、コミュニティの調査結果（TIER 2）を含めて移行ガイドを拡充、OKLCH カラースペースのセクション、PostCSS の複雑さに関する警告、移行ツールの制限事項を追加
• v2.0.1 (2026-01-03)：本番環境での検証
• v2.0.0：エラーを 5 件記録して初回リリース