# Tailwind CSS v4 コードリーディングガイドライン

## はじめに

このガイドラインは、Tailwind CSS v4 のコードベースを効率的に理解するための手引きです。
TypeScript および Rust に精通していないエンジニアでも、段階的に学習できるよう構成されています。

Tailwind CSS v4 は **TypeScript** と **Rust** のハイブリッドモノレポ構成を採用しており、パフォーマンスクリティカルなファイルスキャン・候補抽出を Rust で実装し、ユーザー向け API・プラグインシステム・ビルドツール統合を TypeScript で実装しています。

**対象読者:**
- プロジェクトに新規参画するエンジニア
- 他言語からの経験者
- コードレビューを行う担当者

---

## 1. 言語基礎

> このセクションでは、本プロジェクトで使用される TypeScript と Rust の基本構文と概念を解説します。

### 1.1 プログラム構造

本プロジェクトは2つの言語で構成されています。

**TypeScript 側** — ESM（ES Modules）形式のモジュールシステムを採用しています。

```typescript
// ファイル: packages/tailwindcss/src/index.ts:1-36
import { version } from '../package.json'
import { substituteAtApply } from './apply'
import {
  atRoot, atRule, comment, context, decl, optimizeAst, rule, styleRule, toCss,
  type AstNode, type AtRule, type Context, type StyleRule,
} from './ast'
import { compileCandidates } from './compile'
import { buildDesignSystem, type DesignSystem } from './design-system'
export type Config = UserConfig
```

**Rust 側** — モジュールシステムは `mod` 宣言と `pub use` による再公開を採用しています。

```rust
// ファイル: crates/oxide/src/lib.rs:1-12
pub mod cursor;
pub mod extractor;
pub mod fast_skip;
pub mod glob;
pub mod paths;
pub mod scanner;
pub mod throughput;

pub use glob::GlobEntry;
pub use scanner::sources::PublicSourceEntry;
pub use scanner::ChangedContent;
pub use scanner::Scanner;
```

### 1.2 データ型と変数

**TypeScript** — `type` および `const enum` を活用した型定義が多用されています。

```typescript
// ファイル: packages/tailwindcss/src/ast.ts:13-57
export type StyleRule = {
  kind: 'rule'
  selector: string
  nodes: AstNode[]
  src?: SourceLocation
  dst?: SourceLocation
}

export type Declaration = {
  kind: 'declaration'
  property: string
  value: string | undefined
  important: boolean
}

export type AstNode = StyleRule | AtRule | Declaration | Comment | Context | AtRoot
```

ビットフラグ型の `const enum` が設定オプションに使用されます。

```typescript
// ファイル: packages/tailwindcss/src/index.ts:41-52
export const enum Polyfills {
  None = 0,
  AtProperty = 1 << 0,
  ColorMix = 1 << 1,
  All = AtProperty | ColorMix,
}
```

**Rust** — `enum` と `struct` による判別共用体パターンが多用されます。

```rust
// ファイル: crates/oxide/src/scanner/mod.rs:37-41
#[derive(Debug, Clone)]
pub enum ChangedContent {
    File(PathBuf, String),
    Content(String, String),
}
```

### 1.3 制御構造

**TypeScript** — `for...of` ループと早期リターンパターンが頻出します。

```typescript
// ファイル: packages/tailwindcss/src/compile.ts:27-40
for (let rawCandidate of rawCandidates) {
  if (designSystem.invalidCandidates.has(rawCandidate)) {
    onInvalidCandidate?.(rawCandidate)
    continue // Bail, invalid candidate
  }

  let candidates = designSystem.parseCandidate(rawCandidate)
  if (candidates.length === 0) {
    onInvalidCandidate?.(rawCandidate)
    continue // Bail, invalid candidate
  }

  matches.set(rawCandidate, candidates)
}
```

**Rust** — `match` 式と `impl From` トレイトによるパターンマッチ・型変換が基本です。

```rust
// ファイル: crates/node/src/lib.rs:44-56
impl From<ChangedContent> for tailwindcss_oxide::ChangedContent {
  fn from(changed_content: ChangedContent) -> Self {
    if let Some(file) = changed_content.file {
      return tailwindcss_oxide::ChangedContent::File(file.into(), changed_content.extension);
    }
    if let Some(contents) = changed_content.content {
      return tailwindcss_oxide::ChangedContent::Content(contents, changed_content.extension);
    }
    unreachable!()
  }
}
```

### 1.4 関数/メソッド定義

**TypeScript** — `async` 関数とオプショナルパラメータが多用されます。

```typescript
// ファイル: packages/tailwindcss/src/compile.ts:11-18
export function compileCandidates(
  rawCandidates: Iterable<string>,
  designSystem: DesignSystem,
  {
    onInvalidCandidate,
    respectImportant,
  }: { onInvalidCandidate?: (candidate: string) => void; respectImportant?: boolean } = {},
) {
```

**Rust** — `#[napi]` マクロでデコレートされた関数が JavaScript に公開されます。

```rust
// ファイル: crates/node/src/lib.rs:96-99
#[derive(Debug, Clone)]
#[napi]
pub struct Scanner {
  scanner: tailwindcss_oxide::Scanner,
}
```

### 1.5 モジュール/インポート

**TypeScript** — ESM の `import` / `export` を使用します。`workspace:*` プロトコルでモノレポ内パッケージを参照します。

```typescript
// ファイル: packages/@tailwindcss-postcss/src/index.ts:1-11
import QuickLRU from '@alloc/quick-lru'
import { compileAst, env, Features, Instrumentation, optimize as optimizeCss, Polyfills } from '@tailwindcss/node'
import { Scanner } from '@tailwindcss/oxide'
```

