tailwind-v4-best-practices

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

デザインシステムの考え方、保守性、パフォーマンスを重視した、本番環境向けの Tailwind CSS v4 です。

基本原則

1. 直接色ではなく、デザイントークンを使う

Tailwind のデフォルトのカラーパレットではなく、セマンティックトークンを使用します。これにより、コンポーネントに手を加えずにテーマを切り替えられます。

<button class="bg-blue-500 text-white hover:bg-blue-600">
<span class="text-red-600">Error</span>


<button class="bg-primary text-primary-foreground hover:bg-primary-hover">
<span class="text-error">Error</span>

2. 任意の値より、セマンティックなユーティリティを使う

組み込みのスケールを使用します。任意の値は、本当に一度しか使わない場合に限って使用します。

<h1 class="text-[20px]">
<div class="p-[16px] gap-[24px]">


<h1 class="text-2xl">
<div class="p-4 gap-6">

3. 完全なクラス名のみを使う

Tailwind のコンパイラーは、ビルド時に完全なクラス名を必要とします。クラス名を動的に組み立てないでください。

// ❌ Tailwind can't detect these
<div className={`bg-${color}-500`}>

// ✅ Complete class names or CSS variables
<div className={color === 'blue' ? 'bg-blue-500' : 'bg-red-500'}>
<div className="bg-[var(--dynamic-color)]">

4. @apply を避ける

Tailwind v4 では @apply の使用が推奨されません。テンプレートでユーティリティクラスを直接使用するか、カスタムコンポーネントクラスが必要な場合は CSS で theme() を使用してください。

/* ❌ v3 pattern */
.button { @apply px-4 py-2 bg-blue-500 text-white rounded; }

/* ✅ v4 — use theme() if you need CSS */
.button {
  padding-inline: theme(spacing.4);
  background-color: theme(colors.primary);
}

@theme の設定

Tailwind v4 では、設定を JavaScript から CSS に移行しています。@theme を使ってデザイントークンを定義します。

@import "tailwindcss";

@theme {
  /* Semantic colors using OKLCH */
  --color-primary: oklch(0.55 0.25 250);
  --color-primary-hover: oklch(0.50 0.25 250);
  --color-primary-foreground: oklch(0.98 0 0);

  --color-error: oklch(0.60 0.22 25);
  --color-success: oklch(0.65 0.18 145);

  /* Surface colors */
  --color-background: oklch(1.0 0 0);
  --color-foreground: oklch(0.20 0.01 250);
  --color-surface: oklch(0.98 0.01 250);
  --color-border: oklch(0.90 0.01 250);

  /* Typography */
  --font-family-heading: "Inter", sans-serif;
  --font-family-body: "Inter", sans-serif;
  --font-family-mono: "Fira Code", monospace;
}

トークンアーキテクチャ全体（プリミティブ → セマンティック → コンポーネントのレイヤー）については、references/design-tokens.md を参照してください。

OKLCH カラー

Tailwind v4 では、知覚的な均一性を高めるため、デフォルトで OKLCH を使用します。

oklch(lightness chroma hue / alpha)

• 明度：0（黒）から 1（白）
• 彩度：0（灰色）から約 0.4（鮮やか）
• 色相：0〜360 度
• アルファ：0〜1（任意）

--color-brand: oklch(0.55 0.25 270);      /* vivid purple */
--color-subtle: oklch(0.96 0.02 250);     /* muted gray */
--color-overlay: oklch(0.0 0 0 / 0.5);   /* translucent black */

v3 から v4 へのクラス名の変更

v3                     →  v4
───────────────────────────────
bg-gradient-to-r       →  bg-linear-to-r
bg-gradient-to-br      →  bg-linear-to-br
flex-shrink-0          →  shrink-0
flex-grow              →  grow
decoration-clone       →  box-decoration-clone
decoration-slice       →  box-decoration-slice

自動アップグレードを実行します：npx @tailwindcss/upgrade

Vite のセットアップ（最速）

import tailwindcss from '@tailwindcss/vite'

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

v4 はコンテンツを自動検出するため、コンテンツパスを設定する必要はありません。本番環境では、未使用のユーティリティが自動的にツリーシェイクされます。

リファレンス

現在のタスクに必要なものだけを読み込みます。

リファレンス	読み込むタイミング
design-tokens.md	トークンアーキテクチャ、コンポーネントトークン、ステータスカラーのパターンを設定するとき
theming.md	ダークモード、実行時のテーマ切り替え、ブランドのバリエーション、ユーザー設定の検出
advanced-patterns.md	アニメーション、グリッドレイアウト、コンテナークエリー、カスタムユーティリティ、プラグイン、パフォーマンス
migration.md	Tailwind v3 から v4 にプロジェクトを移行するとき