# 機能設計書 10-デザインシステム構築（buildDesignSystem）

## 概要

本ドキュメントは、Theme・Utilities・Variantsを統合するDesignSystemオブジェクトを構築するbuildDesignSystem関数の機能設計書である。候補パース・AST生成・クラスリスト取得・テーマ値解決等のAPIを提供する。

### 本機能の処理概要

**業務上の目的・背景**：Tailwind CSSのコンパイルパイプラインでは、テーマ設定・ユーティリティ定義・バリアント定義の3つの主要サブシステムを統合して管理する中心的なオブジェクトが必要である。DesignSystemはこれらのサブシステムを統合し、候補クラスのパース・コンパイル・IntelliSense情報の提供を行う統一的なAPIを提供する。

**機能の利用シーン**：parseCss関数内で@themeディレクティブの処理後に構築され、以降のコンパイルパイプライン全体で使用される。IntelliSense機能（候補リスト、バリアントリスト）のデータソースとしても使用される。外部プラグインからもDesignSystem APIを通じてユーティリティやバリアントの操作が行われる。

**主要な処理内容**：
1. Theme・Utilities・Variantsの各サブシステムを初期化する
2. parsedVariants/parsedCandidatesのDefaultMapキャッシュを構築する
3. compiledAstNodesのネストしたDefaultMapキャッシュを構築する
4. テーマ変数の使用追跡機能を提供する
5. candidatesToCss/candidatesToAst関数でIntelliSense向けのCSS生成を提供する
6. getClassOrder/getClassList/getVariants関数でソート順序・補完候補情報を提供する
7. resolveThemeValue関数でテーマ値の解決を提供する
8. canonicalizeCandidates関数で候補の正規化を提供する

**関連システム・外部連携**：Theme、Utilities、Variantsの各サブシステムと連携する。

**権限による制御**：特になし。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 2 | Appコンポーネント | 補助画面 | ユーティリティ・テーマ・バリアントを統合したDesignSystemを提供する |
| 6 | トップページ | 補助画面 | ユーティリティ・テーマ・バリアントを統合したDesignSystemを提供する |

## 機能種別

オブジェクト構築 / ファサードパターン

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| theme | Theme | Yes | テーマオブジェクト | 有効なThemeインスタンス |
| utilitiesSrc | SourceLocation | No | @tailwind utilitiesのソースロケーション | ソースマップ生成用 |

### 入力データソース

- parseCss関数内で構築されたThemeオブジェクト

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| designSystem | DesignSystem | 統合されたデザインシステムオブジェクト |

DesignSystemオブジェクトが提供するAPI:

| メソッド/プロパティ | 型 | 説明 |
|---|---|---|
| theme | Theme | テーマオブジェクト |
| utilities | Utilities | ユーティリティ管理 |
| variants | Variants | バリアント管理 |
| invalidCandidates | Set<string> | 無効候補の記録セット |
| important | boolean | グローバル!importantフラグ |
| parseCandidate(candidate) | Candidate[] | 候補文字列のパース（キャッシュ付き） |
| parseVariant(variant) | Variant \| null | バリアント文字列のパース（キャッシュ付き） |
| compileAstNodes(candidate, flags) | AstNode[] | CandidateからASTノード生成（キャッシュ付き） |
| printCandidate(candidate) | string | Candidateの文字列化 |
| printVariant(variant) | string | Variantの文字列化 |
| getVariantOrder() | Map<Variant, number> | バリアントのソート順序マップ |
| resolveThemeValue(path) | string \| undefined | テーマ値の解決 |
| trackUsedVariables(raw) | void | CSS変数の使用追跡 |
| canonicalizeCandidates(candidates) | string[] | 候補の正規化 |
| candidatesToCss(classes) | (string \| null)[] | クラスからCSS文字列変換 |
| candidatesToAst(classes) | AstNode[][] | クラスからAST変換 |
| getClassOrder(classes) | [string, bigint \| null][] | クラスのソート順序取得 |
| getClassList() | ClassEntry[] | 利用可能な全クラスリスト |
| getVariants() | VariantEntry[] | 利用可能な全バリアントリスト |
| storage | Record<symbol, unknown> | 汎用ストレージ |

### 出力先

- コンパイルパイプラインの各段階で使用される

## 処理フロー

### 処理シーケンス

```
1. サブシステム初期化
   ├─ createUtilities(theme) でUtilitiesを生成
   └─ createVariants(theme) でVariantsを生成
2. キャッシュの構築
   ├─ parsedVariants: DefaultMap (バリアント文字列 -> Variant | null)
   ├─ parsedCandidates: DefaultMap (候補文字列 -> Candidate[])
   ├─ compiledAstNodes: DefaultMap<flags, DefaultMap<candidate, AstNode[]>>
   └─ trackUsedVariables: DefaultMap (値文字列 -> void)
3. ヘルパー関数の定義
   ├─ candidatesToAst: クラス名からAST配列を生成
   └─ candidatesToCss: クラス名からCSS文字列を生成
4. DesignSystemオブジェクトの構築
   └─ 上記全てのプロパティとメソッドを持つオブジェクトを返却
```

