# 機能設計書 67-フィーチャーフラグ

## 概要

本ドキュメントは、Tailwind CSSにおけるフィーチャーフラグ（Feature Flags）機能の設計を記述する。環境変数`FEATURES_ENV`に基づいて実験的機能の有効/無効を制御する仕組みを提供する。

### 本機能の処理概要

**業務上の目的・背景**：Tailwind CSSの開発においては、新機能を段階的にリリースする必要がある。フィーチャーフラグを使用することで、安定版（stable）リリースでは無効化し、開発・プレリリース環境では有効化するという制御が可能になる。これにより、実験的機能をコードベースに含めつつ、安定版ユーザーへの影響を避けることができる。

**機能の利用シーン**：ユーティリティ登録・生成処理（utilities.ts）において、`@container`ユーティリティの`size`値サポートなどの実験的機能を制御するために使用される。`FEATURES_ENV`が`stable`に設定されている場合は実験的機能が無効化され、それ以外の場合（development、未設定等）は有効化される。

**主要な処理内容**：
1. 環境変数`process.env.FEATURES_ENV`の値を参照する
2. 値が`'stable'`の場合は`false`を返す（実験的機能を無効化）
3. 値が`'stable'`以外（未設定含む）の場合は`true`を返す（実験的機能を有効化）

**関連システム・外部連携**：Node.jsの`process.env`環境変数を参照する。ビルドシステム（npm scripts等）により`FEATURES_ENV`が設定される。

**権限による制御**：権限による制御はない。環境変数による制御のみ。

## 関連画面

本機能は内部制御メカニズムであり、画面に直接関連しない。

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | 補助機能 | ユーティリティクラスの利用可否を制御することで間接的にCSS出力に影響 |

## 機能種別

バリデーション（機能制御・条件分岐）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| process.env.FEATURES_ENV | string \| undefined | No | 環境変数。'stable'の場合は実験的機能を無効化 | 特になし |

### 入力データソース

Node.jsの`process.env`環境変数から取得。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| enableContainerSizeUtility | boolean | コンテナサイズユーティリティの有効/無効フラグ。trueで有効 |

### 出力先

定数エクスポートとして、利用元モジュールから参照される。

## 処理フロー

### 処理シーケンス

```
1. モジュール読み込み時に環境変数を評価
   └─ process.env.FEATURES_ENV !== 'stable' の結果をconstに格納
2. エクスポートされたconstを利用元が参照
   └─ utilities.ts の@container処理で条件分岐に使用
```

### フローチャート

```mermaid
flowchart TD
    A["モジュール読み込み"] --> B{"FEATURES_ENV === 'stable'?"}
    B -->|Yes| C["enableContainerSizeUtility = false"]
    B -->|No / undefined| D["enableContainerSizeUtility = true"]
    C --> E["利用元で参照"]
    D --> E
    E --> F{"enableContainerSizeUtility?"}
    F -->|true| G["@container size ユーティリティを有効化"]
    F -->|false| H["@container size ユーティリティを無効化"]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-67-01 | stable環境での無効化 | FEATURES_ENVが'stable'の場合、実験的機能は無効化される | FEATURES_ENV === 'stable' |
| BR-67-02 | デフォルト有効化 | FEATURES_ENVが未設定または'stable'以外の場合、実験的機能は有効化される | FEATURES_ENV !== 'stable' |
| BR-67-03 | コンテナサイズ制御 | enableContainerSizeUtilityは@containerユーティリティのsize値サポートを制御する | @container処理時 |

### 計算ロジック

`enableContainerSizeUtility = process.env.FEATURES_ENV !== 'stable'`

- `FEATURES_ENV`が`'stable'`: false（無効）
- `FEATURES_ENV`が未設定（undefined）: `undefined !== 'stable'` = true（有効）
- `FEATURES_ENV`がその他の値: true（有効）

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

### 操作別データベース影響一覧

データベース操作はない。

## エラー処理

### エラーケース一覧

エラーは発生しない。環境変数が未設定の場合もundefinedとして正常に処理される。

### リトライ仕様

リトライ処理はない。

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

トランザクション管理はない。

## パフォーマンス要件

- モジュール読み込み時に1回だけ評価される定数式（O(1)）
- ランタイムのパフォーマンス影響はない

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

- 環境変数による制御であるため、ユーザーが意図せず実験的機能を有効化するリスクは低い
- 安定版リリースではビルドプロセスでFEATURES_ENVがstableに設定される

## 備考

- 現在エクスポートされているフラグは`enableContainerSizeUtility`の1つのみ
- コンテナサイズユーティリティ（`@container-size`）は`container-type: size`を設定する実験的機能
- utilities.tsの5907行目付近で、`enableContainerSizeUtility && candidate.value.kind === 'named' && candidate.value.value === 'size'`の条件分岐で使用される
- 将来的に実験的機能が増加した場合、本モジュールにフラグが追加される可能性がある

---

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

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

### 推奨読解順序

#### Step 1: フィーチャーフラグの定義を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | feature-flags.ts | `packages/tailwindcss/src/feature-flags.ts` | **1行目**: `enableContainerSizeUtility`の定義。process.env.FEATURES_ENVとの比較による単純なboolean式 |

**読解のコツ**: ファイルは1行のみで極めてシンプル。`process.env.FEATURES_ENV`はNode.jsの環境変数アクセスであり、ビルド時にバンドラーがインライン化する場合もある。

#### Step 2: 利用箇所を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | utilities.ts | `packages/tailwindcss/src/utilities.ts` | **15行目**: enableContainerSizeUtilityのimport文 |
| 2-2 | utilities.ts | `packages/tailwindcss/src/utilities.ts` | **5907行目**: @containerユーティリティ内でのenableContainerSizeUtilityの条件分岐 |

**主要処理フロー**:
1. **15行目**: `import { enableContainerSizeUtility } from './feature-flags'`
2. **5907行目**: `enableContainerSizeUtility && candidate.value.kind === 'named' && candidate.value.value === 'size'`
3. **5911行目**: 条件がtrueの場合、`value = 'size'`が設定され`container-type: size`が出力される

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

```
feature-flags.ts
    │
    └─ export enableContainerSizeUtility = (process.env.FEATURES_ENV !== 'stable')
           │
           └─ utilities.ts
                  │
                  └─ @container ユーティリティ定義
                         │
                         └─ if (enableContainerSizeUtility && ...)
                                └─ container-type: size を出力
```

### データフロー図

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

process.env.FEATURES_ENV
    │
    └───────────────────▶ !== 'stable' 比較
                               │
                               └─ enableContainerSizeUtility ──▶ boolean
                                        │
                                        └─ utilities.ts
                                               │
                                               └─ @container size  ──▶ container-type: size
                                                  有効/無効の制御          (CSSプロパティ)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| feature-flags.ts | `packages/tailwindcss/src/feature-flags.ts` | ソース | フィーチャーフラグの定義（1行） |
| utilities.ts | `packages/tailwindcss/src/utilities.ts` | ソース | enableContainerSizeUtilityを参照してコンテナサイズユーティリティを制御 |
