# API設計書

## 概要

本ドキュメントは、Tailwind CSS v4.2.1 が提供するJavaScript/TypeScript APIの設計書です。Tailwind CSSはHTTP APIを持たないCSSフレームワーク/ビルドツールであるため、本設計書ではNode.jsモジュールとして公開されているプログラマティックAPI（コンパイルAPI、プラグインAPI、ユーティリティAPI、CLI）を対象としています。

## 共通仕様

### ベースURL

```
該当なし（HTTPサーバーではなく、Node.jsライブラリとして利用）
```

### パッケージ構成

| パッケージ名 | 説明 | インポート方法 |
| --- | --- | --- |
| `tailwindcss` | コアライブラリ（コンパイル・プラグイン） | `import { compile } from 'tailwindcss'` |
| `@tailwindcss/node` | Node.js向け拡張API | `import { compile, optimize } from '@tailwindcss/node'` |
| `@tailwindcss/browser` | ブラウザ向け自動コンパイル | `<script src="@tailwindcss/browser">` |
| `@tailwindcss/cli` | CLIツール | `npx @tailwindcss/cli` |
| `tailwindcss/plugin` | プラグインAPI | `import plugin from 'tailwindcss/plugin'` |
| `tailwindcss/colors` | カラーパレット | `import colors from 'tailwindcss/colors'` |
| `tailwindcss/defaultTheme` | デフォルトテーマ | `import defaultTheme from 'tailwindcss/defaultTheme'` |

### 共通型定義

```typescript
// コンパイルオプション（コアパッケージ）
type CompileOptions = {
  base?: string
  from?: string
  polyfills?: Polyfills
  loadModule?: (id: string, base: string, resourceHint: 'plugin' | 'config') => Promise<{
    path: string; base: string; module: Plugin | Config
  }>
  loadStylesheet?: (id: string, base: string) => Promise<{
    path: string; base: string; content: string
  }>
}

// ポリフィルフラグ
enum Polyfills {
  None = 0,
  AtProperty = 1 << 0,  // @property ルールのフォールバック
  ColorMix = 1 << 1,    // color-mix() のフォールバック
  All = AtProperty | ColorMix,
}

// 機能検出フラグ
enum Features {
  None = 0,
  AtApply = 1 << 0,      // @apply の使用
  AtImport = 1 << 1,     // @import の使用
  JsPluginCompat = 1 << 2, // @plugin/@config の使用
  ThemeFunction = 1 << 3,  // theme() 関数の使用
  Utilities = 1 << 4,     // @tailwind utilities の使用
  Variants = 1 << 5,      // @variant の使用
  AtTheme = 1 << 6,       // @theme の使用
}
```

### 共通エラーレスポンス

| エラー種別 | 説明 |
| --- | --- |
| `Error: No 'loadModule' function provided to 'compile'` | プラグイン/設定ファイル読み込み関数が未提供 |
| `Error: No 'loadStylesheet' function provided to 'compile'` | スタイルシート読み込み関数が未提供 |
| `Error: Could not resolve '...' from '...'` | モジュール/スタイルシートの解決失敗 |
| `Error: '@utility' cannot be nested.` | `@utility` がネストされている |
| `Error: '@source' paths must be quoted.` | `@source` パスが引用符で囲まれていない |
| `Error: Circular dependency detected in custom variants` | カスタムバリアントの循環依存 |

## API一覧

