Tailwind CSS の任意値 (arbitrary value) が反映されない

要約

Tailwind の JIT スキャナは、ソース上で完全な文字列として出現したクラス名だけを CSS に出力する。
任意値 w-[123px] は通常クラスと同じ規則に従い、加えて括弧・スペース・引用符のエスケープが必要。w-[${size}] のような実行時補完は検出されず、content に含まれないファイルに書いた任意値も拾われない。

よくある原因

1. 値部分を変数で組み立てている: テンプレートリテラル `text-[${size}]` は静的解析に乗らない。
   Tailwind は完全文字列を要求する。
2. content の対象外: .mdx / .svelte / apps/web/** のような追加パスを tailwind.config.js の content に書いていない。
   スキャンされないファイルのクラスは拾われない。
3. 値内のスペース: grid-cols-[1fr 2fr] のような半角スペースは CSS クラス名区切りと衝突する。_ で置換する規約がある（grid-cols-[1fr_2fr]）。
4. 特殊文字: before:content-['→'] のようにシングルクオートを含む値はそのまま書ける。
   バックスラッシュは \\ でエスケープが必要。

解決策

1. 完全文字列で書く

// NG: スキャンで検出されない
<div className={`w-[${width}px]`}>...</div>
 
// OK
const widthClass = width === "narrow" ? "w-[120px]" : "w-[240px]";
<div className={widthClass}>...</div>

任意値ガイド の通り、完全クラス名を変数で切り替えるのが基本。

2. スペースは _ で置換

<div class="grid-cols-[1fr_2fr_minmax(0,3fr)]">...</div>
<div class="bg-[url('/hero_bg.png')]">...</div>

_ は Tailwind が CSS 出力時に自動でスペースに戻す。
逆に値の中に意図的に _ を書きたいなら \_ でエスケープする。

3. content 設定を見直す

// tailwind.config.js
module.exports = {
  content: [
    "./src/**/*.{ts,tsx}",
    "./src/**/*.mdx",
    "./node_modules/@my-org/ui/dist/**/*.js",
  ],
};

新しい拡張子や外部パッケージのクラスを使うなら明示的に追加する。

4. CSS 変数で完全に動的な値を渡す

<div
  style={{ "--w": `${width}px` } as React.CSSProperties}
  className="w-[var(--w)]"
>
  ...
</div>

幅・色・サイズが完全に実行時依存なら、クラス名側を固定して値を CSS 変数で渡す。