tailwind-v4

Tailwind CSS v4

まずバージョンを確認する

ここが最も重要なステップです。v3 と v4 では設定方法がまったく異なり、一方に対するガイダンスはもう一方では明確に誤りです。

# Check the installed major version
npm ls tailwindcss --depth=0 2>/dev/null || grep '"tailwindcss"' package.json

判別の手がかり	バージョン
CSS 内の @import "tailwindcss";	v4
@tailwind base; @tailwind components; @tailwind utilities;	v3
CSS 内の @theme { } ブロック	v4
content: [...] 配列を含む tailwind.config.js	v3（または互換レイヤーを使用する v4 プロジェクト）
@config "./tailwind.config.js";	レガシー設定を読み込む v4
@tailwindcss/postcss または @tailwindcss/vite の依存関係	v4
postcss 設定で autoprefixer と postcss-import が必要	v3

v4 プロジェクトでは、デフォルトで tailwind.config.js を作成しないでください。 v4 は CSS から設定を読み込みます。手動で追加した設定ファイルは、@config で明示的に読み込まない限り、暗黙のうちに無視されます。

v4 のセットアップ

/* app.css — the single entry point */
@import "tailwindcss";

この1行で3つの @tailwind ディレクティブを置き換えられます。また、postcss-import と autoprefixer の処理も内部で行うため、PostCSS の設定から両方を削除してください。

Vite：

// vite.config.js
import tailwindcss from "@tailwindcss/vite";
export default { plugins: [tailwindcss()] };

PostCSS：

// postcss.config.mjs
export default { plugins: { "@tailwindcss/postcss": {} } };

設定は CSS ファースト

デザイントークンは @theme に記述します。各エントリーは対応するユーティリティを生成し、実際の CSS カスタムプロパティとしても公開します。

@import "tailwindcss";

@theme {
  --color-brand: oklch(0.62 0.19 250);
  --color-brand-muted: oklch(0.72 0.08 250);
  --font-display: "IBM Plex Sans", sans-serif;
  --radius-card: 14px;
  --spacing-gutter: 2.75rem;
  --ease-out-soft: cubic-bezier(0.22, 0.61, 0.36, 1);
}

--color-brand は bg-brand、text-brand、border-brand などを生成し、どこからでも var(--color-brand) として参照できます。この二面性こそが v4 の主な利点です。トークンが JavaScript 設定の中に閉じ込められることはなくなりました。

名前空間はユーティリティのファミリーに対応しています。--color-*、--font-*、--text-*、--spacing-*、--radius-*、--shadow-*、--ease-*、--animate-*、--breakpoint-* です。

名前空間全体、またはすべてを上書きできます。

@theme {
  --color-*: initial;          /* drop the default palette */
  --color-ink: #18181b;
}

content 配列は不要です。 v4 は .gitignore を尊重し、バイナリをスキップしながら、ソースファイルを自動的に検出します。必要な場合にのみ、追加のソースを指定してください。

@source "../packages/ui/src";           /* add a path outside the project root */
@source not "../legacy";                 /* exclude */
@source inline("bg-red-500 bg-red-600"); /* the v4 replacement for safelist */

v3 から v4 への移行

まず codemod を実行し、その後差分を確認してください。

npx @tailwindcss/upgrade

気づかないうちに問題を起こす名前変更：

v3	v4
shadow-sm	shadow-xs
shadow	shadow-sm
rounded-sm	rounded-xs
rounded	rounded-sm
blur-sm	blur-xs
outline-none	outline-hidden
bg-opacity-50	bg-black/50（スラッシュ形式の不透明度のみ）
flex-shrink-0	shrink-0

shadow → shadow-sm と rounded → rounded-sm の変更は特に危険です。以前のクラス名は引き続き使えますが、意味が1段階小さくなります。そのため、エラーになるのではなく、v3 のコードベース全体で影の深さと角丸が気づかないうちに1段階ずつ小さくなります。

ほかにも、次のような動作の変更があります。

• デフォルトのボーダー色は gray-200 ではなく currentColor になりました。border だけではテキストの色を引き継ぐため、色を明示的に指定してください。
• デフォルトのリングは、以前の 3px の青色ではなく 1px currentColor になりました。v3 のサイズを維持するには、ring を ring-3 に変更してください。
• Space-between では異なるセレクターが使われるため、兄弟要素のマージンに関する一部のケースで見た目が変わることがあります。
• ホバーは、デバイスが実際にホバーに対応している場合にのみ適用されます。
• バリアントの重ね合わせは、左から右へ読むようになりました。

動的なクラス名

スキャナーが引き続きソーステキストを静的に読み取るため、v3 からのルールは変わりません。

// BROKEN — never generated
<div className={`text-${color}-500`} />

// CORRECT — complete class names, statically visible
const TONE = {
  danger: "text-red-500",
  success: "text-emerald-500",
};
<div className={TONE[tone]} />

v4 では、設定なしで多くのユーティリティに動的な値を指定できます。grid-cols-15、w-17、mt-23 などを自由に使えます。ただし、組み立てられないのはクラス名の文字列です。実行時にしかわからない値を使う場合は、文字列連結ではなくインラインスタイルか CSS 変数を使用してください。

<div className="w-(--w)" style={{ "--w": `${pct}%` }} />

実用的なパターン

ダークモード。 v4 はデフォルトで prefers-color-scheme を使用します。クラスベースで切り替えるには、次のようにします。

@custom-variant dark (&:where(.dark, .dark *));

コンポーネントを切り出す順序。 @apply より、実際のコンポーネントを優先してください。CSS を共有する必要がある場合は、v4 では @utility を使用します。

@utility card {
  border-radius: var(--radius-card);
  background: var(--color-surface);
}

@apply を多用すると、ユーティリティを使う利点が失われ、CSS が肥大化します。最初に使うのではなく、最後の手段として使用してください。

任意の値は、単発の用途で引き続き使用できます。top-[117px]、bg-[oklch(0.7_0.1_200)]、grid-cols-[1fr_auto] などです。

よくある問題

• クラスが生成されない → クラス名が動的に構築されているか、ソースファイルが自動検出の対象外です（@source を追加してください）。
• tailwind.config.js の設定が反映されない → @config を指定していない v4 プロジェクトです。
• アップグレード後にビルドエラーが発生する → PostCSS のチェーンに postcss-import／autoprefixer が残っています。v4 には両方が含まれています。
• 移行後にボーダーやリングの見た目がおかしい → 上記の currentColor と ring-1 のデフォルト変更が原因です。
• 移行後に奥行き感がわずかに損なわれる → shadow／rounded の名称変更によるものです。

関連スキル

• visual-style-presets — スタイルの方向性を選び、@theme にトークンを設定します
• beautiful-shadows — 任意のユーティリティとして、正確なレイヤー状のシャドウを指定します