addBase での @variant がカスタムバリエントを使用可能に

Tailwind CSS v4.3.1 で、addBase 内の @variant がカスタムバリエントを正しく処理できずエラーになる回帰を修正し、@variant を用いたベーススタイル定義が再び機能するようになりました。

背景

addBase に対して @variant を記述できたのは v4.3.0 までであり、v4.3.1 で回帰が報告されました。この回帰は、addBase が呼び出された瞬間に @variant の置換 が実行され、まだ登録されていないカスタムバリエントが未解決のまま残るために発生しています。

@variant の置換はデザインシステムの解析段階で行われますが、プラグイン側で @custom-variant を後から定義するケースでは、置換タイミングが早すぎて名前解決に失敗します。その結果、addBase の CSS 生成が例外を投げてビルドが失敗するという症状が観測されました。

この問題は Tailwind CSS v4.3.0 では正常に動作していたにも関わらず、v4.3.1 で導入された内部変更が原因です。回帰を解消することで、既存のプラグインが期待通りにカスタムバリエントを利用できるようになります。

技術的な変更

addBase 内で @variant を早期に置換していたロジックを削除し、置換を後続の処理フローに委譲することで回帰を解消しました。具体的には plugin-api.ts のインポートと置換呼び出しが削減されています。

変更前:

import {
  compoundsForSelectors,
  IS_VALID_VARIANT_NAME,
  substituteAtSlot,
  substituteAtVariant,
} from '../variants'

変更後:

import { compoundsForSelectors, IS_VALID_VARIANT_NAME, substituteAtSlot } from '../variants'

さらに buildPluginApi 内の substituteAtVariant 呼び出しが除去されました。

変更前:

featuresRef.current |= substituteAtVariant(baseNodes, designSystem)

変更後:

// 置換は後続の処理に任せるためここでは呼び出さない

このシンプルな除去により、@variant の置換は walk での後処理段階で行われ、カスタムバリエントが既に登録済みの場合に正しく解決されます。修正に合わせて plugin-api.test.ts に回帰テストが追加され、addBase 内でカスタムバリエントが期待通りに生成されることが検証されています。

設計判断

今回の修正は 新しい API を導入せず、既存の変換パイプラインを調整する 方針で行われました。substituteAtVariant の削除は機能的に影響を与えず、エラーの根源であった早期置換だけを回避する最小限の変更です。

このアプローチは 後方互換性 を保持しつつ、プラグイン開発者が既存の addBase と @variant の組み合わせをそのまま利用できるようにします。コードベースへの侵入度が低く、他の変換ロジックやプラグイン API への影響が限定的である点が評価されています。

結果として、Tailwind CSS のプラグインエコシステムはカスタムバリエントを含むベーススタイル定義を安全に利用でき、以前のバージョンとの互換性が復元されました。

まとめ

addBase における @variant の早期置換を撤回し、カスタムバリエントが後から定義されても正しく処理できるようにしたことで、Tailwind CSS v4.3.1 の回帰が解消されました。この変更は最小限のコード削除で実装され、既存プラグインへの影響を避けつつ、設定可能なバリエント機構の一貫性を保っています。