Tailwind CSS v4

Tailwind CSS v4、CSS優先構成、モダンユーティリティパターン、および tailwind-variants を使用した型安全なコンポーネントスタイリングのエキスパートガイダンス。

CSS優先構成

Tailwind CSS v4 は tailwind.config.ts を廃止し、CSS のみの構成を採用します。すべての構成は特殊なディレクティブを使用して CSS ファイルに記述されます。

コアディレクティブ:

• @import "tailwindcss" - Tailwind をロードするエントリーポイント
• @theme { } - デザイントークンを定義または拡張
• @theme static { } - ユーティリティを生成しないトークンを定義
• @utility - カスタムユーティリティを作成
• @custom-variant - カスタムバリアントを定義

最小限の例:

@import "tailwindcss";

@theme {
  --color-brand: oklch(0.72 0.11 178);
  --font-display: "Inter", sans-serif;
  --spacing-edge: 1.5rem;
}

@theme で定義されたすべてのテーマトークンは、自動的にユーティリティクラスとして利用可能になります。たとえば、--color-brand は bg-brand、text-brand、border-brand などとして使用できます。

ESLint 統合

Tailwind CSS v4 のクラス検証とスタイル強制には eslint-plugin-better-tailwindcss を使用してください。

正確性ルール（エラー）:

• no-conflicting-classes - 互いに上書きするクラスを検出
• no-unknown-classes - Tailwind に登録されていないクラスにフラグを立てる

スタイル上のルール（警告）:

• enforce-canonical-classes - 標準 v4 クラス名を使用
• enforce-shorthand-classes - 省略形クラスバージョンを使用
• no-deprecated-classes - 古いクラス名を削除
• no-duplicate-classes - 冗長な宣言を排除
• no-unnecessary-whitespace - 余分なスペースをクリーンアップ

例:

// ❌ 悪い例: 個別のパディング
<div className="px-6 py-6">

// ✅ 良い例: 省略形
<div className="p-6">

// ❌ 悪い例: 個別の幅/高さ
<div className="w-6 h-6">

// ✅ 良い例: size ユーティリティ
<div className="size-6">

Tailwind クラスを修正した後、プロジェクトの ESLint チェックを実行して、コードベース全体のすべての変更を検証してください。

コーディング推奨事項

レイアウト、間隔、タイポグラフィ、色、枠線、グラデーション、任意の値、クラスマージング、画像サイズ、z インデックス、ダークモードをカバーする詳細なコーディングパターンについては、references/coding-preferences.md を参照してください。

CSS Modules

CSS Modules は、Tailwind クラスで簡単に記述できない複雑な CSS の最後の手段としてのみ使用してください。

すべての .module.css ファイルの先頭に @reference "#tailwind"; を含める必要があり、モジュール内で Tailwind ユーティリティとテーマトークンを使用できるようにします。

例:

/* component.module.css */
@reference "#tailwind";

.component {
  /* Tailwind ユーティリティで表現できない複雑な CSS */
  /* 引き続き Tailwind ユーティリティとテーマトークンを使用できます */
}

一般的なタスク

バリアント付きコンポーネントの追加

1. パターンについては references/tailwind-variants.md を読む
2. プロジェクトの @theme 構成で利用可能なトークンを確認
3. 型安全なバリアントについては tailwind-variants から tv() を使用

例:

import { tv } from "tailwind-variants";

const button = tv({
  base: "rounded-lg px-4 py-2 font-medium",
  variants: {
    color: {
      primary: "bg-blue-600 text-white",
      secondary: "bg-gray-600 text-white",
    },
    size: {
      sm: "text-sm",
      md: "text-base",
      lg: "text-lg",
    },
  },
});

スタイルのデバッグ

1. 互換性に関する変更については references/tailwind-v4-rules.md を確認
2. グラデーション構文を確認 (bg-gradient-* ではなく bg-linear-*)
3. CSS 変数の構文を確認 (bg-[--var-my-color] ではなく bg-my-color)
4. 任意の値がプロジェクトの @theme 構成に存在するかどうかを確認

色の操作

1. 最初にプロジェクトの @theme 構成を確認して、利用可能な色を確認
2. 利用可能な場合はセマンティクスカラー名を使用
3. 透明度修飾子を使用して透明度を調整 (/20、/50 など)
4. 絶対に必要な場合以外は任意の色を避ける

例:

// ✅ 良い例: テーマトークンと不透明度
<div className="bg-brand/20 text-brand">

// ❌ 避けるべき: 任意の16進数
<div className="bg-[#4f46e5]/20 text-[#4f46e5]">

アニメーションの追加

1. 利用可能なアニメーションについては references/tw-animate-css.md を読む
2. ベースクラス (animate-in または animate-out) をエフェクトクラスと組み合わせる
3. 小数間隔の注意: 2.5 ではなく [0.625rem] 構文を使用

例:

// 開始: フェード + 下からのスライドアップ
<div className="fade-in slide-in-from-bottom-4 duration-300 animate-in">

// 終了: フェード + 下へのスライドダウン
<div className="fade-out slide-out-to-bottom-4 duration-200 animate-out">

クイックリファレンステーブル

側面	パターン
構成	CSS のみ: @theme、@utility、@custom-variant
グラデーション	bg-linear-*、bg-radial、bg-conic
不透明度	修飾子構文: bg-black/50
行の高さ	修飾子構文: text-base/7
フォント機能	font-features-zero、font-features-ss01 など
CSS 変数	bg-my-color (@theme から自動生成)
CSS Modules	上部に @reference "#tailwind";
クラスマージング	条件付きには cn()、静的にはプレーンな文字列
ビューポート	min-h-screen ではなく min-h-dvh
コンポーネント変種	references/tailwind-variants.md
アニメーション	references/tw-animate-css.md
V4 ルール	references/tailwind-v4-rules.md

リファレンスドキュメント

• Tailwind v4 ルールとベストプラクティス: references/tailwind-v4-rules.md — 互換性に関する変更、削除/名前変更されたユーティリティ、レイアウトルール、タイポグラフィ、グラデーション、CSS 変数、新しい v4 機能、一般的な落とし穴
• tailwind-variants パターン: references/tailwind-variants.md — コンポーネントバリアント、スロット API、合成、TypeScript 統合、レスポンシブバリアント
• tw-animate-css リファレンス: references/tw-animate-css.md — 開始/終了アニメーション、スライド/フェード/ズームユーティリティ、間隔に関する落とし穴