Tailwind CSS v4の@themeを読み解く

v4 で何が変わったか

Tailwind v4は設定がCSS ファイルに移動した。これまで tailwind.config.tsを経由していたtoken定義は、すべて CSSの@theme ディレクティブで完結する。

設定ファイル不要（tailwind.config.ts は削除可）
全tokenがCSS 変数として直接公開される
ビルドがPostCSSplugin 1 つで完結 → Next.js 15 では @tailwindcss/postcssを使う

@theme の書き方

app/globals.css

@import "tailwindcss";
 
@theme {
  --color-bg: #0e0f13;
  --color-fg: #dde0e7;
  --color-accent: #4ade80;
 
  --font-sans: 'Inter', system-ui, sans-serif;
  --font-mono: 'JetBrains Mono', monospace;
 
  --radius-md: 8px;
}

これだけで以下のユーティリティが自動生成される。

bg-bg, text-bg, border-bg
bg-fg, text-fg, border-fg
bg-accent, text-accent, ...
font-sans, font-mono
rounded-md

CSS 変数として var(--color-bg) でも使える。

Next.js v15 への組み込み

postcss.config.mjs でpluginを有効化する。

postcss.config.mjs

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

それからapp/globals.css で @import "tailwindcss"; を一行入れて、@theme { ... } を続ける。

v3 からの変更ポイント

tailwind.config.ts の theme.extend は不要。@themeで直接置き換える
PostCSS pluginの名前が tailwindcss ではなく @tailwindcss/postcss
dark モードはデフォルト(OS設定)では prefers-color-scheme ベースで、クラス切り替え(JS設定)にしたい場合は @custom-variant dark (&:where(.dark, .dark *)); を使う

∟テーマ変数について

CSS-first にすることで設定が一箇所に集約され、見通しが良くなった。