tailwindcss-core

Tailwind CSS v4.3 の CSS ファースト設定ディレクティブについて説明します。`@import "tailwindcss"`、テーマトークンを CSS カスタムプロパティとして定義する `@theme`、追加のソースファイルをスキャンする `@source`、カスタムユーティリティとバリアントを作成する `@utility`／`@variant`、カスタム CSS 内でユーティリティを組み合わせる `@apply`、レガシーな JS 設定を読み込む `@config` を取り上げます。

さらに、ダークモードのバリアント設定、@theme によるレスポンシブブレークポイント、CSS レイヤーの階層（theme, base, components, utilities）、プラグインの統合についても説明します。これらは、tailwind.config.js を CSS ファースト方式で完全に置き換える機能です。

Tailwind CSS Core v4.3

概要

Tailwind CSS v4（v4.0 以降。現在の安定版は v4.3）では、従来の tailwind.config.js ファイルが不要になる CSS ファースト方式が採用されています。設定はすべて、専用ディレクティブを使って CSS ファイル内に直接記述します。

主なコンセプト

1. @import "tailwindcss"

Tailwind CSS を読み込むためのエントリーポイントです。メインの CSS ファイルの先頭に記述します。

@import "tailwindcss";

このディレクティブにより、次の内容が自動的に読み込まれます。

• 基本ユーティリティ
• レスポンシブバリアント
• レイヤー（theme、base、components、utilities）

2. @theme

CSS カスタムプロパティを使って、テーマ値を定義またはカスタマイズするディレクティブです。

@theme {
  --color-primary: #3b82f6;
  --color-secondary: #ef4444;
  --spacing-custom: 2.5rem;
  --radius-lg: 1rem;
}

変数は、生成されるユーティリティから利用できます。

• --color-* → bg-primary、text-primary などのクラス
• --spacing-* → p-custom、m-custom などのクラス
• --radius-* → rounded-lg などのクラス

3. @source

glob パターンを使って、追加のソースファイルを含めるディレクティブです。

@source "./routes/**/*.{ts,tsx}";
@source "./components/**/*.{tsx,jsx}";
@source "../packages/ui/src/**/*.{ts,tsx}";

Tailwind はこれらのファイルをスキャンし、プロジェクトで使われているユーティリティを生成します。

4. @utility および @variant

カスタムユーティリティとバリアントを作成するディレクティブです。

@utility truncate {
  overflow: hidden;
  text-overflow: ellipsis;
  white-space: nowrap;
}

/* Define a new variant with @custom-variant */
@custom-variant theme-midnight (&:where([data-theme="midnight"] *));

/* Apply an existing variant inside CSS with @variant
   (stacked `hover:focus` and compound `hover, focus` forms since v4.3) */
.card {
  @variant hover:focus {
    background: var(--color-sky-600);
  }
}

5. @apply

カスタム CSS ルール内で Tailwind クラスを適用するディレクティブです。

.btn {
  @apply px-4 py-2 rounded-lg font-semibold;
}

.btn-primary {
  @apply bg-blue-500 text-white hover:bg-blue-600;
}

6. @config

必要に応じて外部設定を読み込むディレクティブです。

@config "./tailwind.config.js";

（v4 では省略可能です。主に後方互換性のために使用します）

ダークモード

Tailwind v4.3 でのダークモード設定：

@import "tailwindcss";

/* Default: `dark:` follows prefers-color-scheme — no config needed */

または、手動クラスで設定します（@custom-variant で dark バリアントを上書きします）。

@custom-variant dark (&:where(.dark, .dark *));

レスポンシブブレークポイント

ブレークポイントは @theme で定義します。

@theme {
  --breakpoint-sm: 640px;
  --breakpoint-md: 768px;
  --breakpoint-lg: 1024px;
  --breakpoint-xl: 1280px;
  --breakpoint-2xl: 1536px;
}

レスポンシブバリアントはユーティリティと組み合わせて使用します。

<div class="text-sm md:text-base lg:text-lg"></div>

レイヤー階層

@layer theme, base, components, utilities;

@import "tailwindcss";

/* Your customizations */
@layer components {
  .btn { @apply px-4 py-2 rounded; }
}

@layer utilities {
  .text-shadow { text-shadow: 0 2px 4px rgba(0,0,0,0.1); }
}

プラグインの統合

Tailwind プラグインを読み込みます。

@import "tailwindcss";
@plugin "flowbite/plugin";
@source "../node_modules/flowbite";

詳細度の順序

CSS ファーストでは、インポートと宣言の順序によって詳細度が決まります。

1. @import "tailwindcss" - 基本ユーティリティ
2. @theme { ... } - テーマ変数
3. @layer components { ... } - カスタムコンポーネント
4. @layer utilities { ... } - カスタムユーティリティ

CSS ファースト方式のメリット

• 複雑な JavaScript 設定ファイルが不要
• CSS 変数による型安全性
• 宣言的で読みやすい設定
• CSS プリプロセッサを置き換えます（Tailwind v4 は Sass／Less／Stylus との併用を想定して設計されていません）
• 大規模プロジェクトのメンテナンスを簡素化

詳細なリファレンス

次のファイルを参照してください。

• theme.md - テーマ変数の設定全般
• directives.md - すべてのディレクティブの構文と使用例
• config.md - 高度な設定と使用例