tailwind-css

Tailwind CSS v4

実装前に確認すること：v4 固有の構文（@theme、@variant、CSS ファーストの設定）については、コードを書く前に Context7（query-docs）で最新のドキュメントを調べてください。Tailwind v4 は v3 から大幅に変更されているため、学習データが古い可能性があります。

作業ルール

• ユーティリティ名は完全なソースリテラルのままにし、対象ファイルがスキャンされていることを確認します。
• 共有のデザイントークンと、一貫した可視性の制御方法を使います。
• ソースや設定を変更した後は生成された CSS を確認します。JSX の文字列だけでは、ユーティリティが存在する証明になりません。
• レイアウトの包含関係を変更する場合は、ブラウザーでスクロール、オーバーレイ、フォーカスの動作をテストします。

コーディングルール

• space-x／space-y より gap を使う -- gap は折り返しに対応しますが、space-* は折り返し時に正しく動作しません
• 同じ寸法には w-* h-* より size-* を使う
• min-h-screen より min-h-dvh を使う -- dvh はモバイルブラウザーのツールバーを考慮します
• 不透明度修飾子（bg-black/50）を使う -- *-opacity-* ユーティリティは v4 で削除されています
• 任意の値よりデザイントークンを使う -- [#hex] を使う前に @theme を確認します
• クラスを動的に組み立てない -- text-${color}-500 は検出されません。完全なクラス名を使います
• @layer と組み合わせた @apply より @utility を使う -- v4 では、@layer クラスへの @apply は失敗します
• 最後の子要素のマージンより、親要素のパディングを使う -- 最後の子要素に下マージンを設定するのではなく、コンテナーにパディングを設定します
• overflow-x-auto は両軸のスクロールコンテナーになります -- このユーティリティが出力するのは overflow-x: auto だけですが、CSS Overflow 3 では、どちらかの軸がスクロール可能になると、もう一方の軸の visible 値も auto に計算されます。そのため、横方向のパンを可能にする目的だけで追加したラッパーが、縦方向にはみ出す要素を気付かないうちにクリップしたりスクロールさせたりします。対象には、ポータル化されていないドロップダウン、ポップオーバー、ツールチップ、カスタムセレクト、フォーカスリングがあります。jsdom はレイアウトを行わないため、ユニットテストでは検出できません。新しいラッパー内にレンダリングされるコンポーネントをすべて列挙し、オーバーレイに類するものがラッパーの外に表示されることをそれぞれ確認します。ポータル化は明示的に有効にする必要があり、自動ではありません。Radix では *.Portal が *.Content を囲む別個のパーツとして公開されているため、ライブラリが処理してくれると思い込まず、コンポーネントを確認してください。同じ計算値のルールは逆向きにも当てはまります。ページ全体のスクロールバーを疑う前に、すべての祖先要素の overflow をたどり、実際にスクロールしている要素を特定します
• ネイティブの hidden 属性と表示ユーティリティを併用して可視性を表現しない -- バージョンによって、両者は逆方向に解決されます。v4 の Preflight には [hidden]:where(:not([hidden="until-found"])) { display: none !important } が含まれているため、属性が優先され、表示されるはずの要素が非表示のままになります。一方、v3、または Preflight が無効化されているか読み込まれていない環境では、詳細度にかかわらず、作成者由来のユーティリティ（block、flex、grid）が UA 由来の [hidden] ルールより優先されるため、hidden が設定されていても要素が画面に表示されます。切り替える仕組みは一つにします：clsx(base, open ? 'block' : 'hidden')。いずれの状態も jsdom の toBeInTheDocument では検出できません。toBeVisible または実際のブラウザーエンジンでのみ検出できます

確認

• エラーゼロでビルドが成功する（npm run build など）
• 変更したファイルに v3 のクラス名が残っていない（利用可能な場合は @tailwindcss/upgrade --dry-run で確認）
• 同じ要素に競合するクラスがない

参考資料

• コンポーネントのパターン -- tailwind-variants のスロット、CVA、複合コンポーネント
• レイアウトのパターン -- グリッド領域、コンテナークエリ、z-index の管理、流動的なタイポグラフィ

タスク固有のリファレンス

対応する動作を実装またはレビューする前に、関連するリファレンスを確認してください。

• テーマトークン、ビルド設定、バージョン移行、ダークモード、またはスタイルの欠落については、configuration-and-migration.md を参照してください。
• クラスのマージ、スキャン対象のパス、バリアント、または lint との連携については、class-generation-and-composition.md を参照してください。

対応するトピックに該当する場合は、既存の専門リファレンスも参照してください。

• v3-to-v4-migration.md.