Tailwind CSS v4 完全ガイド【2026年最新】｜Oxide エンジン・CSS-first 設定（@theme / @utility / @source / @custom-variant）・コンテナクエリ・3D Transform・@starting-style・v3 からの移行まで実戦パターンで解説

# インストール
npm install tailwindcss @tailwindcss/vite

import { defineConfig } from "vite";
import tailwindcss from "@tailwindcss/vite";

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

@import "tailwindcss";

npm install tailwindcss @tailwindcss/postcss

export default {
  plugins: { "@tailwindcss/postcss": {} },
};

# watch モードで開発
npx @tailwindcss/cli -i src/input.css -o dist/output.css --watch

# 本番ビルド（--minify）
npx @tailwindcss/cli -i src/input.css -o dist/output.css --minify

@import "tailwindcss";

@theme {
  /* カラーパレット */
  --color-primary-50:  oklch(0.97 0.014 255.1);
  --color-primary-500: oklch(0.54 0.22 258.6);
  --color-primary-900: oklch(0.22 0.12 266.0);

  /* フォント */
  --font-sans: "Inter", "Noto Sans JP", sans-serif;
  --font-mono: "JetBrains Mono", monospace;

  /* ブレイクポイント追加 */
  --breakpoint-3xl: 1920px;

  /* カスタムイージング */
  --ease-snappy: cubic-bezier(0.2, 0, 0, 1);
  --ease-bounce: cubic-bezier(0.68, -0.55, 0.27, 1.55);

  /* カスタムスペーシング基準 */
  --spacing: 0.25rem;
}

<div class="bg-primary-500 text-white font-sans p-8">
  <h1 class="text-3xl">Tailwind v4</h1>
  <p class="mt-4 ease-snappy transition">CSS 変数で全部管理される</p>
</div>

<!-- 3xl ブレイクポイントも自動で追加される -->
<div class="text-base 3xl:text-xl">...</div>

@import "tailwindcss";

@theme {
  /* Tailwind 既定のカラーを全部削除 → カスタム定義のみ */
  --color-*: initial;

  --color-ink: #111827;
  --color-paper: #fafafa;
  --color-accent: oklch(0.7 0.2 30);
}

@import "tailwindcss";

/* node_modules 内の UI ライブラリもクラス抽出対象にする */
@source "../node_modules/@mycompany/ui-lib";
@source "../node_modules/shadcn-ui";

/* 逆に除外したいファイルがあれば */
@source not "./src/legacy/**/*.html";

@utility flex-center {
  display: flex;
  align-items: center;
  justify-content: center;
}

@utility card {
  border-radius: 0.75rem;
  background: var(--color-white);
  box-shadow: 0 4px 16px -2px rgb(0 0 0 / 0.1);
  padding: 1.5rem;
}

<div class="card flex-center">...</div>

/* data-theme="dark" 下のスタイル */
@custom-variant theme-dark (&:where([data-theme="dark"] *));

/* is-active 属性があるときだけ */
@custom-variant active ([data-active] &);

/* フォームがバリデーションエラーの時 */
@custom-variant invalid (&:user-invalid);

<div data-theme="dark">
  <button class="bg-white theme-dark:bg-gray-900">Click</button>
</div>

<input class="border-gray-300 invalid:border-red-500" required type="email" />

.btn-primary {
  @apply inline-flex items-center gap-2 rounded-lg px-4 py-2 bg-primary-500 text-white font-medium;
  @apply hover:bg-primary-600 focus-visible:ring-2 focus-visible:ring-primary-400;
}

<!-- グリッド列（v3: grid-cols-[15] → v4: そのまま） -->
<div class="grid grid-cols-15 gap-4">...</div>

<!-- スペーシング（4 の倍数以外も OK） -->
<div class="mt-17 pr-29 w-13">...</div>

<!-- z-index（任意） -->
<div class="z-47">...</div>

@theme {
  --spacing: 0.25rem;  /* 1 = 0.25rem = 4px */
}