| カテゴリ | API | 種別 | 説明 |
| --- | --- | --- | --- |
| コアコンパイル | `compile()` | 非同期関数 | CSS文字列をコンパイルし、ビルド関数を返す |
| コアコンパイル | `compileAst()` | 非同期関数 | AST入力をコンパイルし、AST出力のビルド関数を返す |
| コアコンパイル | `__unstable__loadDesignSystem()` | 非同期関数 | デザインシステムを読み込む（不安定API） |
| Node.js拡張 | `compile()` | 非同期関数 | ファイルシステム統合付きコンパイル |
| Node.js拡張 | `compileAst()` | 非同期関数 | ファイルシステム統合付きASTコンパイル |
| Node.js拡張 | `optimize()` | 同期関数 | LightningCSSによるCSS最適化 |
| Node.js拡張 | `toSourceMap()` | 同期関数 | ソースマップの生成・シリアライズ |
| プラグイン | `plugin()` | 関数 | プラグインの作成 |
| プラグイン | `plugin.withOptions()` | 関数 | オプション付きプラグインの作成 |
| プラグインAPI | `addBase()` | メソッド | ベーススタイルの追加 |
| プラグインAPI | `addVariant()` | メソッド | 静的バリアントの追加 |
| プラグインAPI | `matchVariant()` | メソッド | 動的バリアントの追加 |
| プラグインAPI | `addUtilities()` | メソッド | 静的ユーティリティの追加 |
| プラグインAPI | `matchUtilities()` | メソッド | 動的ユーティリティの追加 |
| プラグインAPI | `addComponents()` | メソッド | コンポーネントスタイルの追加 |
| プラグインAPI | `matchComponents()` | メソッド | 動的コンポーネントの追加 |
| プラグインAPI | `theme()` | メソッド | テーマ値の参照 |
| プラグインAPI | `config()` | メソッド | 設定値の参照 |
| プラグインAPI | `prefix()` | メソッド | クラス名プレフィックスの取得 |
| 互換エクスポート | `tailwindcss/colors` | オブジェクト | カラーパレット定義 |
| 互換エクスポート | `tailwindcss/defaultTheme` | オブジェクト | デフォルトテーマ設定 |
| 互換エクスポート | `tailwindcss/plugin` | 関数 | プラグイン作成ヘルパー |
| 互換エクスポート | `flattenColorPalette()` | 関数 | カラーパレットのフラット化 |
| CLI | `tailwindcss build` | コマンド | CSSのビルド |

## 各APIエンドポイント定義

### コアコンパイルAPI

#### 1 compile()

CSS文字列を受け取り、Tailwind CSSコンパイラを生成する。候補クラス名を渡してCSSを構築するための `build()` 関数を返す。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| パッケージ | `tailwindcss` |
| インポート | `import { compile } from 'tailwindcss'` |
| ソースファイル | `packages/tailwindcss/src/index.ts:819` |
| 種別 | 非同期関数 |

**シグネチャ**

```typescript
async function compile(
  css: string,
  opts?: CompileOptions
): Promise<{
  sources: { base: string; pattern: string; negated: boolean }[]
  root: null | 'none' | { base: string; pattern: string }
  features: Features
  build(candidates: string[]): string
  buildSourceMap(): DecodedSourceMap
}>
```

**パラメータ**

| パラメータ名 | 型 | 必須 | デフォルト | 説明 |
| --- | --- | --- | --- | --- |
| css | `string` | ○ | - | 入力CSS文字列（`@import "tailwindcss"` 等を含む） |
| opts | `CompileOptions` | - | `{}` | コンパイルオプション |
| opts.base | `string` | - | `''` | ファイル解決のベースディレクトリ |
| opts.from | `string` | - | `undefined` | ソースマップ用の入力ファイルパス |
| opts.polyfills | `Polyfills` | - | `Polyfills.None` | 有効にするポリフィル |
| opts.loadModule | `function` | - | throws | プラグイン/設定ファイルの読み込み関数 |
| opts.loadStylesheet | `function` | - | throws | スタイルシートの読み込み関数 |

**戻り値**

```json
{
  "sources": [
    { "base": "/project", "pattern": "./src/**/*.{html,js,ts,jsx,tsx}", "negated": false }
  ],
  "root": null,
  "features": 20,
  "build": "function(candidates: string[]): string",
  "buildSourceMap": "function(): DecodedSourceMap"
}
```

| フィールド名 | 型 | 説明 |
| --- | --- | --- |
| sources | `{ base: string; pattern: string; negated: boolean }[]` | `@source` で定義されたスキャン対象パス一覧 |
| root | `null \| 'none' \| { base: string; pattern: string }` | `source()` で指定されたルートパス |
| features | `Features` | 検出された機能のビットフラグ |
| build | `(candidates: string[]) => string` | 候補クラス名からCSSを生成する関数 |
| buildSourceMap | `() => DecodedSourceMap` | ソースマップを生成する関数 |

**使用例**

```typescript
import { compile } from 'tailwindcss'

const compiler = await compile(`
  @import "tailwindcss";
  @theme {
    --color-primary: #3490dc;
  }
`, {
  base: '/project',
  loadStylesheet: async (id, base) => ({
    path: id,
    base,
    content: '/* stylesheet content */'
  })
})

// 候補クラスを渡してCSSを生成
const css = compiler.build(['flex', 'items-center', 'text-primary'])
```

---