**Rust** — `crate::` プレフィックスで同一クレート内のモジュール、パス依存でワークスペース内クレートを参照します。

```rust
// ファイル: crates/oxide/src/scanner/mod.rs:1-13
use crate::extractor::{Extracted, Extractor};
use crate::glob::optimize_patterns;
use crate::scanner::sources::{PublicSourceEntry, SourceEntry, Sources};
use crate::GlobEntry;
use rayon::prelude::*;
```

---

## 2. プロジェクト固有の概念

> このセクションでは、Tailwind CSS v4 特有の概念を解説します。

### 2.1 フレームワーク固有の概念

#### NAPI（Node-API）ブリッジ

Rust で実装された高速スキャナーを Node.js から呼び出すために **NAPI バインディング** を使用しています。`#[napi(object)]` マクロで Rust 構造体を JavaScript オブジェクトとして公開します。

```rust
// ファイル: crates/node/src/lib.rs:8-19
#[derive(Debug, Clone)]
#[napi(object)]
pub struct ChangedContent {
  pub file: Option<String>,
  pub content: Option<String>,
  pub extension: String,
}
```

これにより TypeScript 側から以下のように使用できます:

```typescript
// @tailwindcss/oxide パッケージから Scanner をインポートして使用
import { Scanner } from '@tailwindcss/oxide'
const scanner = new Scanner({ sources: [...] })
const candidates = scanner.scan()
```

#### DesignSystem 型

コア設計概念で、テーマ・ユーティリティ・バリアントを統合管理する型です。

```typescript
// ファイル: packages/tailwindcss/src/design-system.ts:35-68
export type DesignSystem = {
  theme: Theme
  utilities: Utilities
  variants: Variants
  invalidCandidates: Set<string>
  important: boolean

  parseCandidate(candidate: string): Readonly<Candidate>[]
  parseVariant(variant: string): Readonly<Variant> | null
  compileAstNodes(candidate: Candidate, flags?: CompileAstFlags): ReturnType<typeof compileAstNodes>
  candidatesToCss(classes: string[]): (string | null)[]
  candidatesToAst(classes: string[]): AstNode[][]
}
```

#### 候補（Candidate）システム

ユーザーが書く CSS クラス名（例: `sm:hover:bg-red-500/50`）を解析する仕組みです。

```typescript
// ファイル: packages/tailwindcss/src/candidate.ts:15-65
export type ArbitraryUtilityValue = {
  kind: 'arbitrary'
  dataType: string | null  // bg-[color:var(--my-color)] の "color"
  value: string            // bg-[#0088cc] の "#0088cc"
}

export type NamedUtilityValue = {
  kind: 'named'
  value: string    // bg-red-500 の "red-500"
  fraction: string | null  // w-1/2 の "1/2"
}
```

#### ステートマシンベースの抽出器

Rust 側では合成可能なステートマシンパターンでクラス候補を抽出します。

```rust
// ファイル: crates/oxide/src/extractor/mod.rs:24-37
#[derive(Debug)]
pub enum Extracted<'a> {
    /// 有効なクラス候補（例: `flex`）
    Candidate(&'a [u8]),

    /// 有効な CSS 変数（例: `--my-variable`）
    CssVariable(&'a [u8]),
}
```

### 2.2 プロジェクト独自のパターン

#### プラグイン API

v3 互換のプラグインシステムを提供しています。

```typescript
// ファイル: packages/tailwindcss/src/plugin.ts:12-33
function createPlugin(handler: PluginFn, config?: Partial<Config>): PluginWithConfig {
  return { handler, config }
}

createPlugin.withOptions = function <T>(
  pluginFunction: (options?: T) => PluginFn,
  configFunction: (options?: T) => Partial<Config> = () => ({}),
): PluginWithOptions<T> {
  function optionsFunction(options: T): PluginWithConfig {
    return {
      handler: pluginFunction(options),
      config: configFunction(options),
    }
  }
  optionsFunction.__isOptionsFunction = true as const
  return optionsFunction as PluginWithOptions<T>
}
```

#### LRU キャッシュパターン

PostCSS・Webpack プラグインではビルドのたびにコンパイラを再生成するのを避けるため、LRU キャッシュを使用しています。

```typescript
// ファイル: packages/@tailwindcss-postcss/src/index.ts:21-30
interface CacheEntry {
  mtimes: Map<string, number>
  compiler: null | ReturnType<typeof compileAst>
  scanner: null | Scanner
  tailwindCssAst: AstNode[]
  cachedPostCssAst: Root
  optimizedPostCssAst: Root
  fullRebuildPaths: string[]
}
const cache = new QuickLRU<string, CacheEntry>({ maxSize: 50 })
```

#### AST ファクトリ関数パターン

CSS AST ノードはファクトリ関数で生成されます。

```typescript
// ファイル: packages/tailwindcss/src/ast.ts:70-76
export function styleRule(selector: string, nodes: AstNode[] = []): StyleRule {
  return {
    kind: 'rule',
    selector,
    nodes,
  }
}
```

---

## 3. 命名規則

> このセクションでは、プロジェクト全体で使用される命名規則を解説します。

### 3.1 ファイル・ディレクトリ命名