/* 自動生成ロジック */
.mt-17 { margin-top: calc(var(--spacing) * 17); }   /* 4.25rem */
.w-13  { width: calc(var(--spacing) * 13); }        /* 3.25rem */

<button
  data-loading
  class="opacity-60 data-loading:opacity-100 data-loading:animate-pulse"
>
  送信中...
</button>

<!-- 値までマッチ（data-state="open"） -->
<div data-state="open" class="data-[state=open]:block hidden">
  Open!
</div>

<div class="@container">
  <div class="grid grid-cols-1 @sm:grid-cols-2 @lg:grid-cols-3">
    <!-- コンテナ幅に応じて列数が変わる（ビューポートではない） -->
  </div>
</div>

<!-- 範囲指定・最大幅指定 -->
<div class="@container">
  <p class="@max-md:hidden">md 以上で表示</p>
  <p class="@min-sm:@max-lg:text-xs">sm 〜 lg の間だけ小さく</p>
</div>

<div class="perspective-distant">
  <article class="transform-3d rotate-x-51 rotate-z-43 transition duration-500 hover:rotate-x-0 hover:rotate-z-0">
    <img src="/card.jpg" alt="" />
  </article>
</div>

<!-- 線形（角度指定） -->
<div class="bg-linear-45 from-indigo-500 via-purple-500 to-pink-500">...</div>

<!-- 補間モード（OKLCH は色が鮮やか、sRGB は暗く濁る場合あり） -->
<div class="bg-linear-to-r/oklch from-indigo-500 to-teal-400">...</div>
<div class="bg-linear-to-r/srgb  from-indigo-500 to-teal-400">...</div>

<!-- コニック -->
<div class="size-40 bg-conic from-red-500 via-yellow-500 to-red-500">...</div>

<!-- ラジアル（位置指定） -->
<div class="size-40 bg-radial-[at_25%_25%] from-white to-zinc-900">...</div>

<!-- HSL の長い色相経由（虹色） -->
<div class="size-40 bg-conic/[in_hsl_longer_hue] from-red-600 to-red-600">...</div>

<div popover id="menu"
     class="transition-discrete duration-300
            opacity-100 scale-100
            starting:open:opacity-0 starting:open:scale-95">
  <!-- popover が開いた瞬間 opacity-0 scale-95 から始まり、100 / 100 へ補間される -->
  <p>メニュー内容</p>
</div>

<button popovertarget="menu">開く</button>

<!-- :not(:hover) 相当 -->
<div class="opacity-75 not-hover:opacity-100">
  hover されていない時は透過 75%、hover されたら 100%
</div>

<!-- メディアクエリの否定 -->
<p class="not-supports-hanging-punctuation:px-4">
  ブラウザが hanging-punctuation 未対応の時だけ余白を付ける
</p>

/* Cascade Layers: スタイルの優先順位を明示 */
@layer theme, base, components, utilities;

/* Registered Custom Properties: 型付き CSS 変数 */
@property --tw-gradient-from {
  syntax: "<color>";
  inherits: false;
  initial-value: transparent;
}

/* color-mix() によるオパシティ計算 */
.bg-blue-500\/50 {
  background-color: color-mix(in oklab, var(--color-blue-500) 50%, transparent);
}

/* Logical Properties（RTL 対応自動化） */
.mx-6 {
  margin-inline: calc(var(--spacing) * 6);   /* 旧 margin-left/right を 1 プロパティで */
}
.ps-4 {
  padding-inline-start: calc(var(--spacing) * 4);  /* LTR では左、RTL では右 */
}

# まず v4 に依存を更新
npm install tailwindcss@latest @tailwindcss/vite@latest
#  or @tailwindcss/postcss@latest

# 公式 codemod
npx @tailwindcss/upgrade

# 以下を自動変換:
# - tailwind.config.js の theme → @theme ディレクティブ
# - @tailwind base/components/utilities → @import "tailwindcss"
# - 一部の非推奨クラス名の置換
# - content フィールドの削除（自動検出に任せる）

# 差分を確認してコミット
git diff