### フローチャート

```mermaid
flowchart TD
    A[Theme入力] --> B[createUtilities]
    A --> C[createVariants]
    B --> D[DefaultMapキャッシュ構築]
    C --> D
    D --> E[DesignSystemオブジェクト構築]
    E --> F[DesignSystem返却]
    F --> G{parseCandidate呼び出し}
    G --> H[parsedCandidatesキャッシュ参照]
    H --> I{キャッシュあり?}
    I -->|Yes| J[キャッシュから返却]
    I -->|No| K[parseCandidate実行+キャッシュ]
    F --> L{compileAstNodes呼び出し}
    L --> M[compiledAstNodesキャッシュ参照]
    M --> N{キャッシュあり?}
    N -->|Yes| O[キャッシュから返却]
    N -->|No| P[compileAstNodes実行+キャッシュ]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | 候補パースのメモ化 | parseCandidateの結果はDefaultMapでキャッシュされ、同一候補文字列に対して再パースしない | 常時 |
| BR-02 | バリアントパースのメモ化 | parseVariantの結果はDefaultMapでキャッシュされる | 常時 |
| BR-03 | ASTノード生成のメモ化 | compileAstNodesの結果はflags→candidateの2段階DefaultMapでキャッシュされる | 常時 |
| BR-04 | CSS関数の遅延評価 | compileAstNodes内でsubstituteFunctionsとsubstituteAtVariantが実行される | ASTノード生成時 |
| BR-05 | substituteFunctions失敗の安全処理 | CSS関数の置換に失敗した場合、空配列を返却する（候補を無効とする） | theme()等の評価エラー時 |
| BR-06 | テーマ値の修飾子対応 | resolveThemeValueは`/`区切りで修飾子（アルファ値）を分離し、withAlphaで適用する | パスに`/`が含まれる場合 |
| BR-07 | バリアント順序の決定 | getVariantOrderはバリアントをcompare関数でソートし、同一順序のバリアントをグループ化する | バリアント順序が必要な場合 |
| BR-08 | IntelliSenseのポリフィル無効化 | candidatesToAst/CssではPolyfills.Noneでoptimizeが実行される | IntelliSense向け出力時 |

### 計算ロジック

- **テーマ値解決**: `theme.resolve(null, [path], forceInline ? ThemeOptions.INLINE : ThemeOptions.NONE)` でテーマ値を解決。修飾子がある場合は`withAlpha(themeValue, modifier)`で透明度を適用
- **バリアント順序**: `variants.compare(a, z)`で比較し、同一比較結果のバリアントに同じインデックスを付与

## データベース操作仕様

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | try/catch | compileAstNodes内のsubstituteFunctionsが失敗 | 空配列を返却（候補を無効とする） |

### リトライ仕様

該当なし

## トランザクション仕様

該当なし

## パフォーマンス要件

- DefaultMapによる3種類のキャッシュ（parseCandidate、parseVariant、compileAstNodes）で繰り返し処理を最適化
- compiledAstNodesは2段階のDefaultMap（flags -> candidate -> result）でフラグごとのキャッシュを分離

## セキュリティ考慮事項

特になし。

## 備考

- `storage`プロパティは汎用ストレージであり、プラグイン間のデータ共有にシンボルキーを使用して衝突を回避する
- `__unstable__loadDesignSystem`関数（index.ts）はDesignSystemのみを取得するヘルパーとして公開されている

---

## コードリーディングガイド

本機能を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: データ構造を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | design-system.ts | `packages/tailwindcss/src/design-system.ts` | DesignSystem型定義（35-68行目）。全APIの一覧を理解する |
| 1-2 | design-system.ts | `packages/tailwindcss/src/design-system.ts` | CompileAstFlags列挙型（30-33行目）。RespectImportantフラグ |

**読解のコツ**: DesignSystem型はインターフェースではなくtype aliasで定義されている。buildDesignSystem関数がこの型に合致するオブジェクトリテラルを返却するパターン。DefaultMapは`Map`のサブクラスで、getメソッドが呼ばれた際にキーが存在しなければファクトリ関数で値を生成してキャッシュする。

#### Step 2: buildDesignSystem関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | design-system.ts | `packages/tailwindcss/src/design-system.ts` | `buildDesignSystem`関数（70-255行目） |

**主要処理フロー**:
1. **74-75行目**: createUtilitiesとcreateVariantsでサブシステム初期化
2. **77-79行目**: parsedVariantsのDefaultMapキャッシュ（バリアントパース結果）
3. **78-80行目**: parsedCandidatesのDefaultMapキャッシュ（候補パース結果）
4. **82-110行目**: compiledAstNodesの2段階DefaultMapキャッシュ（flags -> candidate -> AST）
  - **91-94行目**: substituteFunctionsの実行（CSS関数の評価）
  - **97-100行目**: substituteAtVariantの実行（@variant処理）
  - **101-106行目**: try/catch による安全処理
5. **112-116行目**: trackUsedVariablesのDefaultMap
6. **118-148行目**: candidatesToAst関数の定義
7. **150-154行目**: candidatesToCss関数の定義
8. **156-252行目**: DesignSystemオブジェクトの構築

#### Step 3: 各APIメソッドの実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | design-system.ts | `packages/tailwindcss/src/design-system.ts` | resolveThemeValue（219-239行目）、getVariantOrder（194-217行目） |

**主要処理フロー**:
- **219-239行目**: resolveThemeValue - パスの最後の`/`で修飾子を分離、theme.resolveで値を取得、withAlphaで修飾子を適用
- **194-217行目**: getVariantOrder - parsedVariantsの全値をソートし、同一順序のバリアントをグループ化してMap<Variant, number>を返却

### プログラム呼び出し階層図

```
buildDesignSystem(theme, utilitiesSrc)
    |
    +-- createUtilities(theme)          ... ユーティリティサブシステム初期化
    +-- createVariants(theme)           ... バリアントサブシステム初期化
    |
    +-- DesignSystem オブジェクト
         |
         +-- parseCandidate(candidate)
         |    └─ parsedCandidates.get()  ... DefaultMapキャッシュ
         |         └─ parseCandidate()   ... candidate.ts
         |
         +-- parseVariant(variant)
         |    └─ parsedVariants.get()    ... DefaultMapキャッシュ
         |         └─ parseVariant()     ... candidate.ts
         |
         +-- compileAstNodes(candidate, flags)
         |    └─ compiledAstNodes.get(flags).get(candidate)
         |         ├─ compileAstNodes()  ... compile.ts
         |         ├─ substituteFunctions()
         |         └─ substituteAtVariant()
         |
         +-- resolveThemeValue(path)
         |    └─ theme.resolve()        ... theme.ts
         |
         +-- candidatesToCss(classes)
         |    └─ candidatesToAst()
         |         └─ compileCandidates()
         |
         +-- getClassList()
         |    └─ getClassList()         ... intellisense.ts
         |
         +-- getVariants()
              └─ getVariants()          ... intellisense.ts
