named opacity modifier の IntelliSense 提案を復活

Tailwind CSS v4 で --opacity-* カスタムプロパティから名前付き opacity 修飾子を使用できるようになったが、IntelliSense の候補提示が抜け落ちていた。本 PR はその提案機能を再度有効化し、開発体験を向上させる。

背景

IntelliSense の提案が欠落していたことが、Issue #1541 で報告されている。以前の PR #14278 と #14339 で名前付き opacity 修飾子自体が削除され、#15009 で再導入されたが、補完ロジックの更新が漏れていた。結果として bg-red-500/half のように --opacity-half を用いたクラス入力時に候補が表示されず、開発者は手動でクラス名を覚える必要があった。

この欠如は、Tailwind CSS IntelliSense が colorUtility の抽象化を利用しない一部ユーティリティで発生していた。PR はそのギャップを埋め、全ユーティリティで一貫した提案を提供することを目的としている。

技術的な変更

packages/tailwindcss/src/utilities.ts に modifierThemeKeys: ['--opacity'] を追加した。これによりユーティリティ生成時に --opacity 名前空間から値を取得し、asColor 関数が自動的に名前付き修飾子を解決できるようになった。

@@ -519,6 +519,7 @@ export function createUtilities(theme: Theme) {
       {
         values: ['current', 'inherit', 'transparent'],
         valueThemeKeys: desc.themeKeys,
+        modifierThemeKeys: ['--opacity'],
         modifiers: Array.from({ length: 21 }, (_, index) => `${index * 5}`),
       },

その他のユーティリティブロック（背景色、境界色、テキスト色など）でも同様に modifierThemeKeys: ['--opacity'] が付与され、全てのカラー系ユーティリティが名前付き opacity 修飾子を参照できるようになった。

テストスナップショット packages/tailwindcss/src/__snapshots__/intellisense.test.ts.snap が 165 行追加され、期待されるクラス一覧に bg-current/background や accent-inherit/background など background 修飾子が含まれることを確認できる。スナップショットの拡張は提案ロジックの正当性を自動テストで保証する。

CHANGELOG.md にも新機能として記載され、Support class suggestions for named opacity modifiers from --opacity theme values が追加されたことで、リリースノートとしてユーザーに通知できるようになった。

設計判断

既存のユーティリティ生成フレームワークにフラグだけを付与する 方針が採用された。modifierThemeKeys を追加するだけで、既存コードへの侵入度は最小に抑えられ、後方互換性も保持された。新しい設定キーを導入せず、--opacity 名前空間 を直接参照することで、テーマ側の記述と IDE 補完の整合性が保たれた。

この設計は、ユーティリティが Theme オブジェクトを共有している点を活かし、コードベースの肥大化を防ぎつつ、全体的な一貫性を実現したと言える。

まとめ

PR #20287 は、名前付き opacity 修飾子の IntelliSense 提案を再度有効化し、--opacity-* カスタムプロパティとエディタ補完の橋渡しを実装した。utilities.ts の modifierThemeKeys 追加というシンプルな変更で、既存ユーティリティ全体に新機能を波及させ、開発者の記述負荷を軽減した。