# Tailwind CSS 業務運用マニュアル

## 目次

**【基本操作】**
1. [システム概要](#1-システム概要)
2. [セットアップ・初期設定](#2-セットアップ初期設定)
3. [トップページ（Playground画面）](#3-トップページplayground画面)

**【業務フローに沿った機能】**
4. [【STEP1】CSS設計・テーマ定義（デザインシステムの構築）](#4-step1css設計テーマ定義デザインシステムの構築)
5. [【STEP2-3】ユーティリティクラスの記述・ビルド実行（CSSの生成）](#5-step2-3ユーティリティクラスの記述ビルド実行cssの生成)
6. [【STEP3-4】ファイル管理・ビルドツール統合（開発環境の連携）](#6-step3-4ファイル管理ビルドツール統合開発環境の連携)
7. [【STEP4-5】CSS最適化・本番デプロイ（リリース準備）](#7-step4-5css最適化本番デプロイリリース準備)

**【サポート機能】**
8. [プラグインシステム](#8-プラグインシステム)
9. [v3互換モード・マイグレーション](#9-v3互換モードマイグレーション)
10. [IntelliSense・開発支援機能](#10-intellisense開発支援機能)

**【運用ガイド】**
11. [日常業務の流れ](#11-日常業務の流れ)
12. [よくある質問と対処法](#12-よくある質問と対処法)
13. [トラブルシューティング](#13-トラブルシューティング)

---

## 1. システム概要

### 1.1 Tailwind CSSとは

Tailwind CSS（v4）は、カスタムUIを迅速に構築するためのユーティリティファーストCSSフレームワークです。HTML/JSXの`class`属性にユーティリティクラス名を記述するだけで、実際のCSSが自動生成されます。v4ではTypeScriptとRustのハイブリッド構成を採用し、JIT（Just-In-Time）コンパイルによる高速なCSS生成を実現しています。

本システムは、ビルドツール（Vite、webpack、PostCSS）やCLIと統合して動作し、開発者が効率的にスタイリングを行うための基盤を提供します。

### 1.2 本システムで行う主要業務

本システムは、主に以下の業務を支援します：

| 業務カテゴリ | 具体的な業務内容 |
|------------|----------------|
| **CSS設計・テーマ定義** | デザイントークン（色、スペーシング、フォント等）の定義、`@theme`ディレクティブによるテーマ管理 |
| **ユーティリティクラスによるスタイリング** | HTML/JSXへのクラス記述、バリアント（`hover:`、`md:`等）の適用、カスタムユーティリティの定義 |
| **CSSビルド・コンパイル** | CLI/Vite/PostCSS/webpackを使用したCSSの自動生成、ファイル監視による自動リビルド |
| **CSS最適化・本番デプロイ** | ミニファイ、未使用CSS除去、ソースマップ生成、最適化済みCSSの出力 |
| **プラグイン拡張** | カスタムプラグインの作成・登録、外部プラグインの利用 |
| **バージョンマイグレーション** | v3からv4への自動マイグレーション、設定ファイルの変換 |

### 1.3 業務フロー概要

本システムにおける開発業務は、以下の流れで進行します：

```
┌─────────────────────────────────────────────────────────────────┐
│                      開発業務フロー                               │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  【STEP 1】CSS設計・テーマ定義                                   │
│      @themeでデザイントークンを定義し、デザインシステムを構築       │
│      ↓                                                          │
│  【STEP 2】ユーティリティクラスの記述                             │
│      HTML/JSXにユーティリティクラスを記述してUIを構築              │
│      ↓                                                          │
│  【STEP 3】ビルド実行・開発サーバー起動                           │
│      CLI/Vite/PostCSSでCSSをコンパイル、watchモードで自動リビルド  │
│      ↓                                                          │
│  【STEP 4】CSS最適化                                             │
│      ミニファイ・最適化を実行し、本番用CSSを生成                   │
│      ↓                                                          │
│  【STEP 5】デプロイ・リリース                                    │
│      最適化済みCSSをプロジェクトに組み込み、デプロイ               │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

**役割別の業務概要：**

| 役割 | 主な業務 |
|------|---------|
| **フロントエンド開発者** | ユーティリティクラスの記述、カスタムユーティリティ/バリアントの定義、テーマのカスタマイズ |
| **デザインシステム管理者** | テーマ定義の管理、デザイントークンの統一、プラグインの選定・管理 |
| **ビルドエンジニア** | ビルドツールの設定、CI/CDパイプラインへの組み込み、最適化設定の調整 |

### 1.4 主な機能

| 機能 | 説明 | 業務フローでの位置 |
|------|------|------------------|
| テーマ管理（@theme） | CSS変数ベースのデザイントークン（色・スペーシング・フォント等）を定義・管理 | STEP 1 |
| ユーティリティクラス生成 | 100以上のユーティリティクラスをJITコンパイルで動的に生成 | STEP 2-3 |
| バリアント（修飾子） | `hover:`、`focus:`、`sm:`、`dark:`等のレスポンシブ・インタラクション修飾子 | STEP 2 |
| CLIツール | コマンドラインからのCSSビルド、watchモード、ソースマップ生成 | STEP 3-5 |
| ビルドツール統合 | Vite、webpack、PostCSSプラグインによるシームレスな統合 | STEP 3-4 |
| CSS最適化 | Lightning CSSによるミニファイ・最適化、未使用CSS変数の除去 | STEP 4 |
| プラグインシステム | カスタムユーティリティ/バリアント/テーマ拡張の追加 | 随時利用 |
| v3マイグレーション | v3からv4への自動変換ツール | 随時利用 |
| IntelliSense | IDEでのクラス名補完、バリアントリスト表示 | 随時利用 |

### 1.5 ユーザー種別

本システムには以下のユーザー種別があります：

| ユーザー種別 | 説明 |
|-------------|------|
| フロントエンド開発者 | HTML/JSXにユーティリティクラスを記述し、UIをスタイリングする主要ユーザー |
| デザインシステム管理者 | テーマ定義やプラグイン管理を担当。プロジェクト全体のデザインルールを統括する |
| ビルドエンジニア | ビルドツールの設定やCI/CDパイプラインへの組み込みを担当する |

### 1.6 対応環境

**実行環境：**
- Node.js（pnpm v9.6.0以上推奨）
- Rust（rustup経由、oxideバイナリのビルドに必要）

**対応ビルドツール：**
- Vite（@tailwindcss/vite プラグイン）
- webpack（@tailwindcss/webpack ローダー）
- PostCSS（@tailwindcss/postcss プラグイン）
- CLIツール（@tailwindcss/cli）
- ブラウザ実行（@tailwindcss/browser）

**対応プラットフォーム（ネイティブバイナリ）：**
- macOS（x64 / ARM64）
- Linux（x64 / ARM64 / musl）
- Windows（x64 / ARM64）
- FreeBSD（x64）
- Android（ARM64）

---

## 2. セットアップ・初期設定

### 2.1 新規プロジェクトへのインストール

**前提条件：** Node.jsがインストールされていること

1. プロジェクトのルートディレクトリで以下のコマンドを実行します

```bash
npm install tailwindcss @tailwindcss/cli
```

2. CSSエントリーポイントファイルを作成します（例：`src/input.css`）

```css
@import 'tailwindcss';
```

> **注意**: v4では`@tailwind base; @tailwind components; @tailwind utilities;` の記法は非推奨です。`@import 'tailwindcss'`を使用してください。

3. ビルドを実行してCSSを生成します

```bash
npx @tailwindcss/cli -i src/input.css -o dist/output.css
```

### 2.2 Viteプロジェクトへの統合

1. パッケージをインストールします

```bash
npm install tailwindcss @tailwindcss/vite
```

2. `vite.config.ts`にプラグインを追加します

```typescript
import tailwindcss from '@tailwindcss/vite'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [tailwindcss()],
})
```

3. CSSファイルに`@import 'tailwindcss'`を記述します

### 2.3 PostCSSプロジェクトへの統合

1. パッケージをインストールします

```bash
npm install tailwindcss @tailwindcss/postcss
```

2. `postcss.config.js`にプラグインを追加します

```javascript
module.exports = {
  plugins: {
    '@tailwindcss/postcss': {},
  },
}
```

3. CSSファイルに`@import 'tailwindcss'`を記述します

### 2.4 webpackプロジェクトへの統合

1. パッケージをインストールします

```bash
npm install tailwindcss @tailwindcss/webpack
```

2. webpack設定にローダーを追加します

### 2.5 スタンドアロンCLIの利用

Node.jsのインストールが不要なスタンドアロンバイナリも提供されています。

```bash
npx @tailwindcss/standalone -i src/input.css -o dist/output.css
```

> **ポイント**: スタンドアロンCLIはBunでバンドルされており、各プラットフォーム向けのネイティブバイナリとして配布されます。CI/CD環境やNode.jsをインストールできない環境で便利です。

---

## 3. トップページ（Playground画面）

### 3.1 Vite Playground

Vite Playgroundは、Tailwind CSS v4の`@tailwindcss/vite`プラグインが正しく動作することを検証するためのデモページです。

**アクセス方法：**
1. プロジェクトルートで開発サーバーを起動します
```bash
pnpm build && pnpm vite
```
2. ブラウザで `http://localhost:5173/` にアクセスします

**画面構成：**
- ページタイトル：「Playground」
- メインコンテンツ：Appコンポーネント（「Hello World」テキスト）
- CSSクラス使用例：`m-3`、`p-3`、`border`、`text-blue-500`

**処理の流れ：**
1. ブラウザが`index.html`をロードします
2. `main.tsx`がESモジュールとして読み込まれます
3. `index.css`の`@import 'tailwindcss'`が`@tailwindcss/vite`プラグインによりコンパイルされます
4. ReactDOMにより`<App />`コンポーネントがレンダリングされます

### 3.2 Next.js Playground

Next.js PlaygroundはApp Router構成のデモです。

**アクセス方法：**
1. 開発サーバーを起動します
```bash
pnpm build && pnpm nextjs
```
2. ブラウザでアクセスします

**特徴：**
- PostCSSプラグイン（`@tailwindcss/postcss`）を使用
- CSSモジュール経由の`@apply`ディレクティブ使用例あり（`@apply skew-7`）
- `globals.css`の`@import 'tailwindcss'`がエントリーポイント

### 3.3 V3互換 Playground

Tailwind CSS v3互換構成のNext.jsデモです。

**特徴：**
- v3形式の`@import 'tailwindcss/base'`、`@import 'tailwindcss/components'`、`@import 'tailwindcss/utilities'`を使用
- 後方互換フック（`applyCompatibilityHooks`）が自動的に適用される
- 任意値バリアント（例：`[&_h1]:font-thin`）の使用例あり

---

## 4. 【STEP1】CSS設計・テーマ定義（デザインシステムの構築）

> **業務フローでの位置**: デザインシステム管理者/フロントエンド開発者がプロジェクトのデザイントークンを定義し、テーマを構築するステップです。

### 4.1 テーマを定義する

`@theme`ディレクティブを使用して、プロジェクト固有のデザイントークンを定義します。

**操作手順：**

1. CSSエントリーポイントファイル（例：`src/input.css`）を開きます
2. `@import 'tailwindcss'`の後に`@theme`ブロックを記述します

```css
@import 'tailwindcss';

@theme {
  --color-primary: #3b82f6;
  --color-secondary: #10b981;
  --font-display: 'Inter', sans-serif;
  --spacing-section: 4rem;
}
```

3. 保存するとビルドが実行され、定義したテーマ値がCSS変数として出力されます

> **注意**: `@theme`ブロック内にはCSSカスタムプロパティ（`--`で始まる変数）または`@keyframes`ルールのみ記述できます。通常のCSSプロパティを記述するとエラーになります。

### 4.2 テーマオプションを設定する

テーマ値には以下のオプションを付与できます：

| オプション | 説明 | 用途 |
|-----------|------|------|
| INLINE | テーマ値を使用箇所にインライン展開する | パフォーマンス最適化 |
| REFERENCE | CSS変数として参照のみ（出力しない） | 内部参照用の値 |
| DEFAULT | デフォルト値として設定 | 上書き可能なベース値 |
| STATIC | 静的な値として出力 | 変更されない固定値 |

### 4.3 キーフレームアニメーションを定義する

`@theme`ブロック内で`@keyframes`を定義できます。

```css
@theme {
  @keyframes fade-in {
    from { opacity: 0; }
    to { opacity: 1; }
  }
  --animate-fade-in: fade-in 0.3s ease-in-out;
}
```

### 4.4 カスタムバリアントを定義する

`@custom-variant`ディレクティブにより、独自のバリアントを定義できます。

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

> **注意**: `@custom-variant`はネストできません。また、カスタムバリアント間に循環依存があるとエラーになります。

### 4.5 カスタムユーティリティを定義する

`@utility`ディレクティブにより、独自のユーティリティクラスを定義できます。

```css
@utility tab-4 {
  tab-size: 4;
}
```

> **注意**: `@utility`はネストできません。また、ボディ（CSSブロック）が空の場合はエラーになります。

---

## 5. 【STEP2-3】ユーティリティクラスの記述・ビルド実行（CSSの生成）

> **業務フローでの位置**: フロントエンド開発者がHTML/JSXにユーティリティクラスを記述し、ビルドツールでCSSを自動生成するステップです。

### 5.1 ユーティリティクラスの種類

Tailwind CSSのユーティリティクラスは2種類あります：

| 種類 | 説明 | 例 |
|------|------|-----|
| 静的ユーティリティ | 固定値のクラス | `flex`、`block`、`hidden`、`underline` |
| 機能的ユーティリティ | パラメータ付きのクラス | `text-red-500`、`m-4`、`p-2`、`text-3xl` |

### 5.2 基本的なクラス記述

HTML/JSXファイルにユーティリティクラスを記述します。

```html
<div class="m-3 p-3 border text-blue-500 font-bold">
  Hello World
</div>
```

**処理の流れ：**
1. ファイルスキャナー（Rust製のoxide）がソースファイルからクラス名候補を抽出します
2. 候補パーサーがクラス文字列を解析します
3. ユーティリティ生成エンジンがCSSルールを生成します
4. 最終的なCSSが出力されます

### 5.3 バリアント（修飾子）の適用

バリアントを使用して条件付きスタイルを適用します。

| バリアント種別 | 例 | 説明 |
|--------------|-----|------|
| ホバー | `hover:bg-blue-700` | マウスホバー時に適用 |
| フォーカス | `focus:ring-2` | フォーカス時に適用 |
| レスポンシブ | `md:text-lg` | 画面幅がmd以上で適用 |
| ダークモード | `dark:bg-gray-800` | ダークモード時に適用 |
| グループ | `group-hover:visible` | 親要素のホバー時に適用 |

### 5.4 任意値（Arbitrary Value）の使用

角括弧記法で任意のCSS値を指定できます。

```html
<div class="text-[14px] bg-[#1da1f2] p-[5px_10px]">
  カスタム値の例
</div>
```

### 5.5 モディファイアの使用

ユーティリティにモディファイア（透明度等）を付与できます。

```html
<div class="bg-red-500/50">
  透明度50%の赤背景
</div>
```

### 5.6 @applyディレクティブの使用

既存のユーティリティクラスをカスタムCSS内で適用できます。

```css
.btn-primary {
  @apply bg-blue-500 text-white font-bold py-2 px-4 rounded;
}
```

> **注意**: `@keyframes`内での`@apply`の使用はエラーになります。また、循環依存が検出された場合もエラーとなります。

### 5.7 CLIでのビルド実行

**基本的なビルド：**

```bash
npx @tailwindcss/cli -i src/input.css -o dist/output.css
```

**watchモード（ファイル変更監視）：**

```bash
npx @tailwindcss/cli -i src/input.css -o dist/output.css --watch
```

> **ポイント**: watchモードでは、ファイル変更を検知して自動的にリビルドが実行されます。入力CSSやプラグイン・設定ファイルが変更された場合はフルリビルド、それ以外のソースファイル変更時は差分スキャンによるインクリメンタルリビルドが実行されます。

**CLIオプション一覧：**

| オプション | 短縮形 | 説明 |
|-----------|--------|------|
| `--input` | `-i` | 入力CSSファイルパス。未指定時は`@import 'tailwindcss'`をデフォルト入力として使用 |
| `--output` | `-o` | 出力先ファイルパス。未指定時はstdoutに出力 |
| `--watch` | `-w` | ファイル変更監視モード。`--watch=always`でstdin閉鎖時も継続 |
| `--minify` | `-m` | CSS最適化+ミニファイを実行 |
| `--optimize` | | ミニファイなしの最適化のみ実行 |
| `--cwd` | | 作業ディレクトリの指定 |
| `--map` | | ソースマップ生成。値なしでインライン、パス指定で外部ファイル |
| `--help` | `-h` | ヘルプ表示 |

### 5.8 ソースファイルのスキャン対象指定

`@source`ディレクティブでスキャン対象を指定できます。

```css
@import 'tailwindcss';
@source "./src/**/*.{html,js,jsx,tsx}";
```

`@source not`で除外パターンも指定できます。

```css
@source not "./src/legacy/**";
```

> **注意**: `@source`ディレクティブにはボディ（CSSブロック）を持たせることはできません。また、パスは引用符で囲む必要があります。

---

## 6. 【STEP3-4】ファイル管理・ビルドツール統合（開発環境の連携）

> **業務フローでの位置**: ビルドエンジニア/フロントエンド開発者がビルドツールとTailwind CSSを統合し、開発環境を構築するステップです。

### 6.1 Viteプラグインの設定

**基本設定：**

`vite.config.ts`で`@tailwindcss/vite`プラグインを登録します。

```typescript
import tailwindcss from '@tailwindcss/vite'
import react from '@vitejs/plugin-react'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [react(), tailwindcss()],
})
```

**動作の仕組み：**
1. Viteの開発サーバー起動時にプラグインが初期化されます
2. CSSファイルのインポート時に`compile()`関数でコンパイルが実行されます
3. HMR（ホットモジュールリプレース）により、ファイル変更がリアルタイムに反映されます
4. 本番ビルド時にはCSS最適化も自動で実行されます

> **ポイント**: Viteプラグインはキャッシュ機構（QuickLRU）を備えており、同じコンパイラインスタンスを再利用することでビルド性能が向上します。

### 6.2 PostCSSプラグインの設定

**基本設定：**

`postcss.config.js`に`@tailwindcss/postcss`を追加します。

```javascript
module.exports = {
  plugins: {
    '@tailwindcss/postcss': {},
  },
}
```

**動作の仕組み：**
1. PostCSSビルドパイプライン内でTailwind CSSのコンパイルが実行されます
2. ファイル依存関係がPostCSSメッセージとして通知され、変更時の再ビルドが可能になります
3. Lightning CSSによるCSS最適化も統合されています

### 6.3 webpackローダーの設定

`@tailwindcss/webpack`ローダーをwebpack設定に追加します。CSSファイルの変換・候補スキャン・ユーティリティ生成を担当します。

### 6.4 @importディレクティブの管理

CSSファイル間の依存関係は`@import`で管理します。

```css
@import 'tailwindcss';
@import './custom-base.css';
@import './components.css';
```

**処理の流れ：**
1. `substituteAtImports`関数が`@import`ディレクティブを検出します
2. 外部CSSファイルを再帰的に読み込みます
3. 読み込んだCSSをAST内にインライン展開します

> **注意**: `@reference`ディレクティブを使用すると、スタイル定義を参照のみ（出力には含めない）でインポートできます。

### 6.5 ブラウザでのリアルタイムコンパイル

`@tailwindcss/browser`パッケージにより、ビルドステップなしでブラウザ上でTailwind CSSをリアルタイムにコンパイルできます。

**特徴：**
- DOMの`class`属性変更を監視
- 動的にユーティリティCSSを生成・注入
- プロトタイピングや簡易デモに最適

---

## 7. 【STEP4-5】CSS最適化・本番デプロイ（リリース準備）

> **業務フローでの位置**: ビルドエンジニアがCSS出力を最適化し、本番環境へのデプロイを準備するステップです。

### 7.1 CSSの最適化

**CLIでの最適化：**

```bash
npx @tailwindcss/cli -i src/input.css -o dist/output.css --minify
```

| オプション | 動作 |
|-----------|------|
| `--minify` | CSS最適化 + ミニファイ（サイズ削減） |
| `--optimize` | ミニファイなしの最適化のみ（可読性維持） |

**最適化の内容：**
- Lightning CSSによるネスティング解除
- メディアクエリの最適化
- 隣接ルールの結合
- 未使用CSS変数の除去（`Theme.markUsedVariable()`による使用検出）
- AST最適化（重複排除・マージ・不要ルール除去）

### 7.2 ソースマップの生成

デバッグ用のソースマップを生成できます。

**インラインソースマップ：**
```bash
npx @tailwindcss/cli -i src/input.css -o dist/output.css --map
```

**外部ソースマップファイル：**
```bash
npx @tailwindcss/cli -i src/input.css -o dist/output.css --map dist/output.css.map
```

> **注意**: `--map`の値に`-`（ダッシュ）は指定できません。インラインソースマップの場合は値なしの`--map`を使用してください。

### 7.3 ポリフィルの設定

レガシーブラウザへの対応として、ポリフィルを有効化できます。

| ポリフィル | 説明 |
|-----------|------|
| `AtProperty` | `@property`ルールのフォールバックCSS生成 |
| `ColorMix` | `color-mix()`関数のフォールバック処理 |

### 7.4 本番ビルドの実行

**推奨ビルドコマンド：**

```bash
npx @tailwindcss/cli -i src/input.css -o dist/output.css --minify
```

**ビルド結果の確認：**
- 出力ファイルサイズの確認（最適化前後の比較）
- ビルド時間の確認（CLIが処理時間を表示）
- ソースマップの正常性確認（デバッグツールでの動作検証）

---

## 8. プラグインシステム

### 8.1 プラグインの作成

`createPlugin` APIを使用してカスタムプラグインを作成します。

```javascript
const plugin = require('tailwindcss/plugin')

module.exports = plugin(function({ addUtilities, matchUtilities, addVariant, matchVariant, addBase, addComponents }) {
  addUtilities({
    '.content-auto': {
      'content-visibility': 'auto',
    },
  })
})
```

**利用可能なAPI：**

| API | 説明 |
|-----|------|
| `addUtilities` | 静的ユーティリティの追加 |
| `matchUtilities` | 動的ユーティリティの追加 |
| `addVariant` | 静的バリアントの追加 |
| `matchVariant` | 動的バリアントの追加 |
| `addBase` | ベーススタイルの追加 |
| `addComponents` | コンポーネントスタイルの追加 |

### 8.2 プラグインオプションの定義

`withOptions`パターンでオプション付きプラグインを作成できます。

```javascript
const plugin = require('tailwindcss/plugin')

module.exports = plugin.withOptions(function(options = {}) {
  return function({ addUtilities }) {
    // optionsを使用したカスタマイズ
  }
})
```

### 8.3 プラグインの登録

CSSファイル内で`@plugin`ディレクティブを使用してプラグインを登録します。

> **注意**: v4ではJavaScript設定ファイル（`tailwind.config.js`）ではなく、CSS内でのプラグイン登録が推奨されます。

---

## 9. v3互換モード・マイグレーション

### 9.1 v3からv4への自動マイグレーション

`@tailwindcss/upgrade`ツールで自動マイグレーションを実行します。

**操作手順：**

1. Git作業ディレクトリの変更をすべてコミットします

> **注意**: 未コミットの変更があるとエラーになります。

2. マイグレーションコマンドを実行します

```bash
npx @tailwindcss/upgrade
```

3. マイグレーションツールが以下を自動変換します：
   - CSS：`@tailwind`ディレクティブを`@import 'tailwindcss'`形式に変換
   - テンプレート：非推奨クラス名をv4形式に更新
   - JavaScript設定：`tailwind.config.js`をCSS設定形式に変換
   - PostCSS設定：プラグイン設定を更新
   - 依存パッケージ：`package.json`の関連パッケージを自動更新

4. マイグレーション結果を確認し、必要に応じて手動で調整します

### 9.2 v3互換モードの利用

v4環境でv3の設定・プラグインを使用する場合、互換レイヤーが自動的に適用されます。

**対応する互換機能：**

| 機能 | 説明 |
|------|------|
| `@plugin`ディレクティブ | v3形式のJSプラグインの読み込み |
| `@config`ディレクティブ | v3形式の設定ファイルの読み込み |
| ダークモード設定 | `media`/`class`/`selector`/`variant`戦略のサポート |
| screens設定 | v3のscreens設定をv4のレスポンシブバリアントに変換 |
| containerプラグイン | v3のcontainerプラグイン設定の変換 |
| レガシーユーティリティ | v3固有のユーティリティ（container等）の登録 |

### 9.3 theme()関数の使用

CSS内でテーマ変数を参照する`theme()`関数を使用できます。v3互換のlegacy形式とv4のネイティブ形式の両方に対応しています。

```css
.element {
  color: theme('colors.blue.500');
  padding: theme('spacing.4');
}
```

---

## 10. IntelliSense・開発支援機能

### 10.1 クラスリスト取得（IDE補完）

`getClassList()`関数により、利用可能な全ユーティリティクラスとその修飾子情報のリストを取得できます。IDE拡張機能（Tailwind CSS IntelliSense for VS Code等）がこのAPIを使用して補完候補を表示します。

### 10.2 バリアントリスト取得

`getVariants()`関数により、利用可能な全バリアントのリストを取得できます。

### 10.3 候補からCSSプレビュー

`candidatesToCss()`関数により、候補クラス名から生成されるCSSをプレビュー表示できます。

### 10.4 エラー報告・診断

コンパイルエラーやバリデーションエラーは、ソースファイル・行・列情報を含むわかりやすい形式で報告されます。

**主なエラーメッセージ：**

| エラー内容 | メッセージ例 |
|-----------|-------------|
| loadModule未設定 | `No 'loadModule' function provided to 'compile'` |
| @utilityのネスト | `'@utility' cannot be nested.` |
| 空の@utility | `'@utility {name}' is empty.` |
| @sourceにボディあり | `'@source' cannot have a body.` |
| @sourceの引用符不足 | `'@source' paths must be quoted.` |
| カスタムバリアントの循環依存 | `Circular dependency detected in custom variants` |
| 無効なプレフィックス | `The prefix "{prefix}" is invalid.` |

---

## 11. 日常業務の流れ

本セクションでは、業務フローに沿った日常業務の流れを説明します。

```
開発業務フロー概要（再掲）
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
【STEP 1】CSS設計・テーマ定義                   → 4章参照
    ↓
【STEP 2】ユーティリティクラスの記述              → 5章参照
    ↓
【STEP 3】ビルド実行・開発サーバー起動            → 5章・6章参照
    ↓
【STEP 4】CSS最適化                             → 7章参照
    ↓
【STEP 5】デプロイ・リリース                     → 7章参照
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

### 11.1 【デザインシステム管理者】STEP1: テーマ定義

プロジェクト開始時に、デザインシステムの基盤を構築します。

**やるべきこと：**
1. CSSエントリーポイントに`@import 'tailwindcss'`を記述
2. `@theme`ブロックでプロジェクト固有のデザイントークンを定義
3. 必要に応じて`@custom-variant`でカスタムバリアントを追加
4. 必要に応じて`@utility`でカスタムユーティリティを追加

**注意点：**
- テーマ値はCSSカスタムプロパティ（`--`で始まる変数）で定義する
- 複数の`@theme`ブロックがある場合、最初の`@theme`位置に全テーマ変数が出力される

### 11.2 【フロントエンド開発者】STEP2: ユーティリティクラスの記述

コンポーネント開発時に、ユーティリティクラスでスタイリングします。

**やるべきこと：**
1. HTML/JSXの`class`属性にユーティリティクラスを記述
2. レスポンシブ対応はバリアント（`sm:`、`md:`、`lg:`等）を使用
3. インタラクション状態は`hover:`、`focus:`等のバリアントを使用
4. テーマにない値が必要な場合は任意値記法（`text-[14px]`等）を使用

**注意点：**
- `@source`ディレクティブでスキャン対象を適切に設定すること
- .gitignoreに含まれるファイルは自動的にスキャン対象から除外される

### 11.3 【フロントエンド開発者】STEP3: ビルド実行

開発中はwatchモードでリアルタイムにCSSを生成します。

**Viteプロジェクトの場合：**
```bash
npm run dev
```
ViteのHMRにより、ファイル変更がリアルタイムで反映されます。

**CLIの場合：**
```bash
npx @tailwindcss/cli -i src/input.css -o dist/output.css --watch
```

**ビルドの仕組み：**
- ファイルスキャナー（Rust製）が高速にソースファイルをスキャンします
- 変更されたファイルのみ差分スキャンされます（インクリメンタルリビルド）
- 入力CSSや設定ファイルの変更時はフルリビルドが実行されます
- 出力ファイルのみの変更はスキップされます（無限ループ防止）

### 11.4 【ビルドエンジニア】STEP4-5: 最適化・デプロイ

リリース前に本番用の最適化済みCSSを生成します。

**やるべきこと：**
1. `--minify`オプションでCSS最適化・ミニファイを実行
2. 必要に応じてソースマップを生成
3. ビルドサイズと処理時間を確認
4. デプロイパイプラインに組み込み

**コマンド例：**
```bash
npx @tailwindcss/cli -i src/input.css -o dist/output.css --minify --map dist/output.css.map
```

---

## 12. よくある質問と対処法

### 12.1 セットアップに関するQ&A

**Q: v4では`tailwind.config.js`は必要ですか？**

A: v4では原則として不要です。テーマやカスタマイズはすべてCSS内（`@theme`、`@custom-variant`、`@utility`）で定義します。ただし、v3互換モードを使用する場合は`@config`ディレクティブで読み込むことができます。

**Q: `@tailwind base; @tailwind components; @tailwind utilities;`はまだ使えますか？**

A: v4では`@import 'tailwindcss'`を使用してください。v3形式のディレクティブは互換レイヤーにより動作しますが、新規プロジェクトではv4形式を推奨します。

### 12.2 ビルドに関するQ&A

**Q: ビルドが遅いのですが、改善方法はありますか？**

A: 以下の方法で改善できます：
- `@source`ディレクティブでスキャン対象を必要最小限に絞る
- watchモードのインクリメンタルリビルドを活用する
- Viteプラグインのキャッシュ機構を活用する

**Q: watchモードで変更が反映されません。**

A: 以下を確認してください：
- 変更したファイルが`@source`のスキャン対象に含まれているか
- `.gitignore`で除外されていないか
- 入力ファイルと出力ファイルが同じパスになっていないか

**Q: `--input`と`--output`に同じファイルを指定するとどうなりますか？**

A: エラーになります。入力と出力は必ず別のファイルパスを指定してください。

### 12.3 スタイリングに関するQ&A

**Q: @applyで循環依存エラーが発生します。**

A: `@utility`定義内や`@apply`チェーンで循環参照が発生しています。依存関係を確認し、循環を解消してください。

**Q: prefixを設定している場合の@applyの注意点は？**

A: prefix設定時は、`@apply`内でもprefixを付けたクラス名を使用する必要があります。prefixなしのクラスを使用するとエラーになります。

---

## 13. トラブルシューティング

### 13.1 エラーメッセージと対処法

| エラーメッセージ | 原因 | 対処法 |
|----------------|------|--------|
| `No 'loadModule' function provided to 'compile'` | プラグイン/設定の読み込みにloadModule関数が必要 | ビルドツール統合（Vite/PostCSS/webpack/CLI）経由で使用してください |
| `No 'loadStylesheet' function provided to 'compile'` | @importの解決にloadStylesheet関数が必要 | ビルドツール統合経由で使用してください |
| `'@utility' cannot be nested.` | @utilityがネストされた位置に記述されている | @utilityをトップレベルに移動してください |
| `'@utility {name}' is empty.` | @utilityブロックの中身が空 | CSSプロパティを記述してください |
| `'@source' cannot have a body.` | @sourceにCSSブロックが付与されている | @sourceはパス指定のみで使用してください |
| `'@source' paths must be quoted.` | @sourceのパスが引用符で囲まれていない | パスを引用符で囲んでください（例: `@source "./src/**/*"`) |
| `'@custom-variant' cannot be nested.` | @custom-variantがネストされた位置に記述されている | トップレベルに移動してください |
| `'@theme' blocks must only contain custom properties or '@keyframes'.` | @themeブロックに通常のCSSプロパティが含まれている | `--`で始まるカスタムプロパティまたは@keyframesのみ記述してください |
| `Circular dependency detected in custom variants` | カスタムバリアント間に循環依存がある | 依存関係を見直し、循環を解消してください |
| `The prefix "{prefix}" is invalid.` | プレフィックスが不正な形式 | 小文字アルファベットのみのプレフィックスを使用してください |
| `CssSyntaxError` | CSS構文エラー | エラーメッセージに含まれるファイル・行・列情報を参照し、構文を修正してください |

### 13.2 よくあるトラブルと解決方法

**スタイルが適用されない場合：**
1. CSSエントリーポイントに`@import 'tailwindcss'`が記述されているか確認
2. ビルドツール（Vite/PostCSS/webpack/CLI）が正しく設定されているか確認
3. `@source`ディレクティブのパターンが正しいか確認
4. ブラウザの開発者ツールでCSSが読み込まれているか確認

**ビルドが無限ループする場合：**
- CLIのwatchモードでは、出力ファイルのみの変更は自動的にスキップされます
- 入力ファイルと出力ファイルが同じディレクトリにあり、スキャン対象に含まれていないか確認してください

**マイグレーションエラーの場合：**
1. Git作業ディレクトリの変更がすべてコミットされているか確認
2. Tailwind CSSのバージョンが期待値と一致しているか確認
3. エラーメッセージのコンテキスト情報を確認し、該当箇所を手動で修正

### 13.3 サポートへの連絡方法

- GitHub Issues: https://github.com/tailwindlabs/tailwindcss/issues
- 公式ドキュメント: https://tailwindcss.com/docs

問題が発生した場合は、以下の情報を添えてIssueを作成してください：
- Tailwind CSSのバージョン
- 使用しているビルドツールとバージョン
- OS・Node.jsのバージョン
- 再現手順
- エラーメッセージの全文

---

## 改訂履歴

| 版数 | 改訂日 | 改訂内容 |
|-----|--------|---------|
| 1.0 | 2026-03-01 | 初版作成 |

---

*本マニュアルは、Tailwind CSS v4のエンドユーザー（開発者）向け業務運用マニュアルです。*
*システムの更新により、コマンドや設定方法が変更される場合があります。*