```

### データフロー図

```
[入力]                    [処理]                           [出力]

Theme             ──▶  buildDesignSystem       ──▶  DesignSystem
                       ├─ createUtilities
                       └─ createVariants

候補文字列        ──▶  parseCandidate          ──▶  Candidate[]
                       (DefaultMapキャッシュ)

Candidate         ──▶  compileAstNodes         ──▶  AstNode[]
                       (2段階DefaultMapキャッシュ)

テーマパス        ──▶  resolveThemeValue       ──▶  string | undefined
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| design-system.ts | `packages/tailwindcss/src/design-system.ts` | ソース | DesignSystem型定義、buildDesignSystem関数 |
| theme.ts | `packages/tailwindcss/src/theme.ts` | ソース | Themeクラス（テーマ管理サブシステム） |
| utilities.ts | `packages/tailwindcss/src/utilities.ts` | ソース | Utilities/createUtilities（ユーティリティサブシステム） |
| variants.ts | `packages/tailwindcss/src/variants.ts` | ソース | Variants/createVariants（バリアントサブシステム） |
| candidate.ts | `packages/tailwindcss/src/candidate.ts` | ソース | parseCandidate、parseVariant関数 |
| compile.ts | `packages/tailwindcss/src/compile.ts` | ソース | compileAstNodes、compileCandidates関数 |
| css-functions.ts | `packages/tailwindcss/src/css-functions.ts` | ソース | substituteFunctions関数 |
| intellisense.ts | `packages/tailwindcss/src/intellisense.ts` | ソース | getClassList、getVariants、canonicalizeCandidates関数 |
| sort.ts | `packages/tailwindcss/src/sort.ts` | ソース | getClassOrder関数 |
| ast.ts | `packages/tailwindcss/src/ast.ts` | ソース | optimizeAst、toCss関数 |
| utils/default-map.ts | `packages/tailwindcss/src/utils/default-map.ts` | ソース | DefaultMapクラス |
| utils/variables.ts | `packages/tailwindcss/src/utils/variables.ts` | ソース | extractUsedVariables関数 |