#### 2 compileAst()

AST（抽象構文木）入力をコンパイルし、AST出力のビルド関数を返す。`compile()` のAST版。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| パッケージ | `tailwindcss` |
| インポート | `import { compileAst } from 'tailwindcss'` |
| ソースファイル | `packages/tailwindcss/src/index.ts:709` |
| 種別 | 非同期関数 |

**シグネチャ**

```typescript
async function compileAst(
  input: AstNode[],
  opts?: CompileOptions
): Promise<{
  sources: { base: string; pattern: string; negated: boolean }[]
  root: null | 'none' | { base: string; pattern: string }
  features: Features
  build(candidates: string[]): AstNode[]
}>
```

**パラメータ**

| パラメータ名 | 型 | 必須 | デフォルト | 説明 |
| --- | --- | --- | --- | --- |
| input | `AstNode[]` | ○ | - | 入力AST配列 |
| opts | `CompileOptions` | - | `{}` | コンパイルオプション（`compile()`と同一） |

**戻り値**

| フィールド名 | 型 | 説明 |
| --- | --- | --- |
| sources | `{ base: string; pattern: string; negated: boolean }[]` | スキャン対象パス一覧 |
| root | `null \| 'none' \| { base: string; pattern: string }` | ルートパス |
| features | `Features` | 検出された機能のビットフラグ |
| build | `(candidates: string[]) => AstNode[]` | 候補からASTを生成する関数 |

---

#### 3 __unstable__loadDesignSystem()

CSS文字列からデザインシステムオブジェクトを読み込む。不安定APIであり、将来のバージョンで変更される可能性がある。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| パッケージ | `tailwindcss` |
| インポート | `import { __unstable__loadDesignSystem } from 'tailwindcss'` |
| ソースファイル | `packages/tailwindcss/src/index.ts:857` |
| 種別 | 非同期関数（不安定） |

**シグネチャ**

```typescript
async function __unstable__loadDesignSystem(
  css: string,
  opts?: CompileOptions
): Promise<DesignSystem>
```

**パラメータ**

| パラメータ名 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| css | `string` | ○ | 入力CSS文字列 |
| opts | `CompileOptions` | - | コンパイルオプション |

---

### Node.js拡張API（@tailwindcss/node）

#### 4 compile()（Node.js版）

コアの `compile()` をNode.jsファイルシステム統合で拡張したもの。モジュール解決、ファイル監視、URL書き換え機能を含む。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| パッケージ | `@tailwindcss/node` |
| インポート | `import { compile } from '@tailwindcss/node'` |
| ソースファイル | `packages/@tailwindcss-node/src/compile.ts:100` |
| 種別 | 非同期関数 |

**シグネチャ**

```typescript
async function compile(
  css: string,
  options: CompileOptions
): Promise<{
  sources: { base: string; pattern: string; negated: boolean }[]
  root: null | 'none' | { base: string; pattern: string }
  features: Features
  build(candidates: string[]): string
  buildSourceMap(): DecodedSourceMap
}>
```

**パラメータ**

| パラメータ名 | 型 | 必須 | デフォルト | 説明 |
| --- | --- | --- | --- | --- |
| css | `string` | ○ | - | 入力CSS文字列 |
| options.base | `string` | ○ | - | ベースディレクトリパス |
| options.from | `string` | - | `undefined` | ソースマップ用の入力ファイルパス |
| options.onDependency | `(path: string) => void` | ○ | - | 依存ファイル検出時のコールバック |
| options.shouldRewriteUrls | `boolean` | - | `false` | URL書き換えの有効化 |
| options.polyfills | `Polyfills` | - | `undefined` | 有効にするポリフィル |
| options.customCssResolver | `Resolver` | - | `undefined` | カスタムCSS解決関数 |
| options.customJsResolver | `Resolver` | - | `undefined` | カスタムJS解決関数 |

**戻り値**

コアの `compile()` と同じ構造を返す（上記参照）。加えて `source()` パスの存在チェックを行う。

---

#### 5 optimize()

LightningCSSを使用してCSSを最適化する。ネスティング展開、メディアクエリ最適化、オプションの最小化を行う。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| パッケージ | `@tailwindcss/node` |
| インポート | `import { optimize } from '@tailwindcss/node'` |
| ソースファイル | `packages/@tailwindcss-node/src/optimize.ts:29` |
| 種別 | 同期関数 |

**シグネチャ**

