tailwindcss-v4

Tailwind CSS v4（現行の安定版 v4.3）のコア機能のうち、v3→v4への移行に関係する内容を説明します。`@theme`の名前空間と生成されるユーティリティの対応（`--color-*`→`bg-*`／`text-*`、`--spacing-*`→`p-*`／`m-*`／`gap-*`など）、v3→v4の破壊的変更（`@tailwind`ディレクティブの削除、`shadow-sm`→`shadow-xs`などのユーティリティ名の変更、`bg-opacity-*`／`flex-shrink-*`の削除、`@utility`のカスタムユーティリティ構文の変更、任意値での変数構文、important修飾子の位置）、および`@tailwindcss/upgrade` CLIツールを扱います。

日常的なCSSファーストの設定リファレンス（@theme／@utility／@variantの使い方はtailwindcss-coreが担当）でも、ユーティリティクラスの検索ガイド（各カテゴリのスキルが担当）でもありません。

Tailwind CSS v4.3 コア

現行の安定版：tailwindcss 4.3.3（2026年7月）。v4.0以降のマイナーリリース：v4.1（テキストシャドウ、マスク）、v4.2（mauve／olive／mist／taupeのパレット、@tailwindcss/webpack、論理プロパティのpbs／mbs／inline-*／block-*／inset-s|e|bs|beユーティリティ、font-features-*、start-*／end-*は非推奨に）、v4.3（スクロールバー用ユーティリティ、@container-size、zoom-*、tab-*、スタック／複合@variant、関数形式の@utilityにおける--default()）。

ドキュメント

• CSSテーマ変数、デザイントークン、カスタマイズ → tailwindcss-core
• ディレクティブ（@utility、@variant、@theme、@apply）→ tailwindcss-core
• カスタムユーティリティとバリアント → tailwindcss-custom-styles
• コンテンツ検出（@sourceスキャン）→ tailwindcss-core
• v3からv4への移行 → 下記の「v3 → v4の破壊的変更」セクションを参照

クイックリファレンス - @themeの名前空間

名前空間	生成されるユーティリティ
--color-*	bg-、text-、border-、fill-
--font-*	font-*
--text-*	text-xs、text-sm、text-baseなど
--spacing-*	p-、m-、gap-、w-、h-*
--radius-*	rounded-*
--shadow-*	shadow-*
--breakpoint-*	sm:、md:、lg:、xl:
--animate-*	animate-spin、animate-bounceなど
--ease-*	ease-in、ease-out、ease-in-out

v3 → v4の破壊的変更

@tailwindディレクティブの削除

/* v3 */
@tailwind base;
@tailwind components;
@tailwind utilities;

/* v4 */
@import "tailwindcss";

ユーティリティ名の変更

v3	v4
shadow-sm	shadow-xs
shadow	shadow-sm
rounded-sm	rounded-xs
rounded	rounded-sm
outline-none	outline-hidden
ring	ring-3

非推奨ユーティリティの削除

• bg-opacity-* → bg-black/50を使用
• text-opacity-* → text-black/50を使用
• flex-shrink-* → shrink-*を使用
• flex-grow-* → grow-*を使用

カスタムユーティリティの構文

/* v3 */
@layer utilities {
  .tab-4 {
    tab-size: 4;
  }
}

/* v4 */
@utility tab-4 {
  tab-size: 4;
}

任意値での変数

<div class="bg-[--brand-color]"></div>


<div class="bg-(--brand-color)"></div>

important修飾子の位置

<div class="!bg-red-500">


<div class="bg-red-500!">

アップグレードツール

npx @tailwindcss/upgrade

Node.js 20以降が必要です

詳細リファレンス

• configuration.md - CSSファーストの@theme設定を書くとき、または@utility／@variant／@custom-variantディレクティブを使用するときに読み込みます
• api-functions.md - --alpha()／--spacing() CSS関数または@applyを使用するときに読み込みます
• installation-support.md - Tailwind v4をインストールするとき（npm／Vite／CLI／webpack）、またはブラウザーサポートを確認するときに読み込みます