tailwind-v4

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

/* Generates: :root { --color-brand: oklch(...); } */
/* Usage: text-brand → color: var(--color-brand) */

注：@theme default を明示的に指定して、デフォルト以外の @theme 宣言で上書きできるテーマ値としてマークすることもできます。

inline

CSS 変数を使わずに値を直接インライン化します（パフォーマンスが向上します）：

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

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

reference

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

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

/* No :root variable, but utilities use fallback */
/* Usage: 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);  /* Bright blue */
--color-red-600: oklch(57.7% 0.245 27.325);   /* Vibrant red */
--color-zinc-900: oklch(21% 0.006 285.885);   /* Near-black gray */

CSS 変数の命名

Tailwind v4 では、ダブルハイフン形式の CSS 変数命名規則を使用します：

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

  /* Spacing: --spacing multiplier */
  --spacing: 0.25rem;  /* Base unit for spacing scale */

  /* Fonts: --font-{family} */
  --font-display: 'Inter Variable', system-ui, sans-serif;

  /* Breakpoints: --breakpoint-{size} */
  --breakpoint-lg: 64rem;

  /* Custom animations: --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"
  }
}

段階的な情報開示

• セットアップとインストール：Vite プラグインの設定、パッケージのセットアップ、TypeScript 設定については、references/setup.md を参照してください
• テーマとデザイントークン：@theme のモード、カラーパレット、カスタムフォント、アニメーションについては、references/theming.md を参照してください
• ダークモードの方法：メディアクエリ、クラスベース、属性ベースの方法については、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 も）のメジャーバージョンが v3 の PostCSS のみのツールチェーンではなく、4 であることを確認します。
3. テーマの定義元：新しいテーマトークンは CSS 内の @theme / @theme inline に定義します。v3 の tailwind.config.js の extend には定義しません。v3 の設定が引き続きテーマを制御している場合は、トークンの調整よりも統合設定の移行を優先してください。

選択ガイド

@theme inline と default の使い分け

@theme inline を使用する場合：

• パフォーマンスを向上させたい（CSS 変数によるオーバーヘッドがありません）
• 変更されない静的な色の値
• 複数の値を持つアニメーションのキーフレーム
• 値を直接インライン化する必要があるユーティリティ

@theme（default）を使用する場合：

• JavaScript を使った動的なテーマ設定
• カスタム CSS 内での CSS 変数の参照
• コンテキストに応じて変化する値
• デバッグを容易にしたい（DevTools で CSS 変数を確認できます）

@theme reference を使用する場合

@theme reference を使用する場合：

• CSS 変数によるオーバーヘッドなしでフォールバック値を指定する
• 変数が定義されていない場合でも機能させる値
• ユーティリティのサポートを維持しつつ :root の肥大化を抑える
• 直接値を置換するために inline と組み合わせる

よく使われるパターン

2 層の変数システム

デザイントークンにマッピングするセマンティック変数：

@theme {
  /* Design tokens (OKLCH colors) */
  --color-blue-600: oklch(54.6% 0.245 262.881);
  --color-slate-800: oklch(27.9% 0.041 260.031);

  /* Semantic mappings */
  --color-primary: var(--color-blue-600);
  --color-surface: var(--color-slate-800);
}

/* Usage: 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';
}

/* Usage: 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);
    }
  }
}

/* Usage: animate-beacon */