結論から言うと、Tailwind CSS v3 から v4 への移行は、公式ツール npx @tailwindcss/upgrade を使えば大半が自動で終わります。
ただし「クラス名は同じなのに見た目が変わる」タイプの破壊的変更がいくつかあり、ここを知らないまま移行すると、影やボーダーが微妙に崩れた画面をそのまま本番に出すことになります。
この記事では、v4 で何が変わったのかを最初の3分で押さえたうえで、移行手順と「実際にハマる破壊的変更10個」を、対応表とコピペで直せるコード付きで解説します。内容は2026年7月時点の公式アップグレードガイドに基づいています。
Tailwind CSS v4は何が変わったのか
v4 はフレームワークをゼロから書き直したメジャーバージョンで、方向性はシンプルに「速く・設定レスに・モダンCSS前提に」の3つです。
- エンジンを刷新し、フルビルドは最大5倍、差分ビルドは100倍以上高速（マイクロ秒単位）
- 設定が CSS ファーストに。tailwind.config.js の代わりに CSS 内の @theme でデザイントークンを定義
- セットアップは CSS に @import "tailwindcss" を1行書くだけ。content のパス指定も不要（テンプレートを自動検出）
- cascade layers・@property・color-mix() などモダンCSS機能の上に構築
その代わり、対応ブラウザは Safari 16.4+ / Chrome 111+ / Firefox 128+ が最低ラインになりました。これより古いブラウザのサポートが必要なプロジェクトは、v3.4 に留まるのが公式の推奨です。
移行手順は基本これだけ
Node.js 20 以上の環境で、公式のアップグレードツールを実行します。依存パッケージの更新、テンプレート内のクラス名の書き換え、設定ファイルの CSS への移行までを自動でやってくれます。
# 新しいブランチで実行し、差分を確認してからマージするのが公式推奨
npx @tailwindcss/upgradeプラグインの入れ替え
v4 では PostCSS プラグインが @tailwindcss/postcss パッケージに分離されました。postcss-import と autoprefixer は本体に取り込まれたため不要になります。
// postcss.config.mjs（v4）
export default {
plugins: {
"@tailwindcss/postcss": {},
},
};Vite を使っているなら、PostCSS 経由ではなく専用プラグインに乗り換えるほうが高速です。
// vite.config.ts
import { defineConfig } from "vite";
import tailwindcss from "@tailwindcss/vite";
export default defineConfig({
plugins: [tailwindcss()],
});@tailwindディレクティブは1行のインポートへ
/* v3 */
@tailwind base;
@tailwind components;
@tailwind utilities;
/* v4 */
@import "tailwindcss";画面が崩れる破壊的変更10選
ここからが本題です。アップグレードツールが直してくれるものも多いですが、「なぜ変わったのか」を知らないとレビューで差分の意味が分からず、手書きの新規コードで古い書き方に戻してしまいます。
① shadow・rounded・blurのスケールが1段ずれた
命名の一貫性のため、無印と -sm のあたりが1段リネームされました。v3 の shadow-sm を v4 でそのまま使うと「v3 の shadow」相当の濃い影になる、という順ずれが起きます。
- shadow-sm → shadow-xs ／ shadow → shadow-sm
- rounded-sm → rounded-xs ／ rounded → rounded-sm
- blur-sm → blur-xs ／ blur → blur-sm（backdrop-blur・drop-shadow も同様）
② *-opacity-* ユーティリティが削除された
bg-opacity-50 や text-opacity-* は削除され、スラッシュ記法に一本化されました。
<!-- v3 -->
<div class="bg-black bg-opacity-50"></div>
<!-- v4 -->
<div class="bg-black/50"></div>③ ringはデフォルト3px→1px、色もcurrentColorに
ring だけ書いたときの太さが 3px から 1px に、デフォルト色も blue-500 から currentColor に変わりました。フォーカスリングが急に細く・青くなくなったら原因はこれです。
<!-- v3 -->
<button class="focus:ring">保存</button>
<!-- v4: v3 と同じ見た目にするなら太さと色を明示する -->
<button class="focus:ring-3 focus:ring-blue-500">保存</button>プロジェクト全体で v3 の挙動に寄せたい場合は、テーマ変数で上書きできます。
@theme {
--default-ring-width: 3px;
--default-ring-color: var(--color-blue-500);
}④ borderのデフォルト色がgray-200→currentColorに
border と書いたときの色が gray-200 から currentColor（そのテキスト色）に変わりました。色を指定していない border が全部濃くなる、移行後に一番目につく変化です。border border-gray-200 のように色を明示しましょう。
⑤ outline-noneはoutline-hiddenへ
outline 単体がデフォルトで outline-width: 1px を出すようになり、従来の outline-none は outline-hidden にリネームされました（forced-colors モードでのアクセシビリティを保つための変更です）。
本当に outline を消したい場合だけ新しい outline-none を使います。
⑥ space-y・divideの実装セレクタが変わった
パフォーマンスのため、space-y-* の実装が「次兄弟に margin-top」から「最後以外に margin-bottom」へ変わりました。
インライン要素との組み合わせや、子側で margin を上書きしていたレイアウトはずれる可能性があります。公式も、要素間の間隔は flex / grid の gap への移行を推奨しています。
/* v3 */
.space-y-4 > :not([hidden]) ~ :not([hidden]) {
margin-top: 1rem;
}
/* v4 */
.space-y-4 > :not(:last-child) {
margin-bottom: 1rem;
}⑦ !importantの「!」はクラス名の末尾に
<!-- v3 -->
<div class="!flex !bg-red-500"></div>
<!-- v4 -->
<div class="flex! bg-red-500!"></div>⑧ 任意値のCSS変数は丸括弧、グリッドのカンマはアンダースコアに
任意値（arbitrary value）まわりの構文が2つ変わりました。CSS 変数を参照するときは角括弧ではなく丸括弧、grid-cols などの複数値はカンマではなくアンダースコア区切りです。
<!-- v3 -->
<div class="bg-[--brand-color] grid-cols-[max-content,auto]"></div>
<!-- v4 -->
<div class="bg-(--brand-color) grid-cols-[max-content_auto]"></div>⑨ hover:がタッチデバイスで発火しなくなった
v4 の hover: は @media (hover: hover) の中に生成されるため、タッチ操作では適用されません。「タップでホバー状態にする」挙動に依存していた UI は要注意です。どうしても v3 の挙動に戻すなら、カスタムバリアントで上書きできます。
@custom-variant hover (&:hover);⑩ Vue/Svelteのstyleブロックで@applyがそのまま動かない
v4 では、別ファイルとして処理される <style> ブロックや CSS Modules からは、メインCSSのテーマ変数やカスタムユーティリティが見えません。@apply を使うならメインCSSを @reference で参照します。
なお、Sass・Less・Stylus との併用は v4 では非対応になりました。
<template>
<h1>Hello world!</h1>
</template>
<style>
@reference "../../app.css";
h1 {
@apply text-2xl font-bold text-red-500;
}
</style>ただし公式は、@apply よりも CSS 変数を直接使うほう（例: color: var(--text-red-500);）を推奨しています。こちらはビルドも速くなります。
設定はtailwind.config.jsからCSSの@themeへ
v4 の思想を一番象徴するのがここです。デザイントークンは CSS 変数として @theme に書き、そのままユーティリティクラスを生成します。
@import "tailwindcss";
@theme {
--font-display: "Satoshi", "sans-serif";
--breakpoint-3xl: 120rem;
--color-avocado-100: oklch(0.99 0 0);
--color-avocado-200: oklch(0.98 0.04 113.22);
}既存の JavaScript 設定を段階的に残したい場合は @config "../../tailwind.config.js"; で明示的に読み込めます（v3 のような自動検出はされません。
corePlugins / safelist / separator は非対応）。また、カスタムユーティリティは @layer utilities ではなく @utility ディレクティブで定義するのが v4 流です。
@utility tab-4 {
tab-size: 4;
}v4はまだ進化中（2026年の動き）
v4 は 2025 年初頭の GA 後もマイナーバージョンで機能追加が続いています。
2026 年 2 月の v4.2 では webpack 用の公式プラグイン（@tailwindcss/webpack）、mauve・olive・mist・taupe の4色のデフォルトパレット追加、論理プロパティ系ユーティリティの拡充が入りました。
続く v4.3 ではスクロールバーのスタイリングが公式ユーティリティになるなど、v3 時代にプラグインで補っていた領域が本体に取り込まれつつあります。
モダンCSS機能そのものに興味がある方は、こちらの記事も合わせてどうぞ。
JavaScriptを消せるモダンCSS新機能7選【2026】昨日まで JavaScript で書いていた「親要素の判定」「入力欄の自動リサイズ」「出現アニメ」「スクロール連動」——2026年のモダンCSSなら、その大半がCSSだけで完結します。実際に動く7つの新機能を、コピペできるコード付きで一気に紹介します。frontendlab.magicgifted.com
まとめ
- 移行は npx @tailwindcss/upgrade（Node 20+）でほぼ自動。新ブランチで実行して差分レビューする
- 対応ブラウザは Safari 16.4+ / Chrome 111+ / Firefox 128+。満たせないなら v3.4 に留まる
- 見た目が変わる系（shadow スケール・ring 1px・border currentColor・space-y）は移行後に必ず目視確認する
- 新規コードは v4 流（スラッシュ記法・bg-(--var)・@theme・@utility）で書く
破壊的変更の数は多く見えますが、方向性は「CSS 標準に寄せる」で一貫しています。一度 v4 の書き方に慣れると、設定ファイルとCSSを往復しない開発体験には戻れなくなるはずです。
まずは開発ブランチでアップグレードツールを走らせて、この記事の10項目をチェックリストに差分を眺めるところから始めてみてください。
