# 機能設計書 34-プロパティ順序

## 概要

本ドキュメントは、Tailwind CSSにおけるユーティリティクラスのCSSプロパティ順序表（property-order）の機能設計を記述する。

### 本機能の処理概要

ユーティリティクラスをCSSプロパティの出現順に基づいてソートするための、グローバルなプロパティ順序表を提供する機能である。この順序表は配列として定義され、配列のインデックスがプロパティのソート優先度を表す。

**業務上の目的・背景**：Tailwind CSSが生成するCSSにおいて、ユーティリティクラスの出力順序はスタイルの優先度に直結する。プロパティ順序表は、レイアウト（position, inset等）→ボックスモデル（margin, padding等）→タイポグラフィ（font-size, color等）→ビジュアル（shadow, filter等）→その他（transition, animation等）の論理的な順序でプロパティを配置することで、開発者が直感的に理解しやすいCSS出力を実現する。また、Tailwind CSS内部の`--tw-`カスタムプロパティも順序表に含めることで、カスタムプロパティを使用した内部変数（shadow、gradient、filter等）のソートも管理する。

**機能の利用シーン**：compileCandidates関数内でASTノードのソート順序を決定する際に参照される。各ユーティリティクラスが生成するCSSプロパティの位置を、この順序表で比較することで、一貫したCSS出力順序を保証する。

**主要な処理内容**：
1. CSSプロパティ名とTailwind内部カスタムプロパティ名の順序付きリストを定義する
2. 約430のプロパティ/カスタムプロパティを論理グループごとに並べる
3. compile.tsのGLOBAL_PROPERTY_ORDERとしてインポートされ、プロパティインデックスの比較に使用される

**関連システム・外部連携**：外部システムとの連携はない。Tailwind CSS内部のソートアルゴリズムにのみ使用される。

**権限による制御**：権限による制御はない。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | 画面に直接関連しない内部データ定義 |

## 機能種別

データ定義（CSSプロパティのソート順序表）

## 入力仕様

### 入力パラメータ

本機能はデータ定義であり、入力パラメータは存在しない。

### 入力データソース

静的に定義されたプロパティ名の配列をデフォルトエクスポートする。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| default export | string[] | プロパティ名の順序付き配列。インデックスがソート優先度を表す |

### 出力先

compile.tsにGLOBAL_PROPERTY_ORDERとしてインポートされる。

## 処理フロー

### 処理シーケンス

```
本機能はデータ定義であるため、処理フローは存在しない。
モジュールの読み込み時に静的な配列が確定する。
```

### フローチャート

```mermaid
flowchart TD
    A[property-order.ts読み込み] --> B[プロパティ順序配列をエクスポート]
    B --> C[compile.tsがGLOBAL_PROPERTY_ORDERとして参照]
    C --> D[compileCandidatesのソート処理でインデックス比較に使用]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-34-01 | レイアウト優先 | container-type, position, inset等のレイアウト系プロパティが先頭に配置される | 常に |
| BR-34-02 | ボックスモデル | margin, box-sizing, display, width/height等のボックスモデルがレイアウトの後に配置 | 常に |
| BR-34-03 | フレックス/グリッド | flex, grid関連プロパティがボックスモデルの後に配置 | 常に |
| BR-34-04 | 装飾 | border, background, shadow, filter等のビジュアル装飾が後半に配置 | 常に |
| BR-34-05 | トランジション | transition, will-change等のアニメーション関連が末尾に配置 | 常に |
| BR-34-06 | カスタムプロパティ | --tw-で始まる内部カスタムプロパティは関連する標準プロパティの近くに配置 | 常に |
| BR-34-07 | 省略→個別の順序 | 省略プロパティ（margin）は個別プロパティ（margin-top等）より前に配置 | 常に |
| BR-34-08 | 論理→物理の順序 | 論理プロパティ（margin-inline）は物理プロパティ（margin-left等）より前に配置 | 常に |

### 計算ロジック

プロパティのソート優先度は配列のインデックスで表される:
- インデックスが小さい → 先に出力される（優先度低）
- インデックスが大きい → 後に出力される（優先度高、スタイル上書き力が強い）
- 配列に存在しないプロパティはInfinityとして扱われ、末尾に配置される

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

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

データベース操作なし。

## エラー処理

### エラーケース一覧

エラーケースなし。静的データ定義である。

### リトライ仕様

リトライは不要。

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

トランザクション管理なし。

## パフォーマンス要件

- 静的配列であるため、モジュール読み込み時に1回のみ初期化される
- compile.tsでのプロパティインデックス検索にはindexOf()が使用されるため、O(n)の計算コストがかかるが、配列サイズは約430要素で固定のため実用上問題ない

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

特になし。

## 備考

- プロパティ順序はTailwind CSSのデザイン判断に基づくものであり、CSS仕様で規定されたものではない
- `--tw-container-component`のようなTailwind固有のカスタムプロパティも順序表に含まれている
- コメントに`// Not real`と記されたプロパティ（例: `border-start-radius`）は、CSS仕様には存在しないがTailwind内部で使用される仮想プロパティ名である

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | property-order.ts | `packages/tailwindcss/src/property-order.ts` | プロパティ順序配列の全体構造と各グループの境界 |