```typescript
function optimize(
  input: string,
  options?: OptimizeOptions
): TransformResult
```

**パラメータ**

| パラメータ名 | 型 | 必須 | デフォルト | 説明 |
| --- | --- | --- | --- | --- |
| input | `string` | ○ | - | 入力CSS文字列 |
| options.file | `string` | - | `'input.css'` | 変換対象のファイル名 |
| options.minify | `boolean` | - | `false` | 最小化の有効化 |
| options.map | `string` | - | `undefined` | 入力ソースマップ |

**戻り値**

```json
{
  "code": "/* 最適化されたCSS */",
  "map": "/* ソースマップJSON文字列 */"
}
```

| フィールド名 | 型 | 説明 |
| --- | --- | --- |
| code | `string` | 最適化されたCSS文字列 |
| map | `string \| undefined` | ソースマップ（入力マップが提供された場合） |

**ブラウザターゲット**

| ブラウザ | 最低バージョン |
| --- | --- |
| Safari | 16.4 |
| iOS Safari | 16.4 |
| Firefox | 128 |
| Chrome | 111 |

---

#### 6 toSourceMap()

デコードされたソースマップをシリアライズし、インラインまたは外部参照用のソースマップオブジェクトを返す。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| パッケージ | `@tailwindcss/node` |
| インポート | `import { toSourceMap } from '@tailwindcss/node'` |
| ソースファイル | `packages/@tailwindcss-node/src/source-maps.ts:45` |
| 種別 | 同期関数 |

**シグネチャ**

```typescript
function toSourceMap(map: DecodedSourceMap | string): SourceMap
```

**パラメータ**

| パラメータ名 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| map | `DecodedSourceMap \| string` | ○ | デコードされたソースマップまたはJSON文字列 |

**戻り値**

| フィールド名 | 型 | 説明 |
| --- | --- | --- |
| raw | `string` | ソースマップのJSON文字列 |
| inline | `string` | Base64エンコードされたインラインソースマップコメント |
| comment | `(url: string) => string` | 外部ファイル参照用のコメント生成関数 |

---

### プラグインAPI

#### 7 plugin()

Tailwind CSSプラグインを作成する。プラグインはカスタムユーティリティ、バリアント、コンポーネント、ベーススタイルを追加できる。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| パッケージ | `tailwindcss/plugin` |
| インポート | `import plugin from 'tailwindcss/plugin'` |
| ソースファイル | `packages/tailwindcss/src/plugin.ts:12` |
| 種別 | 関数 |

**シグネチャ**

```typescript
function plugin(
  handler: (api: PluginAPI) => void,
  config?: Partial<UserConfig>
): PluginWithConfig
```

**パラメータ**

| パラメータ名 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| handler | `(api: PluginAPI) => void` | ○ | プラグインハンドラー関数 |
| config | `Partial<UserConfig>` | - | プラグインが追加するデフォルト設定 |

**使用例**

```typescript
import plugin from 'tailwindcss/plugin'

export default plugin(function({ addUtilities, theme }) {
  addUtilities({
    '.scrollbar-none': {
      'scrollbar-width': 'none',
      '&::-webkit-scrollbar': {
        display: 'none'
      }
    }
  })
})
```

---

#### 8 plugin.withOptions()

オプションを受け取るプラグインを作成する。各プロジェクトでオプションをカスタマイズ可能。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| パッケージ | `tailwindcss/plugin` |
| インポート | `import plugin from 'tailwindcss/plugin'` |
| ソースファイル | `packages/tailwindcss/src/plugin.ts:19` |
| 種別 | 関数 |

**シグネチャ**

```typescript
plugin.withOptions<T>(
  pluginFunction: (options?: T) => (api: PluginAPI) => void,
  configFunction?: (options?: T) => Partial<UserConfig>
): PluginWithOptions<T>
```

**パラメータ**

| パラメータ名 | 型 | 必須 | デフォルト | 説明 |
| --- | --- | --- | --- | --- |
| pluginFunction | `(options?: T) => PluginFn` | ○ | - | オプションを受け取り、プラグインハンドラーを返す関数 |
| configFunction | `(options?: T) => Partial<Config>` | - | `() => ({})` | オプションに基づく追加設定を返す関数 |

**使用例**