| パターン | 意味 | 例 |
|---------|------|-----|
| `kebab-case.ts` | TypeScript モジュールファイル | `design-system.ts`, `css-parser.ts` |
| `snake_case.rs` | Rust ソースファイル | `candidate_machine.rs`, `named_variant_machine.rs` |
| `@tailwindcss-{name}/` | スコープ付き NPM パッケージ | `@tailwindcss-cli/`, `@tailwindcss-node/` |
| `{name}_machine.rs` | ステートマシン実装ファイル | `utility_machine.rs`, `variant_machine.rs` |
| `pre_processors/` | 言語別前処理モジュール | `json.rs`, `ruby.rs`, `pug.rs` |
| `compat/` | 後方互換性レイヤー | `compat/config/types.ts` |
| `utils/` | ユーティリティ関数群 | `utils/escape.ts`, `utils/segment.ts` |
| `commands/` | CLI コマンド定義 | `commands/build/index.ts` |

### 3.2 クラス・関数・変数命名

| プレフィックス/サフィックス | 意味 | 例 |
|---------------------------|------|-----|
| `create*` | ファクトリ関数 | `createPlugin()`, `createUtilities()`, `createVariants()` |
| `compile*` | コンパイル処理 | `compile()`, `compileCandidates()`, `compileAstNodes()` |
| `parse*` | 構文解析処理 | `parseCandidate()`, `parseVariant()`, `parseThemeOptions()` |
| `substitute*` | 置換処理 | `substituteAtApply()`, `substituteAtImports()`, `substituteFunctions()` |
| `build*` | 構築処理 | `buildDesignSystem()` |
| `load*` | 動的読み込み | `loadModule()`, `loadStylesheet()` |
| `optimize*` | 最適化処理 | `optimizeAst()`, `optimizeCss()` |
| `*Machine` | Rust ステートマシン型 | `CandidateMachine`, `UtilityMachine`, `VariantMachine` |
| `*Entry` | データ入力エントリ型 | `GlobEntry`, `SourceEntry`, `CacheEntry` |
| `*Options` | オプション設定型 | `CompileOptions`, `ScannerOptions`, `PluginOptions` |
| `IS_*` | バリデーション正規表現 | `IS_VALID_PREFIX`, `IS_VALID_VARIANT_NAME` |
| `*_EXTENSIONS_GLOB` | ファイル拡張子定数 | `BINARY_EXTENSIONS_GLOB` |
| `__unstable__*` | 非安定 API | `__unstable__loadDesignSystem()` |

### 3.3 プログラム分類一覧

| 分類 | ファイル命名パターン | 説明 |
|------|---------------------|------|
| コアコンパイラ | `index.ts`, `compile.ts`, `ast.ts` | CSS コンパイルの中核 |
| パーサー | `css-parser.ts`, `selector-parser.ts`, `value-parser.ts` | 構文解析器 |
| ビルドツールプラグイン | `packages/@tailwindcss-{tool}/src/index.ts` | Vite/PostCSS/Webpack 統合 |
| ステートマシン | `*_machine.rs` | Rust 候補抽出器 |
| 前処理器 | `pre_processors/*.rs` | 言語別ファイル前処理 |
| テスト | `*.test.ts`, Rust 内 `#[test]` | テストコード |
| ベンチマーク | `*.bench.ts` | パフォーマンスベンチマーク |

---

## 4. ディレクトリ構造

> このセクションでは、プロジェクトのディレクトリ構造を解説します。

```
tailwindcss-main/
├── crates/                         # Rust クレート（高速処理エンジン）
│   ├── oxide/                      #   コアスキャン・候補抽出エンジン
│   │   └── src/
│   │       ├── lib.rs              #     公開 API
│   │       ├── scanner/            #     ファイルスキャナー
│   │       ├── extractor/          #     クラス候補抽出器
│   │       │   ├── candidate_machine.rs  # 候補パース統合マシン
│   │       │   ├── *_machine.rs    #     各種ステートマシン
│   │       │   └── pre_processors/ #     言語別前処理
│   │       ├── cursor.rs           #     バイト位置管理
│   │       ├── glob.rs             #     glob パターン最適化
│   │       └── fast_skip.rs        #     パフォーマンス最適化
│   ├── node/                       #   Node.js NAPI バインディング
│   │   ├── src/
│   │   │   ├── lib.rs              #     NAPI 型マッピング
│   │   │   └── utf16.rs            #     UTF-8/UTF-16 変換
│   │   ├── npm/                    #     プラットフォーム別バイナリ
│   │   └── package.json            #     @tailwindcss/oxide NPM 設定
│   ├── ignore/                     #   .gitignore パターンマッチング
│   └── classification-macros/      #   バイト分類マクロ（proc-macro）
├── packages/                       # TypeScript NPM パッケージ
│   ├── tailwindcss/                #   コアパッケージ（CSS ユーティリティ生成）
│   │   └── src/
│   │       ├── index.ts            #     メインコンパイル API
│   │       ├── design-system.ts    #     デザインシステム（テーマ・ユーティリティ・バリアント）
│   │       ├── compile.ts          #     候補→AST コンパイル
│   │       ├── candidate.ts        #     クラス名パーサー
│   │       ├── ast.ts              #     CSS AST 型定義
│   │       ├── variants.ts         #     バリアントシステム
│   │       ├── utilities.ts        #     ユーティリティクラス定義
│   │       ├── theme.ts            #     テーマリゾルバ
│   │       ├── plugin.ts           #     プラグイン API
│   │       ├── apply.ts            #     @apply ディレクティブ
│   │       ├── at-import.ts        #     @import 解決
│   │       ├── css-parser.ts       #     CSS パーサー
│   │       ├── compat/             #     v3 互換レイヤー
│   │       ├── source-maps/        #     ソースマップ生成
│   │       └── utils/              #     ユーティリティ関数
│   ├── @tailwindcss-cli/           #   CLI ツール
│   ├── @tailwindcss-node/          #   Node.js ラッパー（モジュールロード・最適化）
│   ├── @tailwindcss-vite/          #   Vite プラグイン
│   ├── @tailwindcss-postcss/       #   PostCSS プラグイン
│   ├── @tailwindcss-webpack/       #   Webpack ローダー
│   ├── @tailwindcss-browser/       #   ブラウザランタイム
│   ├── @tailwindcss-standalone/    #   スタンドアロン WASM ビルド
│   └── @tailwindcss-upgrade/       #   v3→v4 マイグレーションツール
├── integrations/                   # 統合テスト
│   ├── cli/                        #   CLI テスト
│   ├── postcss/                    #   PostCSS テスト
│   ├── vite/                       #   Vite テスト
│   ├── webpack/                    #   Webpack テスト
│   └── oxide/                      #   スキャナーテスト
├── playgrounds/                    # 開発用サンプルプロジェクト
│   ├── vite/                       #   Vite プレイグラウンド
│   └── nextjs/                     #   Next.js プレイグラウンド
├── scripts/                        # ビルド・ユーティリティスクリプト
├── patches/                        # 依存パッケージのパッチ
├── Cargo.toml                      # Rust ワークスペース設定
├── package.json                    # ルート NPM 設定（Turbo ビルド）
├── pnpm-workspace.yaml             # pnpm ワークスペース定義
├── turbo.json                      # Turbo ビルドオーケストレーション
├── vitest.config.ts                # Vitest テスト設定
└── rust-toolchain.toml             # Rust ツールチェーン（1.85.0）
```

