BLOG /
Tailwind v4で色が効かない原因は@theme inlineの書き方
Tailwind CSS v4で bg-primary などが生成されず画面が真っ白になる症状について、@theme inline と var() 参照の落とし穴、直接色値で書く回避策、確かめ方を整理します。
Tailwind CSS v4 で bg-primary や text-secondary が効かず、画面が真っ白になる。原因はクラス名の typo でも HMR(ホットリロード)の不調でもない。@theme inline の中で色を var() 参照にしていると、この構成では --color-* からユーティリティが生成されない。回避策は、色値を @theme に直接書くことだ。
症状:bg-primary が生成されず、全画面が真っ白になる
色定義が次の形になっていると起きる。
@theme inline {
--color-primary: var(--primary);
--color-secondary: var(--secondary);
}
:root に --primary を置き、@theme inline から参照する形だ。shadcn/ui 系の構成でよく見る書き方でもある。
この状態でビルドすると、画面全体が真っ白になる。DevTools で要素を見ると、bg-primary や text-secondary のスタイルが出力されていない。色は rgba(0,0,0,0)、つまり完全な透明に解決される。
症状は見た目にだけ現れる。ユーティリティが生成されず、色が透明に解決され、画面が真っ白になる。手がかりは画面の側にしか出ないので、クラス名や色の定義まで遡らないと原因は分からない。
原因:@theme inline で --color-* を var() 参照にしている
症状から言える点は次の2つだ。
@theme inlineの中で--color-*を別の CSS 変数への参照(var(--primary))にすると、ユーティリティクラスが生成されないbg-primaryなどのクラスが存在しないので、色が透明に解決される
仕組みは1段だけ押さえておけば足りる。v4 の @theme は、名前空間(--color-* など)のトークンからユーティリティを作る。--color-primary が具体的な色値なら、bg-primary text-primary border-primary といった一式が生える。値が他の変数への参照だと、この生成が働かない。
inline は、変数を参照する値を、そのまま展開して使うためのオプションだ。この説明だけでは、var() 参照の色でユーティリティが消えるとは読み取りにくい。inline という名前から受ける印象と、この構成での挙動にはずれがある。ここが地雷になる。
内部の処理順までは、この記事では踏み込まない。扱うのは「この構文だと生成されない」という挙動だ。
回避策:@theme に色値を直接書き、間接参照は併用にとどめる
主要な色トークンは、@theme に色値を直接書く。
@theme {
--color-primary: #E67E22;
--color-secondary: #2C3E50;
}
これで bg-primary と text-secondary が生成され、色が出る。
間接参照が必要な場面もある。ダークモードで :root の変数を切り替えたい場合などだ。その場合は @theme inline を併用してよい。ただし、役割を分ける。
- 主要な色トークン:
@themeに直接値で置く - 間接参照が要るもの:
@theme inline側に置く
inline を捨てる必要はない。要点は、色の本体を inline と var() だけに頼らないことだ。
制約もある。直接値にすると、色の定義元が @theme の1か所に固定される。実行時に変数を差し替えて色を変える設計とは相性が悪い。切り替えが要るなら、その部分だけを inline 側に分けて持つことになる。
確かめ方:HMR再起動で治らないときは構文ミスを疑う
見分け方は3つある。
- 出力された CSS に
bg-primaryがあるか。DevTools で要素を選び、該当クラスのスタイルが当たっているかを見る。無ければ、ユーティリティが生成されていない - 計算済みの色が
rgba(0,0,0,0)になっていないか。透明に解決されていれば、今回と同じ症状だ :rootに--primaryが定義されているか。参照先が未定義でも、色は透明になる。1と2が当てはまり、3も怪しいなら、別の原因が重なっている
判断の目安がもうひとつある。開発サーバーを再起動しても治らないなら、キャッシュや HMR ではなく、構文の問題を疑うことだ。再起動は無駄足になりやすい。
構文ミスと見当をつけたら、まず @theme 内の --color-* が var() 参照になっていないかを探す。直接の色値に書き換えて、色が出れば解決だ。出ないなら、クラス名と CSS の読み込み経路を疑う順になる。
派生テンプレートにもこの書き方を引き継ぐ
ひとつのテンプレートから、業種別の派生テンプレートを作る運用では、この落とし穴が増殖しやすい。元の書き方をコピーすれば、同じ症状も一緒にコピーされる。
派生を作るときは、最初から次の形を踏襲する。
@theme {
--color-primary: #E67E22; /* 業種ごとに値だけ差し替える */
}
差し替えるのは値だけにして、@theme に直接書く構造は動かさない。こうしておけば、派生が増えても同じ症状を踏みにくい。
ブランドカラーが変わるたびに、定義の置き場所まで変わってしまう。そんな運用は避けたい。色は値、構造は固定。この分担が、テンプレートを長持ちさせる。
テンプレートの実例は /works にまとめている。
Tailwind v4 の設定まわりで詰まったら、制作の相談は /contact へどうぞ。