# 機能設計書 23---alpha()関数

## 概要

本ドキュメントは、Tailwind CSSにおける`--alpha()`カスタムCSS関数の仕様・処理フロー・内部構造を記述した機能設計書である。

### 本機能の処理概要

`--alpha()`関数は、色にアルファ値（透明度）を適用するカスタムCSS関数である。`--alpha(var(--color-blue-500) / 50%)`と記述すると、`color-mix(in oklab, var(--color-blue-500) 50%, transparent)`のような透明度を適用した色表現に変換される。

**業務上の目的・背景**：CSSで色にアルファ値を動的に適用する需要は多い。CSS変数として保持されている色に対して透明度を後から指定できる仕組みが必要であり、`--alpha()`関数はこの要件を満たす。`color-mix()`関数を使用してブラウザネイティブの色合成を行うことで、あらゆる色形式（hex, rgb, hsl, oklchなど）に対応する。

**機能の利用シーン**：テーマカラーに透明度を適用する場合（例: `background: --alpha(var(--color-primary) / 50%)`）、カスタムユーティリティ内で色のアルファ操作を行う場合、修飾子（modifier）経由でアルファ値を指定する場合の内部処理として使用される。

**主要な処理内容**：
1. CSS値パーサーでCSS値文字列をパースし、`--alpha()`関数ノードを検出する
2. 引数を`/`で分割して色とアルファ値を分離する
3. `withAlpha`関数でcolor-mix()式を生成する

**関連システム・外部連携**：CSS関数置換フレームワーク（substituteFunctions）、withAlpha関数（utilities.tsからインポート）と連携する。

**権限による制御**：特になし。CSS処理パイプラインの一部として自動的に実行される。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | 本機能はCSS処理パイプラインの内部処理であり、特定の画面とは直接関連しない |

## 機能種別

データ変換処理（CSS関数の値変換）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| _designSystem | DesignSystem | Yes | デザインシステム（本関数では未使用） | - |
| _source | AstNode | Yes | ASTノード（本関数では未使用） | - |
| value | string | Yes | `color / alpha`形式の文字列 | 色とアルファ値の両方が必要 |
| rest | string[] | No | 追加の引数 | 空であること（1引数のみ許可） |

### 入力データソース

CSSのAST内の宣言値から抽出される。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| result | string | `color-mix(in oklab, {color} {alpha}, transparent)`形式の文字列 |

### 出力先

AST上の関数ノードが生成された色表現で置換される。

## 処理フロー

### 処理シーケンス

```
1. substituteFunctions内でASTを走査し--alpha()関数を検出
   └─ THEME_FUNCTION_INVOCATION正規表現でマッチ
2. alpha関数を呼び出し
   └─ 引数を / で分割して色とアルファ値を取得
3. バリデーション
   └─ 色とアルファ値の両方が存在すること、引数が1つのみであること
4. withAlpha関数で変換
   └─ color-mix()式を生成して返す
```

### フローチャート

```mermaid
flowchart TD
    A[--alpha関数呼び出し] --> B["segment(value, '/') で分割"]
    B --> C{color と alpha 両方存在?}
    C -->|No| D[エラー: 色とアルファ値が必要]
    C -->|Yes| E{rest.length > 0?}
    E -->|Yes| F[エラー: 引数は1つのみ]
    E -->|No| G["withAlpha(color, alpha)"]
    G --> H[color-mix()式を返す]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | 単一引数制約 | `--alpha()`は1つの引数のみ受け取る | 常時 |
| BR-02 | 色とアルファ値の必須性 | `color / alpha`形式で、色とアルファ値の両方が必要 | 常時 |
| BR-03 | /区切り | 色とアルファ値は`/`で分割される | 常時 |

### 計算ロジック

`withAlpha(color, alpha)` -> `color-mix(in oklab, {color} {alpha}, transparent)`

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

本機能はデータベース操作を行わない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | Error | 色またはアルファ値が欠落している | `--alpha(color / alpha)`形式で指定する |
| - | Error | 引数が2つ以上 | 引数を1つに減らす |

### リトライ仕様

リトライは行わない。

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

トランザクション管理は不要。

## パフォーマンス要件

特段の要件なし。

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

特段のセキュリティ考慮事項はない。

## 備考

- `--alpha()`はCSS関数置換フレームワーク（CSS_FUNCTIONS）の一部として`--theme()`、`--spacing()`と同じ仕組みで処理される
- `withAlpha`関数はutilities.tsからインポートされ、ユーティリティクラスの修飾子処理でも使用される
- `color-mix()`はCSS Color Level 5の仕様に基づく

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | css-functions.ts | `packages/tailwindcss/src/css-functions.ts` | **9-17行目**: CSS_FUNCTIONSレコード。`--alpha`キーにalpha関数がマッピングされている |

#### Step 2: alpha関数の実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | css-functions.ts | `packages/tailwindcss/src/css-functions.ts` | **19-40行目**: alpha関数の実装 |

**主要処理フロー**:
- **25行目**: `segment(value, '/')`で色とアルファ値を分割し、trimする
- **27-31行目**: 色またはアルファ値が欠落している場合のエラー
- **33-37行目**: 引数が複数の場合のエラー
- **39行目**: `withAlpha(color, alpha)`でcolor-mix()式を生成

#### Step 3: withAlpha関数の実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | utilities.ts | `packages/tailwindcss/src/utilities.ts` | withAlpha関数の実装。color-mix()式の生成ロジック |

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

```
substituteFunctions(ast, designSystem)
    │
    ├─ walk(ast, callback)
    │      │
    │      └─ substituteFunctionsInValue(value, source, designSystem)
    │             │
    │             ├─ ValueParser.parse(value)
    │             │
    │             └─ alpha(_designSystem, _source, value, ...rest)
    │                    │
    │                    ├─ segment(value, '/')
    │                    │
    │                    └─ withAlpha(color, alpha)
    │
    └─ Features更新
```

### データフロー図

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

CSS値文字列                      ──▶ substituteFunctions            ──▶ CSS値文字列（変換済み）
"--alpha(var(--blue) / 50%)"          │
                                      ├─ --alpha() を検出
                                      │
                                      ├─ "/" で分割
                                      │    color = "var(--blue)"
                                      │    alpha = "50%"
                                      │
                                      └─ withAlpha で変換
                                                                        "color-mix(in oklab, var(--blue) 50%, transparent)"
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| css-functions.ts | `packages/tailwindcss/src/css-functions.ts` | ソース | --alpha()関数の主要実装（19-40行目） |
| utilities.ts | `packages/tailwindcss/src/utilities.ts` | ソース | withAlpha関数の提供元 |
| value-parser.ts | `packages/tailwindcss/src/value-parser.ts` | ソース | CSS値のパーサー |
| segment.ts | `packages/tailwindcss/src/utils/segment.ts` | ソース | /区切りの文字列分割 |
| walk.ts | `packages/tailwindcss/src/walk.ts` | ソース | AST走査ユーティリティ |