### 各ディレクトリの役割

| ディレクトリ | 役割 | 主要ファイル |
|-------------|------|-------------|
| `crates/oxide/` | 高速ファイルスキャン・CSS クラス候補抽出 | `src/scanner/mod.rs`, `src/extractor/mod.rs` |
| `crates/node/` | Rust → JavaScript NAPI ブリッジ | `src/lib.rs` |
| `crates/ignore/` | .gitignore パターン除外（ripgrep fork） | `src/lib.rs` |
| `crates/classification-macros/` | バイト分類ルックアップテーブル生成マクロ | `src/lib.rs` |
| `packages/tailwindcss/` | コア CSS コンパイラ | `src/index.ts`, `src/design-system.ts` |
| `packages/@tailwindcss-node/` | Node.js 環境向けラッパー | `src/compile.ts`, `src/optimize.ts` |
| `packages/@tailwindcss-cli/` | コマンドラインインターフェース | `src/index.ts` |
| `packages/@tailwindcss-vite/` | Vite ビルドツール統合 | `src/index.ts` |
| `packages/@tailwindcss-postcss/` | PostCSS プラグイン統合 | `src/index.ts` |
| `packages/@tailwindcss-webpack/` | Webpack ローダー統合 | `src/index.ts` |
| `packages/@tailwindcss-browser/` | ブラウザ内コンパイラ | `src/index.ts` |
| `integrations/` | 統合テストスイート | 各ツール別ディレクトリ |
| `playgrounds/` | 開発・デバッグ用サンプル | Vite/Next.js 設定 |

---

## 5. アーキテクチャ

> このセクションでは、プロジェクトのアーキテクチャパターンを解説します。

### 5.1 全体アーキテクチャ

Tailwind CSS v4 は **ハイブリッドモノリポ（Hybrid Monorepo）** アーキテクチャを採用しています。パフォーマンスクリティカルなスキャン処理を Rust で実装し、NAPI を通じて TypeScript 側から利用する構成です。

```mermaid
graph TB
    subgraph "ユーザーインターフェース層"
        CLI["@tailwindcss/cli<br/>CLI ツール"]
        Vite["@tailwindcss/vite<br/>Vite プラグイン"]
        PostCSS["@tailwindcss/postcss<br/>PostCSS プラグイン"]
        Webpack["@tailwindcss/webpack<br/>Webpack ローダー"]
        Browser["@tailwindcss/browser<br/>ブラウザランタイム"]
    end

    subgraph "Node.js ラッパー層"
        Node["@tailwindcss/node<br/>モジュールロード・最適化"]
    end

    subgraph "コアコンパイラ層（TypeScript）"
        Core["tailwindcss<br/>CSS コンパイラ"]
        DS["DesignSystem<br/>テーマ・ユーティリティ・バリアント"]
        AST["AST<br/>CSS 抽象構文木"]
    end

    subgraph "ネイティブエンジン層（Rust/NAPI）"
        Oxide["@tailwindcss/oxide<br/>NAPI バインディング"]
        Scanner["Scanner<br/>ファイルスキャナー"]
        Extractor["Extractor<br/>候補抽出器"]
    end

    CLI --> Node
    Vite --> Node
    PostCSS --> Node
    Webpack --> Node
    Browser --> Core

    Node --> Core
    Node --> Oxide

    Core --> DS
    DS --> AST

    Oxide --> Scanner
    Scanner --> Extractor
```

### 5.2 レイヤー構成

| レイヤー | 責務 | 代表的なファイル |
|---------|------|-----------------|
| ユーザーインターフェース | ビルドツールとの統合・CLI コマンド | `packages/@tailwindcss-cli/src/index.ts` |
| Node.js ラッパー | モジュールロード・CSS 最適化・パス解決 | `packages/@tailwindcss-node/src/compile.ts` |
| コアコンパイラ | CSS 候補→AST 変換・テーマ管理 | `packages/tailwindcss/src/index.ts` |
| ネイティブエンジン | 高速ファイルスキャン・クラス候補抽出 | `crates/oxide/src/scanner/mod.rs` |