```typescript
import plugin from 'tailwindcss/plugin'

export default plugin.withOptions<{ prefix?: string }>(
  (options = {}) => ({ addUtilities }) => {
    const prefix = options.prefix ?? 'tw'
    addUtilities({
      [`.${prefix}-container`]: { width: '100%', maxWidth: '1200px', margin: '0 auto' }
    })
  },
  (options = {}) => ({
    theme: { extend: {} }
  })
)
```

---

#### 9 PluginAPI.addBase()

ベーススタイル（`@layer base` 相当）を追加する。リセットやグローバルスタイルの登録に使用。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| 提供元 | `PluginAPI` オブジェクト |
| ソースファイル | `packages/tailwindcss/src/compat/plugin-api.ts:109` |
| 種別 | メソッド |

**シグネチャ**

```typescript
addBase(base: CssInJs): void
```

**パラメータ**

| パラメータ名 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| base | `CssInJs` | ○ | CSS-in-JSオブジェクト |

**使用例**

```typescript
addBase({
  'h1': { fontSize: '2rem', fontWeight: 'bold' },
  'h2': { fontSize: '1.5rem', fontWeight: 'bold' },
})
```

---

#### 10 PluginAPI.addVariant()

静的バリアント（`hover:`, `focus:` のようなもの）を登録する。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| 提供元 | `PluginAPI` オブジェクト |
| ソースファイル | `packages/tailwindcss/src/compat/plugin-api.ts:120` |
| 種別 | メソッド |

**シグネチャ**

```typescript
addVariant(
  name: string,
  variant: string | string[] | CssInJs
): void
```

**パラメータ**

| パラメータ名 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| name | `string` | ○ | バリアント名（英数字、ハイフン、アンダースコアのみ、小文字で開始） |
| variant | `string \| string[] \| CssInJs` | ○ | セレクタ文字列、セレクタ配列、またはCSS-in-JSオブジェクト |

**バリデーション**

- バリアント名は `/^[a-z0-9][a-zA-Z0-9_-]*$/` にマッチする必要がある
- `:merge(…)` を含むバリアントは無視される（v4自動合成のため）

**使用例**

```typescript
addVariant('hocus', ['&:hover', '&:focus'])
addVariant('not-first', '&:not(:first-child)')
```

---

#### 11 PluginAPI.matchVariant()

動的なバリアントを登録する。値を受け取ってセレクタを生成するバリアント。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| 提供元 | `PluginAPI` オブジェクト |
| ソースファイル | `packages/tailwindcss/src/compat/plugin-api.ts:161` |
| 種別 | メソッド |

**シグネチャ**

```typescript
matchVariant<T = string>(
  name: string,
  cb: (value: T | string, extra: { modifier: string | null }) => string | string[],
  options?: {
    values?: Record<string, T>
    sort?: (
      a: { value: T | string; modifier: string | null },
      b: { value: T | string; modifier: string | null }
    ) => number
  }
): void
```

**パラメータ**

| パラメータ名 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| name | `string` | ○ | バリアント名 |
| cb | `function` | ○ | 値からセレクタを生成するコールバック |
| options.values | `Record<string, T>` | - | プリセット値のマッピング |
| options.sort | `function` | - | バリアントのソート関数 |

**使用例**

```typescript
matchVariant('data', (value) => `&[data-${value}]`, {
  values: { checked: 'checked', disabled: 'disabled' }
})
// 使用: data-checked:bg-green-500, data-[custom]:text-red-500
```

---

#### 12 PluginAPI.addUtilities()

静的ユーティリティクラスを登録する。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| 提供元 | `PluginAPI` オブジェクト |
| ソースファイル | `packages/tailwindcss/src/compat/plugin-api.ts:266` |
| 種別 | メソッド |

**シグネチャ**

```typescript
addUtilities(
  utilities: Record<string, CssInJs | CssInJs[]> | Record<string, CssInJs | CssInJs[]>[],
  options?: {}
): void
```

**パラメータ**

| パラメータ名 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| utilities | `Record<string, CssInJs>` or array | ○ | ユーティリティ定義オブジェクト |
| options | `{}` | - | 予約済み（現在未使用） |

**バリデーション**

- クラスセレクタは `.` で始まり、小文字英字で開始する必要がある
- `@keyframes` ルールも含めることができる

**使用例**

```typescript
addUtilities({
  '.content-auto': { 'content-visibility': 'auto' },
  '.content-hidden': { 'content-visibility': 'hidden' },
  '.content-visible': { 'content-visibility': 'visible' },
})
```

