# バッチ設計書 21-Figma to CSS Variables

## 概要

本ドキュメントは、FigmaからCSS変数を自動同期し、プルリクエストを作成するバッチ「Figma to CSS Variables」の設計について記載する。

### 本バッチの処理概要

このバッチは、Figmaデザインファイルからローカル変数（カラー、サイズ、スペーシング等）を取得し、Style Dictionaryを使用してCSS変数に変換し、変更があった場合に自動でプルリクエストを作成する処理を行う。

**業務上の目的・背景**：デザイナーがFigmaで定義したデザイントークン（色、サイズ、スペーシング等）をフロントエンドのCSSに手動で反映する作業は、転記ミスや反映漏れのリスクがある。本バッチにより、Figmaのデザイントークンをワンクリックで自動同期することで、デザインと実装の一貫性を保ち、デザイナーと開発者間の協業を効率化する。

**バッチの実行タイミング**：手動実行のみ（workflow_dispatch）。デザイナーがFigma上でデザイントークンを更新した後、開発者またはデザイナーがGitHub Actionsから手動でトリガーする運用を想定している。

**主要な処理内容**：
1. Figma APIを使用してローカル変数をJSON形式で取得
2. 取得したFigma変数をStyle Dictionary形式に変換
3. Style Dictionaryでビルドし、CSS変数ファイルを生成
4. 生成されたCSS変数ファイルをコミットし、プルリクエストを自動作成

**前後の処理との関連**：本バッチは独立したワークフローであり、前提となるバッチはない。後続処理として、作成されたPRのレビュー・マージ、およびマージ後のデプロイが続く。

**影響範囲**：フロントエンドアプリケーションのスタイル定義（`apps/service-site/src/styles`ディレクトリ配下のCSSファイル）。UIパッケージ（`packages/ui/src/styles`）への同期も別途可能。

## バッチ種別

データ連携（外部APIからのデータ取得・変換・コード生成）

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時（手動実行のみ） |
| 実行時刻 | 任意 |
| 実行曜日 | N/A |
| 実行日 | N/A |
| トリガー | workflow_dispatch（手動） |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| Figma APIアクセストークン | `FIGMA_ACCESS_TOKEN`シークレットが設定されていること |
| FigmaファイルKey | `FIGMA_FILE_KEY`シークレットが設定されていること |
| Figmaファイルへのアクセス権 | 指定されたFigmaファイルに対する読み取り権限があること |
| ローカル変数の定義 | Figmaファイル内にローカル変数が定義されていること |

### 実行可否判定

- workflow_dispatchイベントでトリガーされた場合に実行される
- 環境変数（`FIGMA_FILE_KEY`、`FIGMA_ACCESS_TOKEN`）が設定されていない場合はエラー終了

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| --output | string | No | build/css | CSS変数ファイルの出力先パス |
| --filter-modes | string | No | なし | カンマ区切りのモード名フィルタ（例: "Dark,Mode 1"） |
| --fetch | flag | No | - | Figma変数取得のみ実行 |
| --transform | flag | No | - | 変数変換のみ実行 |
| --generate | flag | No | - | CSSビルドのみ実行 |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| Figma API | JSON | `/v1/files/{file_key}/variables/local`エンドポイントからローカル変数を取得 |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| apps/service-site/src/styles/{mode}/variables.css | CSS | 各モード別のCSS変数定義ファイル |
| GitHub Pull Request | PR | 変更があった場合に自動作成されるPR |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | variables.css |
| 出力先 | {outputPath}/{mode}/ |
| 文字コード | UTF-8 |
| フォーマット | CSS variables形式（`--variable-name: value;`） |

## 処理フロー

### 処理シーケンス

```
1. 環境準備
   └─ pnpmセットアップ、依存関係インストール
2. Figmaローカル変数取得（fetchFigmaLocalVariables）
   └─ Figma APIからローカル変数をJSONで取得し、tmp/local-variables.jsonに保存
3. Style Dictionary形式への変換（transformVariablesForStyleDictionary）
   └─ JSONからデザイントークン形式に変換し、tmp/transformed-variables/配下に保存
4. CSS生成（runStyleDictionary）
   └─ Style Dictionaryでビルドし、指定パスにvariables.cssを出力
5. プルリクエスト作成
   └─ 変更がある場合、peter-evans/create-pull-requestでPRを作成
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B[pnpmセットアップ]
    B --> C[fetchFigmaLocalVariables]
    C --> D{API取得成功?}
    D -->|成功| E[transformVariablesForStyleDictionary]
    D -->|失敗| Z[エラー終了]
    E --> F[runStyleDictionary]
    F --> G{ファイル変更あり?}
    G -->|あり| H[create-pull-request]
    G -->|なし| I[変更なしで終了]
    H --> J[PR作成完了]
    I --> K[バッチ終了]
    J --> K
    Z --> K
```

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

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

本バッチはデータベース操作を行わない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| ENV_ERROR | 環境変数エラー | FIGMA_FILE_KEYまたはFIGMA_ACCESS_TOKENが未設定 | GitHub Secretsに必要な値を設定する |
| API_ERROR | API通信エラー | Figma APIからのレスポンスがエラー | Figmaアクセストークンの有効性確認、ファイルKeyの確認 |
| TRANSFORM_ERROR | 変換エラー | 変数のフォーマットが不正 | Figmaでの変数定義を確認 |
| BUILD_ERROR | ビルドエラー | Style Dictionaryのビルドに失敗 | 変換済みJSONの形式を確認 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | なし（手動実行のため） |
| リトライ間隔 | N/A |
| リトライ対象エラー | N/A |

### 障害時対応

1. GitHub Actionsのログを確認してエラー箇所を特定
2. 環境変数エラーの場合はSecretsの設定を確認
3. API通信エラーの場合はFigmaアクセストークンの有効期限を確認
4. 必要に応じてワークフローを再実行

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | N/A（ファイル操作のみ） |
| コミットタイミング | 全ファイル生成完了後 |
| ロールバック条件 | N/A（PRが作成されなければ変更は適用されない） |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 数百〜数千の変数 |
| 目標処理時間 | 15分以内（timeout-minutes設定） |
| メモリ使用量上限 | 制限なし（GitHub Actions標準ランナー） |

## 排他制御

- `concurrency`設定により、同一ワークフローの同一ブランチでの同時実行を制限
- `cancel-in-progress: true`により、新しい実行がトリガーされた場合、実行中のジョブはキャンセルされる

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | 各ステップ開始時 | GitHub Actionsのステップ名 |
| 進捗ログ | Figma変数取得後 | "Local variables fetched and saved to tmp/local-variables.json" |
| 進捗ログ | 変換完了後 | "Variables transformed and saved to tmp/transformed-variables/" |
| 終了ログ | ビルド完了後 | "Style Dictionary build complete." |
| エラーログ | エラー発生時 | "Error: {エラーメッセージ}" |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| 処理時間 | 15分 | GitHub Actionsワークフロー失敗通知 |
| ワークフロー失敗 | 発生時 | リポジトリのActions通知設定に依存 |

## 備考

- ワークフローは手動実行のみ（cronスケジュールなし）
- デフォルトの出力先は`apps/service-site/src/styles`
- フィルターモードとして"Dark"と"Mode 1"が指定されている
- PRのブランチ名は`maintenance/sync-figma-to-css-variables`で固定
- `delete-branch: true`により、PRマージ後にブランチは自動削除される
- peter-evans/create-pull-request v7.0.8を使用