### 5.3 データフロー

CSS コンパイルの全体的なデータフローは以下の通りです:

```
1. ユーザー CSS ファイル
   ↓
2. @import / @theme 解決（Node.js ラッパー層）
   ↓
3. CSS パース → AST 生成（コアコンパイラ層）
   ↓
4. ファイルスキャン → クラス候補抽出（Rust エンジン層）
   ↓
5. 候補パース（parseCandidate）
   ↓
6. 候補→CSS ルール変換（compileCandidates）
   ↓
7. AST 最適化（optimizeAst）
   ↓
8. CSS 出力（toCss）
   ↓
9. Lightning CSS による最適化・ミニファイ
```

---

## 6. 主要コンポーネント

> このセクションでは、主要なコンポーネントとその連携を解説します。

### 6.1 エントリーポイント

**CLI エントリーポイント** — `packages/@tailwindcss-cli/src/index.ts`

```typescript
// ファイル: packages/@tailwindcss-cli/src/index.ts:1-48
#!/usr/bin/env node

import { args, type Arg } from './utils/args'
import * as build from './commands/build'
import { help } from './commands/help'

const flags = args({ ...build.options(), ...sharedOptions })
// ...
build.handle(flags)
```

**コアコンパイラエントリーポイント** — `packages/tailwindcss/src/index.ts`

`compile()` 関数がメインの公開 API で、CSS 文字列を受け取り、候補追加可能なコンパイラオブジェクトを返します。

```typescript
// ファイル: packages/tailwindcss/src/index.ts:54-75
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
  }>
}
```

**Rust スキャナーエントリーポイント** — `crates/oxide/src/lib.rs`

公開 API は `Scanner`, `GlobEntry`, `ChangedContent`, `PublicSourceEntry` の4つです。

### 6.2 ビジネスロジック

**DesignSystem（デザインシステム）** — テーマ・ユーティリティ・バリアントの統合管理

```typescript
// ファイル: packages/tailwindcss/src/design-system.ts:70-79
export function buildDesignSystem(
  theme: Theme,
  utilitiesSrc?: SourceLocation | undefined,
): DesignSystem {
  let utilities = createUtilities(theme)
  let variants = createVariants(theme)

  let parsedVariants = new DefaultMap((variant) => parseVariant(variant, designSystem))
  let parsedCandidates = new DefaultMap((candidate) =>
    Array.from(parseCandidate(candidate, designSystem)),
  )
```

**Extractor（候補抽出器）** — Rust のステートマシンによる候補抽出

```rust
// ファイル: crates/oxide/src/extractor/mod.rs:57-72
pub struct Extractor<'a> {
    cursor: cursor::Cursor<'a>,
    css_variable_machine: CssVariableMachine,
    candidate_machine: CandidateMachine,
}

impl<'a> Extractor<'a> {
    pub fn new(input: &'a [u8]) -> Self {
        Self {
            cursor: cursor::Cursor::new(input),
            css_variable_machine: Default::default(),
            candidate_machine: Default::default(),
        }
    }
```

### 6.3 データアクセス

本プロジェクトはデータベースを使用していません。データアクセスに相当する処理は以下です:

**ファイルシステムスキャン** — Rust の `Scanner` が `.gitignore` を尊重しつつファイルを走査します。

```rust
// ファイル: crates/oxide/src/scanner/mod.rs:59-80
#[derive(Debug, Clone, Default)]
pub struct Scanner {
    sources: Sources,
    walker: Option<WalkBuilder>,
    extensions: FxHashSet<String>,
    files: FxHashSet<PathBuf>,
    dirs: FxHashSet<PathBuf>,
    globs: Option<Vec<GlobEntry>>,
    candidates: FxHashSet<String>,
```

**モジュール動的ロード** — `jiti` を使用して TypeScript プラグインを動的にロードします。

```typescript
// ファイル: packages/@tailwindcss-node/src/compile.ts:1-6
import EnhancedResolve from 'enhanced-resolve'
import { createJiti, type Jiti } from 'jiti'
```

### 6.4 ユーティリティ/共通機能

**パスユーティリティ** — `packages/@tailwindcss-node/src/normalize-path.ts`
**エスケープ関数** — `packages/tailwindcss/src/utils/escape.ts`
**セグメント関数** — `packages/tailwindcss/src/utils/segment.ts`（CSS 値のセグメント分割）
**ブレース展開** — `packages/tailwindcss/src/utils/brace-expansion.ts`
**DefaultMap** — `packages/tailwindcss/src/utils/default-map.ts`（遅延初期化マップ）
**UTF-16 変換** — `crates/node/src/utf16.rs`（エディタ互換の位置変換）

---

## 7. よく使われるパターン

> このセクションでは、コード内で頻出するパターンを解説します。

### パターン一覧

| パターン | 説明 | 出現頻度 | 代表的なファイル |
|---------|------|---------|-----------------|
| ステートマシン | バイト単位のトークン抽出 | 高 | `crates/oxide/src/extractor/*_machine.rs` |
| タグ付き共用体 (Discriminated Union) | `kind` フィールドによる型判別 | 高 | `packages/tailwindcss/src/ast.ts` |
| ファクトリ関数 | オブジェクト生成の抽象化 | 高 | `packages/tailwindcss/src/ast.ts` |
| LRU キャッシュ | ビルド結果のキャッシング | 中 | `packages/@tailwindcss-postcss/src/index.ts` |
| From トレイト変換 | Rust ↔ JavaScript 型変換 | 中 | `crates/node/src/lib.rs` |
| ビットフラグ enum | オプションのビット演算合成 | 中 | `packages/tailwindcss/src/index.ts` |
| DefaultMap | 遅延初期化キャッシュ | 中 | `packages/tailwindcss/src/design-system.ts` |
| Rayon 並列処理 | マルチスレッドファイル処理 | 低 | `crates/oxide/src/scanner/mod.rs` |