---

#### 13 PluginAPI.matchUtilities()

動的な値を受け取るユーティリティを登録する。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| 提供元 | `PluginAPI` オブジェクト |
| ソースファイル | `packages/tailwindcss/src/compat/plugin-api.ts:350` |
| 種別 | メソッド |

**シグネチャ**

```typescript
matchUtilities(
  utilities: Record<string, (value: string, extra: { modifier: string | null }) => CssInJs | CssInJs[]>,
  options?: Partial<{
    type: string | string[]
    supportsNegativeValues: boolean
    values: Record<string, string>
    modifiers: 'any' | Record<string, string>
  }>
): void
```

**パラメータ**

| パラメータ名 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| utilities | `Record<string, function>` | ○ | ユーティリティ名と値からCSSを返す関数のマッピング |
| options.type | `string \| string[]` | - | 受け入れるデータ型（`'color'`, `'length'`, `'any'` 等） |
| options.supportsNegativeValues | `boolean` | - | 負の値のサポート |
| options.values | `Record<string, string>` | - | プリセット値のマッピング |
| options.modifiers | `'any' \| Record<string, string>` | - | モディファイア定義 |

**データ型**

| 型名 | 説明 |
| --- | --- |
| `'any'` | 任意の値を受け入れ |
| `'color'` | カラー値（`inherit`, `transparent`, `currentcolor` を暗黙サポート） |
| `'length'` | 長さの値 |
| その他 | CSS Data Types に準拠 |

**使用例**

```typescript
matchUtilities(
  {
    'tab': (value) => ({ tabSize: value }),
  },
  {
    type: ['length', 'any'],
    values: { 1: '1', 2: '2', 4: '4', 8: '8' },
  }
)
// 使用: tab-4, tab-[16], tab-[2rem]
```

---

#### 14 PluginAPI.addComponents()

コンポーネントスタイルを追加する。内部的には `addUtilities()` のエイリアス。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| 提供元 | `PluginAPI` オブジェクト |
| ソースファイル | `packages/tailwindcss/src/compat/plugin-api.ts:512` |
| 種別 | メソッド（`addUtilities()` のエイリアス） |

**シグネチャ**

```typescript
addComponents(
  utilities: Record<string, CssInJs> | Record<string, CssInJs>[],
  options?: {}
): void
```

---

#### 15 PluginAPI.matchComponents()

動的コンポーネントスタイルを追加する。内部的には `matchUtilities()` のエイリアス。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| 提供元 | `PluginAPI` オブジェクト |
| ソースファイル | `packages/tailwindcss/src/compat/plugin-api.ts:516` |
| 種別 | メソッド（`matchUtilities()` のエイリアス） |

---

#### 16 PluginAPI.theme()

テーマ設定から値を取得する。ドット区切りのパスでネストされた値にアクセスできる。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| 提供元 | `PluginAPI` オブジェクト |
| ソースファイル | `packages/tailwindcss/src/compat/plugin-api.ts:520` |
| 種別 | メソッド |

**シグネチャ**

```typescript
theme(path: string, defaultValue?: any): any
```

**パラメータ**

| パラメータ名 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| path | `string` | ○ | テーマパス（例: `'colors.blue.500'`, `'spacing'`） |
| defaultValue | `any` | - | パスが存在しない場合のデフォルト値 |

---

#### 17 PluginAPI.config()

解決済み設定から値を取得する。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| 提供元 | `PluginAPI` オブジェクト |
| ソースファイル | `packages/tailwindcss/src/compat/plugin-api.ts:530` |
| 種別 | メソッド |

**シグネチャ**

```typescript
config(path?: string, defaultValue?: any): any
```

**パラメータ**

| パラメータ名 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| path | `string` | - | 設定パス（省略時はルート設定オブジェクト全体） |
| defaultValue | `any` | - | パスが存在しない場合のデフォルト値 |

---

### 互換エクスポートAPI

#### 18 tailwindcss/colors

Tailwind CSSの全カラーパレットをエクスポートする。v3互換のカラー定義。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| パッケージ | `tailwindcss/colors` |
| インポート | `import colors from 'tailwindcss/colors'` |
| ソースファイル | `packages/tailwindcss/src/compat/colors.ts` |
| 種別 | デフォルトエクスポート（オブジェクト） |

**戻り値の構造**

