Tailwind CSS v4 ベストプラクティス

クイックリファレンス

Vite プラグインセットアップ:

// vite.config.ts
import tailwindcss from '@tailwindcss/vite';
import { defineConfig } from 'vite';

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

CSS エントリーポイント:

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

@theme インラインディレクティブ:

@theme inline {
  --color-primary: oklch(60% 0.24 262);
  --color-surface: oklch(98% 0.002 247);
}

v3 からの主な違い

機能	v3	v4
設定	tailwind.config.js	CSS の @theme
ビルドツール	PostCSS プラグイン	@tailwindcss/vite
カラー	rgb() / hsl()	oklch()（デフォルト）
テーマ拡張	JS の extend: {}	CSS 変数
ダークモード	darkMode 設定オプション	CSS バリアント

@theme ディレクティブモード

default（標準モード）

CSS 変数を生成し、他の場所で参照できます:

@theme {
  --color-brand: oklch(60% 0.24 262);
}

/* 生成: :root { --color-brand: oklch(...); } */
/* 使用: text-brand → color: var(--color-brand) */

注記: @theme default を明示的に使用して、デフォルト以外の @theme 宣言でオーバーライドできるテーマ値をマークすることもできます。

inline

パフォーマンス向上のため CSS 変数なしで値を直接インラインします:

@theme inline {
  --color-brand: oklch(60% 0.24 262);
}

/* 使用: text-brand → color: oklch(60% 0.24 262) */

reference

CSS 変数を出力せずにフォールバックとして値をインラインします:

@theme reference {
  --color-internal: oklch(50% 0.1 180);
}

/* :root 変数なし、ただしユーティリティはフォールバックを使用 */
/* 使用: bg-internal → background-color: var(--color-internal, oklch(50% 0.1 180)) */

OKLCH カラーフォーマット

OKLCH は知覚的に均一な色を提供し、色相全体で一貫性が向上します:

oklch(L% C H)

• L（明度）: 0%（黒）から 100%（白）
• C（色度）: 0（グレー）から約 0.4（ビビッド）
• H（色相）: 0-360 度（赤 → 黄 → 緑 → 青 → マゼンタ）

例:

--color-sky-500: oklch(68.5% 0.169 237.323);  /* 明るい青 */
--color-red-600: oklch(57.7% 0.245 27.325);   /* ビビッドな赤 */
--color-zinc-900: oklch(21% 0.006 285.885);   /* ほぼ黒のグレー */

CSS 変数命名規則

Tailwind v4 はダブルダッシュ CSS 変数命名規則を使用します:

@theme {
  /* カラー: --color-{name}-{shade} */
  --color-primary-500: oklch(60% 0.24 262);

  /* スペーシング: --spacing 乗数 */
  --spacing: 0.25rem;  /* スペーシングスケールの基本単位 */

  /* フォント: --font-{family} */
  --font-display: 'Inter Variable', system-ui, sans-serif;

  /* ブレークポイント: --breakpoint-{size} */
  --breakpoint-lg: 64rem;

  /* カスタムアニメーション: --animate-{name} */
  --animate-fade-in: fade-in 0.3s ease-out;
}

設定ファイル不要

Tailwind v4 は設定ファイルを排除します:

• tailwind.config.js なし - CSS の @theme を使用してください
• postcss.config.js なし - @tailwindcss/vite プラグインを使用してください
• TypeScript サポート - パス解決用に @types/node を追加してください

{
  "devDependencies": {
    "@tailwindcss/vite": "^4.0.0",
    "@types/node": "^22.0.0",
    "tailwindcss": "^4.0.0",
    "vite": "^6.0.0"
  }
}

プログレッシブディスクロージャー

• セットアップとインストール: references/setup.md を参照して、Vite プラグイン設定、パッケージセットアップ、TypeScript 設定を確認
• テーマ設計とデザイントークン: references/theming.md を参照して、@theme モード、カラーパレット、カスタムフォント、アニメーション を確認
• ダークモード戦略: references/dark-mode.md を参照して、メディアクエリ、クラスベース、属性ベースのアプローチを確認

ゲート（セットアップ検証）

@theme の選択肢、OKLCH トークン、または v4 ユーティリティを推奨する前に、プロジェクトが実際に v4 統合パスにあることを確認してください:

1. ビルドの配線: Vite 設定が @tailwindcss/vite から tailwindcss() をロードし、CSS エントリーが @import 'tailwindcss' を使用しています。失敗する場合は停止し、references/setup.md に従って配線を修正してください。
2. メジャーバージョン: package.json に tailwindcss（Vite 使用時は @tailwindcss/vite も）が メジャー 4 で記載されており、v3 PostCSS のみのツールチェーンではありません。
3. テーマソース: 新しいテーマトークンは CSS の @theme / @theme inline に存在し、tailwind.config.js の extend には ありません（v3）。v3 設定がまだテーマを駆動している場合、配線の移行はトークンの微調整より優先されます。

決定ガイド

@theme inline と default のどちらを使用するか

@theme inline を使用:

• パフォーマンス向上（CSS 変数オーバーヘッドなし）
• 変わらない静的な色値
• 複数の値を持つアニメーションキーフレーム
• 値を直接インラインする必要があるユーティリティ

@theme（デフォルト）を使用:

• JavaScript での動的テーマング
• カスタム CSS での CSS 変数参照
• コンテキストに基づいて変わる値
• より良いデバッグ（DevTools で CSS 変数を検査）

@theme reference を使用するタイミング

@theme reference を使用:

• CSS 変数オーバーヘッドなしフォールバック値を提供
• 変数が定義されていない場合でも機能する値
• :root の膨張を削減しながらユーティリティサポートを維持
• 直接値の置換のため inline と組み合わせ

一般的なパターン

2 段階変数システム

デザイントークンにマップされたセマンティック変数:

@theme {
  /* デザイントークン（OKLCH カラー） */
  --color-blue-600: oklch(54.6% 0.245 262.881);
  --color-slate-800: oklch(27.9% 0.041 260.031);

  /* セマンティックマッピング */
  --color-primary: var(--color-blue-600);
  --color-surface: var(--color-slate-800);
}

/* 使用: bg-primary, bg-surface */

カスタムフォント設定

@theme {
  --font-display: 'Inter Variable', system-ui, sans-serif;
  --font-mono: 'JetBrains Mono', ui-monospace, monospace;

  --font-display--font-variation-settings: 'wght' 400;
  --font-display--font-feature-settings: 'cv02', 'cv03', 'cv04';
}

/* 使用: font-display, font-mono */

アニメーションキーフレーム

@theme inline {
  --animate-beacon: beacon 2s ease-in-out infinite;

  @keyframes beacon {
    0%, 100% {
      opacity: 1;
      transform: scale(1);
    }
    50% {
      opacity: 0.5;
      transform: scale(1.05);
    }
  }
}

/* 使用: animate-beacon */