### 各パターンの詳細

#### パターン1: ステートマシン（State Machine）

**目的:** バイト列から CSS クラス候補を高速に抽出する。各マシンは `Machine` トレイトを実装し、合成可能な設計です。

**実装例:**
```rust
// ファイル: crates/oxide/src/extractor/candidate_machine.rs（概要）
// CandidateMachine は VariantMachine と UtilityMachine を内部に持ち、
// "sm:hover:flex" のようなクラス名を以下のように分解します:
//
//   VariantMachine → "sm:" を検出
//   VariantMachine → "hover:" を検出
//   UtilityMachine → "flex" を検出
```

**マシン合成の階層:**
```
CandidateMachine
├── VariantMachine
│   ├── NamedVariantMachine（例: "hover:", "sm:"）
│   └── ArbitraryValueMachine（例: "[&:hover]:"）
└── UtilityMachine
    ├── NamedUtilityMachine（例: "flex", "bg-red-500"）
    ├── ArbitraryPropertyMachine（例: "[color:red]"）
    └── ModifierMachine（例: "/50"）
```

#### パターン2: タグ付き共用体（Discriminated Union）

**目的:** `kind` フィールドで型を判別し、TypeScript の型ガードを活用する。

**実装例:**
```typescript
// ファイル: packages/tailwindcss/src/ast.ts:13-68
export type StyleRule = { kind: 'rule'; selector: string; nodes: AstNode[] }
export type AtRule    = { kind: 'at-rule'; name: string; params: string; nodes: AstNode[] }
export type Declaration = { kind: 'declaration'; property: string; value: string | undefined }
export type Comment   = { kind: 'comment'; value: string }
export type AstNode = StyleRule | AtRule | Declaration | Comment | Context | AtRoot
```

**解説:** `kind` フィールドの値でどの型かを判定できるため、`switch` 文やガード条件で安全にアクセスできます。

#### パターン3: ビットフラグ enum

**目的:** 複数の設定オプションをビット演算で効率的に組み合わせる。

**実装例:**
```typescript
// ファイル: packages/tailwindcss/src/index.ts:41-52
export const enum Polyfills {
  None = 0,
  AtProperty = 1 << 0,   // 1
  ColorMix = 1 << 1,     // 2
  All = AtProperty | ColorMix, // 3
}
```

**解説:** `1 << n` でビット位置を確保し、`|` で組み合わせ、`&` で存在チェックを行います。C 言語のビットフラグと同じパターンです。

#### パターン4: From トレイト変換

**目的:** Rust ↔ JavaScript 間のデータ型変換を安全に行う。

**実装例:**
```rust
// ファイル: crates/node/src/lib.rs:44-56
impl From<ChangedContent> for tailwindcss_oxide::ChangedContent {
  fn from(changed_content: ChangedContent) -> Self {
    if let Some(file) = changed_content.file {
      return tailwindcss_oxide::ChangedContent::File(file.into(), changed_content.extension);
    }
    if let Some(contents) = changed_content.content {
      return tailwindcss_oxide::ChangedContent::Content(contents, changed_content.extension);
    }
    unreachable!()
  }
}
```

**解説:** JavaScript 側の `{ file?: string, content?: string }` を Rust 側の `File(PathBuf, String) | Content(String, String)` に変換します。

---

## 8. 業務フロー追跡の実践例

> このセクションでは、実際の業務フローをコードで追跡する方法を解説します。

### 8.1 フロー追跡の基本手順

1. エントリーポイントを特定（CLI / Vite / PostCSS）
2. 処理の流れを追跡（呼び出し関係を追う）
3. データの変換を確認（CSS → AST → CSS）
4. 最終的な出力を確認

### 8.2 フロー追跡の実例

#### 例1: CLI でのビルドフロー

**概要:** `tailwindcss --input input.css --output output.css` コマンドの実行フロー

**処理フロー:**
```
CLI index.ts → build command → compile(css) → Scanner.scan() → compileCandidates() → toCss() → 出力
```

**詳細な追跡:**

1. **CLI エントリーポイント** (`packages/@tailwindcss-cli/src/index.ts:12-48`)
   ```typescript
   const flags = args({ ...build.options(), ...sharedOptions })
   build.handle(flags)
   ```

2. **Node.js ラッパーでのコンパイル** (`packages/@tailwindcss-node/src/compile.ts:33-64`)
   ```typescript
   function createCompileOptions({ base, from, polyfills, onDependency, ... }) {
     return {
       base,
       polyfills,
       from,
       async loadModule(id, base) {
         return loadModule(id, base, onDependency, customJsResolver)
       },
       async loadStylesheet(id, sheetBase) {
         let sheet = await loadStylesheet(id, sheetBase, onDependency, customCssResolver)
         // URL 書き換え
         return sheet
       },
     }
   }
   ```

3. **コアコンパイラでの処理** (`packages/tailwindcss/src/index.ts`)
   - CSS パース → AST 生成
   - `@import` / `@theme` の解決
   - `DesignSystem` の構築

4. **Rust スキャナーによる候補抽出** (`crates/oxide/src/scanner/mod.rs`)
   - ファイルシステム走査（.gitignore 尊重）
   - 言語別前処理
   - ステートマシンによるクラス候補抽出