```json
{
  "inherit": "inherit",
  "current": "currentcolor",
  "transparent": "transparent",
  "black": "#000",
  "white": "#fff",
  "slate": {
    "50": "oklch(98.4% 0.003 247.858)",
    "100": "oklch(96.8% 0.007 247.896)",
    "...": "..."
  },
  "gray": { "...": "..." },
  "red": { "...": "..." },
  "...": "..."
}
```

**含まれるカラーグループ**

`inherit`, `current`, `transparent`, `black`, `white`, `slate`, `gray`, `zinc`, `neutral`, `stone`, `mauve`, `olive`, `mist`, `taupe`, `red`, `orange`, `amber`, `yellow`, `lime`, `green`, `emerald`, `teal`, `cyan`, `sky`, `blue`, `indigo`, `violet`, `purple`, `fuchsia`, `pink`, `rose`

各カラーグループは `50` 〜 `950` のシェードを持ち、oklch色空間で定義されている。

---

#### 19 tailwindcss/defaultTheme

デフォルトのテーマ設定をエクスポートする。カスタマイズの基盤として使用。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| パッケージ | `tailwindcss/defaultTheme` |
| インポート | `import defaultTheme from 'tailwindcss/defaultTheme'` |
| ソースファイル | `packages/tailwindcss/src/compat/default-theme.ts` |
| 種別 | デフォルトエクスポート（オブジェクト） |

**主要プロパティ**

| プロパティ | 型 | 説明 |
| --- | --- | --- |
| `screens` | `Record<string, string>` | ブレークポイント（`sm`, `md`, `lg`, `xl`, `2xl`） |
| `colors` | `function` | カラーパレット |
| `spacing` | `Record<string, string>` | スペーシングスケール |
| `fontFamily` | `Record<string, string[]>` | フォントファミリー |
| `fontSize` | `Record<string, [string, object]>` | フォントサイズ + 行の高さ |
| `borderRadius` | `Record<string, string>` | ボーダー半径 |
| `boxShadow` | `Record<string, string>` | ボックスシャドウ |
| 他多数 | - | CSSプロパティに対応するテーマ値 |

---

#### 20 flattenColorPalette()

ネストされたカラーパレットオブジェクトをフラットなキー・値マッピングに変換する。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| パッケージ | `tailwindcss/lib/util/flattenColorPalette` |
| インポート | `import flattenColorPalette from 'tailwindcss/lib/util/flattenColorPalette'` |
| ソースファイル | `packages/tailwindcss/src/compat/flatten-color-palette.ts:7` |
| 種別 | デフォルトエクスポート（関数） |

**シグネチャ**

```typescript
function flattenColorPalette(
  colors: { [key: string | number]: string | Colors }
): Record<string, string>
```

**パラメータ**

| パラメータ名 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| colors | `{ [key]: string \| Colors }` | ○ | ネストされたカラーオブジェクト |

**使用例**

```typescript
import flattenColorPalette from 'tailwindcss/lib/util/flattenColorPalette'

flattenColorPalette({
  blue: { 100: '#dbeafe', 500: '#3b82f6', DEFAULT: '#3b82f6' }
})
// => { 'blue-100': '#dbeafe', 'blue-500': '#3b82f6', 'blue': '#3b82f6' }
```

---

### ユーザー設定API

#### 21 UserConfig 型定義

ユーザー設定ファイル（`tailwind.config.js`）の型定義。v3互換の設定システム。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| パッケージ | `tailwindcss` |
| インポート | `import type { Config } from 'tailwindcss'` |
| ソースファイル | `packages/tailwindcss/src/compat/config/types.ts` |
| 種別 | 型定義 |

**設定フィールド**

| フィールド名 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| presets | `UserConfig[]` | - | プリセット設定の配列 |
| theme | `ThemeConfig` | - | テーマ設定（`extend` 含む） |
| plugins | `Plugin[]` | - | プラグインの配列 |
| content | `ContentFile[] \| { files: ContentFile[] }` | - | コンテンツスキャン設定（v3互換） |
| darkMode | `DarkModeStrategy` | - | ダークモード戦略 |
| prefix | `string` | - | クラス名のプレフィックス |
| blocklist | `string[]` | - | 除外するクラス名 |
| important | `boolean \| string` | - | `!important` フラグの設定 |
| future | `'all' \| Record<string, boolean>` | - | 将来の機能フラグ |
| experimental | `'all' \| Record<string, boolean>` | - | 実験的機能フラグ |

