# 機能設計書 78-Color

## 概要

本ドキュメントは、Avaloniaフレームワークにおける色定義機能（Color）の設計仕様を記述する。Colorは、ARGB（Alpha、Red、Green、Blue）形式で色を表現する不変構造体であり、色の解析、変換、比較機能を提供する。

### 本機能の処理概要

Colorは、UIにおける色を表現する基本的なデータ型である。16進数カラーコード、RGB/RGBA関数形式、HSL/HSV形式、既知の色名など、多様な形式からの色解析をサポートする。また、HSL（Hue、Saturation、Lightness）やHSV（Hue、Saturation、Value）形式への変換機能も提供する。

**業務上の目的・背景**：UIデザインにおいて、色は視覚的な情報伝達の重要な要素である。Color構造体により、デザイナーが指定した色を正確にアプリケーションに反映でき、異なる色空間間の変換も可能になる。これにより、カラーピッカー、テーマシステム、データビジュアライゼーションなど多様な機能を実現できる。

**機能の利用シーン**：SolidColorBrushの色指定、XAMLでの色定義、カラーピッカーでの色選択、テーマの色設定、グラデーションの色停止点など。

**主要な処理内容**：
1. ARGB成分の保持
2. 各種形式からの色解析（Parse、TryParse）
3. HSL/HSV形式への変換
4. 整数表現との相互変換
5. 等値比較

**関連システム・外部連携**：Brush系クラス、GradientStop、ColorPicker、テーマシステムと連携する。

**権限による制御**：本機能は純粋なデータ型であり、特別な権限制御は存在しない。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 18 | ColorPicker | 補助機能 | 色選択で使用される色値 |

## 機能種別

データ型定義 / 色表現

## 入力仕様

### 入力パラメータ（コンストラクタ）

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| a | byte | Yes | アルファ成分（0-255） | - |
| r | byte | Yes | 赤成分（0-255） | - |
| g | byte | Yes | 緑成分（0-255） | - |
| b | byte | Yes | 青成分（0-255） | - |

### Parse入力形式

| 形式 | 例 | 説明 |
|------|-----|------|
| 16進数（6桁） | #FF0000 | RGB形式 |
| 16進数（8桁） | #FFFF0000 | ARGB形式 |
| 16進数（3桁） | #F00 | RGB短縮形式 |
| 16進数（4桁） | #FF00 | ARGB短縮形式 |
| rgb() | rgb(255, 0, 0) | CSS RGB関数 |
| rgba() | rgba(255, 0, 0, 0.5) | CSS RGBA関数 |
| hsl() | hsl(0, 100%, 50%) | CSS HSL関数 |
| hsv() | hsv(0, 100%, 100%) | HSV関数 |
| 色名 | Red, Blue, Green | 既知の色名 |

### 入力データソース

- XAMLマークアップでの色指定
- Color.Parse()、Color.TryParse()による文字列解析
- Color.FromArgb()、Color.FromRgb()、Color.FromUInt32()によるコード生成

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| A | byte | アルファ成分 |
| R | byte | 赤成分 |
| G | byte | 緑成分 |
| B | byte | 青成分 |
| ToUInt32() | uint | 32ビット整数表現 |
| ToHsl() | HslColor | HSL形式への変換 |
| ToHsv() | HsvColor | HSV形式への変換 |
| ToString() | string | 文字列表現 |

### 出力先

- SolidColorBrushのColorプロパティ
- GradientStopのColorプロパティ
- 各種UI要素の色プロパティ

## 処理フロー

### 処理シーケンス

```
1. 色の生成
   └─ Parse/FromArgb/FromRgb/FromUInt32
2. 形式判定（Parse時）
   └─ #形式/rgb形式/hsl形式/色名
3. 値の抽出
   └─ 各成分をbyteとして保持
4. 利用
   └─ ブラシ等への適用
```

### フローチャート