5. **候補のコンパイル** (`packages/tailwindcss/src/compile.ts:11-80`)
   ```typescript
   export function compileCandidates(rawCandidates, designSystem, options) {
     for (let rawCandidate of rawCandidates) {
       let candidates = designSystem.parseCandidate(rawCandidate)
       matches.set(rawCandidate, candidates)
     }
     // AST ノード生成とソート
   }
   ```

6. **CSS 出力** (`packages/tailwindcss/src/ast.ts`)
   - `toCss()` で AST → CSS 文字列変換

#### 例2: PostCSS プラグインでのインクリメンタルビルド

**概要:** PostCSS パイプラインでの Tailwind CSS ビルドフロー

**処理フロー:**
```
PostCSS パイプライン → プラグイン Once → キャッシュチェック → Scanner.scan() → compileAst() → optimize → 出力
```

**詳細な追跡:**

1. **プラグイン登録** (`packages/@tailwindcss-postcss/src/index.ts:71-78`)
   ```typescript
   function tailwindcss(opts: PluginOptions = {}): AcceptedPlugin {
     return {
       postcssPlugin: '@tailwindcss/postcss',
       plugins: [
         fixRelativePathsPlugin(),
         { postcssPlugin: 'tailwindcss', async Once(root, { result, postcss }) { ... } }
       ]
     }
   }
   ```

2. **LRU キャッシュ検索** (`packages/@tailwindcss-postcss/src/index.ts:32-34`)
   ```typescript
   let key = `${inputFile}:${opts.base ?? ''}:${JSON.stringify(opts.optimize)}`
   if (cache.has(key)) return cache.get(key)!
   ```

3. **ファイル変更検出** — mtime ベースの変更検知
4. **フル再ビルドまたはインクリメンタルスキャン** — 依存ファイルが変わればフル再ビルド、そうでなければ候補のみ追加

### 8.3 フロー追跡チェックリスト

- [ ] エントリーポイントを特定したか（CLI / Vite / PostCSS / Webpack / Browser）
- [ ] 呼び出し関係を把握したか（どのパッケージのどの関数を呼んでいるか）
- [ ] データの変換ポイントを確認したか（CSS → AST → CSS、Rust ↔ JS 型変換）
- [ ] エラーハンドリングを確認したか（`throwOnLoadModule` 等）
- [ ] 最終的な出力を確認したか（CSS 文字列、ソースマップ）

---

## 9. 設計書の参照順序

> このセクションでは、プロジェクト理解のための設計書参照順序を案内します。

### 9.1 目的別ロードマップ

#### 全体像を把握したい場合
1. `README.md` — プロジェクト概要
2. `package.json` + `pnpm-workspace.yaml` — モノレポ構成
3. `Cargo.toml` — Rust ワークスペース構成
4. 本ガイドライン（セクション4: ディレクトリ構造、セクション5: アーキテクチャ）

#### 特定機能を理解したい場合
1. 該当パッケージの `package.json` — 依存関係と公開 API
2. 該当パッケージの `src/index.ts` — エントリーポイント
3. 関連するコアモジュール（`compile.ts`, `design-system.ts` 等）

#### 改修作業を行う場合
1. 対象パッケージの `src/` ディレクトリ
2. 関連する `*.test.ts` テストファイル
3. `integrations/` の統合テスト
4. `turbo.json` のビルド依存関係

#### ビルドツール統合を理解したい場合
1. `packages/@tailwindcss-{tool}/src/index.ts` — プラグイン実装
2. `packages/@tailwindcss-node/src/compile.ts` — 共通コンパイル API
3. `integrations/{tool}/` — 統合テスト

### 9.2 ドキュメント一覧

| ドキュメント | 概要 | 参照タイミング |
|-------------|------|---------------|
| `README.md` | プロジェクト概要・ビルド手順 | 最初に読む |
| `CHANGELOG.md` | バージョン変更履歴 | 変更内容の確認時 |
| `LICENSE` | MIT ライセンス | ライセンス確認時 |
| `turbo.json` | ビルドパイプライン定義 | ビルド問題の調査時 |
| `vitest.config.ts` | テスト設定 | テスト実行時 |
| `rust-toolchain.toml` | Rust バージョン（1.85.0） | 環境構築時 |

---

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

> このセクションでは、コードリーディング時によくある問題と解決法を解説します。

### よくある疑問と回答

#### Q: TypeScript と Rust のどちらを読めばよいか分からない
A: 大まかに以下の分担です:
- **「何を生成するか」** → TypeScript（`packages/tailwindcss/src/`）を読む
- **「どのファイルから候補を取るか」** → Rust（`crates/oxide/src/`）を読む
- **「どうビルドツールと統合するか」** → TypeScript（`packages/@tailwindcss-{tool}/`）を読む

#### Q: `@tailwindcss/oxide` パッケージの `.node` ファイルはどこから来るのか
A: `crates/node/` の Rust コードが NAPI でコンパイルされ、プラットフォーム別の `.node` バイナリとして生成されます。`crates/node/npm/` 配下にプラットフォームごとのパッケージがあります。

#### Q: `compat/` ディレクトリは何のためにあるのか
A: Tailwind CSS v3 のプラグイン API・設定ファイル形式との後方互換性を提供しています。v3 形式の設定やプラグインが v4 でも動作するようにするアダプタ層です。

#### Q: テストを実行するにはどうすればよいか
A: ルートの `package.json` のスクリプトを使用します:
- `pnpm test` — Rust テスト（`cargo test`）+ TypeScript テスト（`vitest run`）
- `pnpm test:integrations` — 統合テスト
- `pnpm tdd` — 監視モードでの TypeScript テスト