**DarkModeStrategy 型**

```typescript
type DarkModeStrategy =
  | false                         // ダークモード無効
  | 'media'                       // メディアクエリ戦略
  | 'class'                       // .dark クラス戦略
  | ['class', string]             // カスタムクラス戦略
  | 'selector'                    // セレクタ戦略
  | ['selector', string]          // カスタムセレクタ戦略
  | ['variant', string | string[]] // バリアント戦略
```

---

### CLIコマンド

#### 22 tailwindcss build

CSSファイルをビルドするCLIコマンド。入力CSSからTailwind CSSユーティリティを生成し、出力する。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| パッケージ | `@tailwindcss/cli` |
| ソースファイル | `packages/@tailwindcss-cli/src/index.ts` |
| 種別 | CLIコマンド |

**使用方法**

```bash
tailwindcss [--input input.css] [--output output.css] [--watch] [options…]
```

**オプション**

| オプション | エイリアス | 型 | デフォルト | 説明 |
| --- | --- | --- | --- | --- |
| `--input` | `-i` | `string` | - | 入力CSSファイルパス |
| `--output` | `-o` | `string` | `'-'`（stdout） | 出力CSSファイルパス |
| `--watch` | `-w` | `boolean \| 'always'` | `false` | ファイル変更監視モード |
| `--minify` | `-m` | `boolean` | `false` | 出力の最小化 |
| `--optimize` | - | `boolean` | `false` | 最適化のみ（最小化なし） |
| `--cwd` | - | `string` | `'.'` | カレントワーキングディレクトリ |
| `--map` | - | `boolean \| string` | - | ソースマップ生成（`true` = インライン） |
| `--help` | `-h` | `boolean` | - | ヘルプメッセージ表示 |

**使用例**

```bash
# 基本的なビルド
tailwindcss -i ./src/input.css -o ./dist/output.css

# 監視モードで最小化ビルド
tailwindcss -i ./src/input.css -o ./dist/output.css --watch --minify

# ソースマップ付きビルド
tailwindcss -i ./src/input.css -o ./dist/output.css --map
```

---

### CSSディレクティブAPI

#### 23 CSS @ルール一覧

Tailwind CSS v4で使用可能なCSSディレクティブ（at-rule）の一覧。CSSファイル内で使用し、Tailwind CSSコンパイラに指示を与える。

| ディレクティブ | 説明 | 例 |
| --- | --- | --- |
| `@import "tailwindcss"` | Tailwind CSSフレームワークのインポート | `@import "tailwindcss";` |
| `@tailwind utilities` | ユーティリティクラスの生成位置指定 | `@tailwind utilities;` |
| `@theme { ... }` | テーマ変数（CSSカスタムプロパティ）の定義 | `@theme { --color-primary: #3490dc; }` |
| `@custom-variant` | カスタムバリアントの定義 | `@custom-variant hocus (&:hover, &:focus);` |
| `@variant` | バリアントの適用 | `@variant hover { ... }` |
| `@utility` | カスタムユーティリティの定義 | `@utility scrollbar-none { scrollbar-width: none; }` |
| `@source` | クラスキャンドテート検出のソースパス指定 | `@source "./src/**/*.html";` |
| `@apply` | 既存ユーティリティの適用（後方互換） | `@apply flex items-center;` |
| `theme()` | テーマ値の参照関数 | `color: theme(colors.blue.500);` |

**@theme オプション**

| オプション | 説明 |
| --- | --- |
| `reference` | CSS変数を出力せず参照のみ |
| `inline` | インラインテーマ値 |
| `default` | デフォルト値として扱う |
| `static` | 静的テーマ値 |
| `prefix(ident)` | テーマ変数にプレフィックスを付与 |

## 備考

- Tailwind CSS v4はHTTP APIを提供しない。本設計書のAPIはすべてNode.jsモジュール/CLIとして提供される。
- v4ではCSS-firstの設定アプローチが導入されており、`@theme` ディレクティブによるCSS内での設定が推奨される。
- `tailwind.config.js` による設定はv3互換レイヤーを通じて引き続きサポートされる。
- `__unstable__loadDesignSystem()` は内部APIであり、将来のバージョンで変更・削除される可能性がある。
- ブラウザビルド（`@tailwindcss/browser`）はプラグインおよび設定ファイルをサポートしない。
- カラー値はoklch色空間で定義されており、v3のhex/rgb定義から変更されている。