**読解のコツ**:
- ファイルは1つのdefault export配列のみで構成される（1-433行目）
- コメントで各グループの意図が説明されている
- `--tw-`で始まるエントリはTailwind内部のカスタムプロパティ
- 配列の先頭（container-type）から末尾（forced-color-adjust）まで、レイアウト→装飾→アニメーションの論理順

**主要なプロパティグループ**:
- **1-19行目**: レイアウト（container-type, position, inset系）
- **21-49行目**: z-index, order, grid配置, float, margin系
- **51-61行目**: box-sizing, display, サイズ（width/height）
- **63-66行目**: flex
- **68-73行目**: テーブル
- **77-93行目**: transform系
- **99-132行目**: スクロール関連
- **134-137行目**: リスト
- **140-149行目**: グリッド/フレックスレイアウト
- **151-175行目**: 配置、overflow、gap
- **186-236行目**: border系
- **238-320行目**: 背景、マスク、グラデーション
- **329-368行目**: テキスト、フォント
- **370-397行目**: 色、opacity、shadow
- **399-419行目**: filter、backdrop-filter
- **421-433行目**: transition、will-change、content

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | compile.ts | `packages/tailwindcss/src/compile.ts` | GLOBAL_PROPERTY_ORDERのインポート（4行目）とソートでの使用 |

**主要処理フロー**:
- **4行目**: `import GLOBAL_PROPERTY_ORDER from './property-order'`
- **83-115行目**: compileCandidates内のastNodes.sort()でプロパティ順序を使って比較

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

```
property-order.ts
    │ (default export: string[])
    │
    └─ compile.ts (import as GLOBAL_PROPERTY_ORDER)
           │
           ├─ getPropertySort()
           │      └─ GLOBAL_PROPERTY_ORDER.indexOf(property)
           │
           └─ compileCandidates()
                  └─ astNodes.sort() → プロパティ順序比較
```

### データフロー図

```
[定義]                       [参照]                              [使用]

property-order.ts      ───▶ compile.ts                   ───▶ ソート比較
string[433]                  GLOBAL_PROPERTY_ORDER              indexOf()で
["container-type",           │                                  プロパティの
 "pointer-events",          └─ getPropertySort()               インデックスを取得し
 "visibility",                  walk(nodes) →                  astNodes.sort()で
 "position",                    property → index               順序比較に使用
 ...]
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| property-order.ts | `packages/tailwindcss/src/property-order.ts` | ソース | プロパティ順序表の定義（default export） |
| compile.ts | `packages/tailwindcss/src/compile.ts` | ソース | GLOBAL_PROPERTY_ORDERとしてインポートし、ソート比較に使用 |
| sort.ts | `packages/tailwindcss/src/sort.ts` | ソース | getClassOrder経由で間接的にプロパティ順序を利用 |