```mermaid
flowchart TD
    A[Parse開始] --> B{#で始まる?}
    B -->|Yes| C[TryParseHexFormat]
    B -->|No| D{rgb/rgba?}
    D -->|Yes| E[TryParseCssFormat]
    D -->|No| F{hsl/hsla?}
    F -->|Yes| G[HslColor.TryParse + ToRgb]
    F -->|No| H{hsv/hsva?}
    H -->|Yes| I[HsvColor.TryParse + ToRgb]
    H -->|No| J[KnownColors.GetKnownColor]
    C --> K{解析成功?}
    E --> K
    G --> K
    I --> K
    J --> K
    K -->|Yes| L[Color生成]
    K -->|No| M[FormatException]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-78-01 | 不変性 | Colorは不変構造体である | 常時 |
| BR-78-02 | 既知色優先 | ToString()は既知の色名があればそれを返す | ToString()呼び出し時 |
| BR-78-03 | 16進数形式 | 既知色名がなければ#AARRGGBB形式で返す | ToString()呼び出し時 |

### 計算ロジック

**ToUInt32()**:
```csharp
return ((uint)A << 24) | ((uint)R << 16) | ((uint)G << 8) | (uint)B;
```

**FromUInt32(uint value)**:
```csharp
A = (byte)((value >> 24) & 0xff)
R = (byte)((value >> 16) & 0xff)
G = (byte)((value >> 8) & 0xff)
B = (byte)(value & 0xff)
```

**RGB to HSL変換**:
- max = Max(R, G, B)
- min = Min(R, G, B)
- chroma = max - min
- lightness = (max + min) / 2
- saturation = chroma / (1 - |2*lightness - 1|)
- hue = 色相計算（R/G/Bのどれが最大かで分岐）

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| FormatException | 解析エラー | Parse()で無効な色文字列 | 有効な色形式を指定 |
| ArgumentNullException | 引数エラー | Parse()にnullを渡した場合 | nullでない文字列を指定 |

### リトライ仕様

本機能にリトライ仕様は存在しない。

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

本機能にトランザクション管理は存在しない。

## パフォーマンス要件

- Colorは軽量な構造体（4バイト）
- TryParseは例外を投げないため高速
- 既知色のキャッシュで高速なParse

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

本機能はデータ型のみを担当するため、特別なセキュリティ考慮事項は存在しない。

## 備考

- Colorはreadonly structで不変
- IEquatable<Color>を実装し効率的な比較が可能
- アニメーション用のColorAnimatorが別途存在

---

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

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

### 推奨読解順序

#### Step 1: 構造体定義を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Color.cs | `src/Avalonia.Base/Media/Color.cs` | Color構造体の定義 |

**主要処理フロー**:
- **24-46行目**: A/R/G/Bプロパティとコンストラクタ
- **71-74行目**: FromArgb()静的メソッド
- **83-86行目**: FromRgb()静的メソッド
- **94-101行目**: FromUInt32()静的メソッド
- **108-121行目**: Parse()メソッド
- **144-200行目**: TryParse()メソッド（複数形式対応）
- **273-323行目**: TryParseHexFormat()（16進数解析）
- **328-436行目**: TryParseCssFormat()（CSS形式解析）
- **470-473行目**: ToUInt32()メソッド
- **479-482行目**: ToHsl()メソッド
- **488-491行目**: ToHsv()メソッド
- **526-590行目**: ToHsl()静的メソッド（RGB→HSL変換）
- **600-724行目**: ToHsv()静的メソッド（RGB→HSV変換）

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

```
Color.Parse(string)
    │
    ├─ TryParse(string, out Color)
    │      │
    │      ├─ TryParseHexFormat() → FromUInt32()
    │      │
    │      ├─ TryParseCssFormat() → new Color()
    │      │
    │      ├─ HslColor.TryParse() → ToRgb()
    │      │
    │      ├─ HsvColor.TryParse() → ToRgb()
    │      │
    │      └─ KnownColors.GetKnownColor() → ToColor()
    │
    └─ FormatException（失敗時）
```

### データフロー図

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

"#FF0000" ─────▶ TryParseHexFormat ─────▶ Color(255,255,0,0)
                       │
"rgb(255,0,0)" ──▶ TryParseCssFormat ───▶ Color(255,255,0,0)
                       │
"hsl(0,100%,50%)" ─▶ HslColor.TryParse ──▶ Color(255,255,0,0)
                       │
"Red" ─────────▶ KnownColors ───────────▶ Color(255,255,0,0)
                       │
                       ▼
                 SolidColorBrush
                 GradientStop
                 etc.
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Color.cs | `src/Avalonia.Base/Media/Color.cs` | ソース | Color構造体 |
| HslColor.cs | `src/Avalonia.Base/Media/HslColor.cs` | ソース | HSL色空間 |
| HsvColor.cs | `src/Avalonia.Base/Media/HsvColor.cs` | ソース | HSV色空間 |
| KnownColors.cs | `src/Avalonia.Base/Media/KnownColors.cs` | ソース | 既知色定義 |
| KnownColor.cs | `src/Avalonia.Base/Media/KnownColor.cs` | ソース | 既知色列挙 |
| SolidColorBrush.cs | `src/Avalonia.Base/Media/SolidColorBrush.cs` | ソース | 単色ブラシ |
| GradientStop.cs | `src/Avalonia.Base/Media/GradientStop.cs` | ソース | グラデーション停止点 |
| ColorAnimator.cs | `src/Avalonia.Base/Animation/Animators/ColorAnimator.cs` | ソース | 色アニメーション |