#### Q: `const enum` が JavaScript に出力されないのはなぜか
A: TypeScript の `const enum` はコンパイル時にインライン展開されます。バンドル後のコードでは数値リテラルに置き換わっているため、ランタイムには存在しません。

### デバッグのヒント

- **Rust 側のデバッグ:** `SHOULD_TRACE` 環境変数と `tracing` クレートで詳細ログを有効化できます（`crates/oxide/src/scanner/init_tracing.rs`）
- **PostCSS プラグインのデバッグ:** `env.DEBUG` フラグで追加ログが出力されます（`packages/@tailwindcss-postcss/src/index.ts:19`）
- **パフォーマンス測定:** `Instrumentation` クラスがビルド各ステップの計測に使用できます（`packages/@tailwindcss-node/src/instrumentation.ts`）
- **ビルドの問題:** `turbo.json` のタスク依存関係（`dependsOn`）を確認してください

---

## 付録

### A. 用語集

| 用語 | 説明 |
|-----|------|
| Candidate（候補） | ユーザーが HTML/JSX で書くクラス名（例: `bg-red-500`）。Rust スキャナーが抽出し、TypeScript コンパイラが CSS に変換する |
| Variant（バリアント） | 条件付きスタイルのプレフィックス（例: `hover:`, `sm:`, `dark:`） |
| Utility（ユーティリティ） | 1つの CSS プロパティに対応するクラス名（例: `flex`, `p-4`） |
| DesignSystem | テーマ・ユーティリティ・バリアントを統合管理する中核オブジェクト |
| Oxide | Rust 実装のコード名。高速スキャン・候補抽出エンジン |
| NAPI | Node-API。Rust ネイティブモジュールを Node.js から呼び出すための安定 ABI |
| AST | 抽象構文木。CSS を構造化されたデータとして表現する |
| Lightning CSS | CSS の最適化・ミニファイに使用される外部ライブラリ |
| Turbo | モノレポのビルドオーケストレーションツール |
| pnpm | 高速なパッケージマネージャ。ワークスペース機能でモノレポを管理 |
| jiti | TypeScript/ESM モジュールを実行時に動的ロードするライブラリ |
| Polyfill | 古いブラウザ向けのフォールバック CSS 生成機能 |
| Extractor | ステートマシンベースのクラス候補抽出器（Rust 実装） |

### B. ファイル一覧

| ファイル/ディレクトリ | 説明 | 主な内容 |
|---------------------|------|---------|
| `packages/tailwindcss/src/index.ts` | コアコンパイラのエントリーポイント | `compile()` 関数、CSS 処理パイプライン |
| `packages/tailwindcss/src/design-system.ts` | デザインシステム構築 | `buildDesignSystem()`, `DesignSystem` 型 |
| `packages/tailwindcss/src/compile.ts` | 候補コンパイル | `compileCandidates()` |
| `packages/tailwindcss/src/candidate.ts` | クラス名パーサー | `Candidate`, `Variant` 型定義 |
| `packages/tailwindcss/src/ast.ts` | CSS AST 定義 | `AstNode` 型、`toCss()`, `optimizeAst()` |
| `packages/tailwindcss/src/variants.ts` | バリアントシステム | `createVariants()`, バリアント定義 |
| `packages/tailwindcss/src/utilities.ts` | ユーティリティ定義 | `createUtilities()`, ユーティリティ登録 |
| `packages/tailwindcss/src/theme.ts` | テーマリゾルバ | `Theme` クラス、テーマ値解決 |
| `packages/tailwindcss/src/plugin.ts` | プラグイン API | `createPlugin()`, `withOptions()` |
| `packages/@tailwindcss-node/src/compile.ts` | Node.js コンパイルラッパー | モジュールロード、スタイルシートロード |
| `packages/@tailwindcss-node/src/optimize.ts` | CSS 最適化 | Lightning CSS による最適化 |
| `packages/@tailwindcss-cli/src/index.ts` | CLI エントリーポイント | 引数パース、ビルドコマンド |
| `packages/@tailwindcss-vite/src/index.ts` | Vite プラグイン | HMR、環境別ルート管理 |
| `packages/@tailwindcss-postcss/src/index.ts` | PostCSS プラグイン | LRU キャッシュ、AST 変換 |
| `packages/@tailwindcss-browser/src/index.ts` | ブラウザランタイム | MutationObserver、DOM スキャン |
| `crates/oxide/src/lib.rs` | Rust コアの公開 API | `Scanner`, `GlobEntry` エクスポート |
| `crates/oxide/src/scanner/mod.rs` | ファイルスキャナー | ファイル走査、並列処理 |
| `crates/oxide/src/extractor/mod.rs` | 候補抽出器 | `Extractor`, `Extracted` enum |
| `crates/oxide/src/extractor/candidate_machine.rs` | 候補パースマシン | ステートマシン合成 |
| `crates/node/src/lib.rs` | NAPI バインディング | Rust ↔ JS 型変換 |
| `crates/node/src/utf16.rs` | UTF-16 変換 | エディタ互換位置変換 |

### C. 参考資料

- [Tailwind CSS 公式ドキュメント](https://tailwindcss.com/docs)
- [TypeScript ドキュメント](https://www.typescriptlang.org/docs/)
- [Rust 公式ドキュメント](https://doc.rust-lang.org/book/)
- [NAPI-RS ドキュメント](https://napi.rs/)
- [Lightning CSS](https://lightningcss.dev/)
- [Turbo ドキュメント](https://turbo.build/)
- [pnpm ワークスペース](https://pnpm.io/workspaces)
- [Vitest ドキュメント](https://vitest.dev/)
