---
name: documenting-ui-states
description: Documents all UI state variations (default, empty, error, loading, success) from Figma designs. Use when defining complete UI specifications before implementation.
allowed-tools: [Read, Write, Glob, mcp__figma__get_screenshot, mcp__figma__get_design_context, mcp__figma__get_metadata]
---

# UI States Documentation Skill

Figmaデザインから全てのUI状態バリエーション（default, empty, error, loading等）を抽出・整理するスキルです。

## 目次

1. [概要](#概要)
2. [クイックスタート](#クイックスタート)
3. [詳細ガイド](#詳細ガイド)
4. [出力形式](#出力形式)

## 概要

このスキルは以下のタスクをサポートします：

1. **状態バリエーション検出**: Figmaフレーム名から状態を自動検出
2. **状態一覧の整理**: 各状態の条件・表示内容を文書化
3. **未定義状態の特定**: 実装に必要だがFigmaに存在しない状態を明示
4. **状態遷移の整理**: 状態間の遷移条件を文書化

## 禁止事項

**以下は絶対に行わないこと：**
- 実装コードの生成（React/Vue/SwiftUI等）
- 状態管理ライブラリの提案（Redux/Zustand等）
- 技術スタック固有の実装詳細

このスキルの目的は「どのような状態があるか」の**情報整理のみ**です。

## 出力先

このスキルは**画面仕様書（spec.md）の「UI状態」セクション**を更新します。

```
.outputs/{screen-id}/
├── spec.md                 # ← このスキルが「UI状態」セクションを更新
├── index.html              # converting-figma-to-htmlで生成済み
└── assets/                 # 画像等
```

**重要**: 単独ファイル（ui_states.md）は生成しません。必ず spec.md 内のセクションを更新してください。

## クイックスタート

### 基本的な使い方

```
以下のFigma画面のUI状態を整理してください：
https://figma.com/design/XXXXX/Project?node-id=1234-5678
```

エージェントは自動的に：
1. Figmaフレーム一覧を取得
2. 状態バリエーションを検出（_Empty, _Error, _Loading等）
3. 各状態のスクリーンショット・情報を取得
4. **spec.md の「UI状態」セクションを更新**

## 詳細ガイド

詳細な情報は以下のファイルを参照してください：

- **[workflow.md](references/workflow.md)**: 状態抽出のワークフロー
- **[state-patterns.md](references/state-patterns.md)**: 一般的な状態パターンと検出ルール
- **[section-template.md](references/section-template.md)**: セクション出力テンプレート

## Workflow

状態整理時にこのチェックリストをコピー：

```
UI States Documentation Progress:
- [ ] Step 0: spec.md の存在確認（なければ初期化）
- [ ] Step 1: Figmaフレーム一覧を取得
- [ ] Step 2: 状態バリエーションを検出
- [ ] Step 3: 各状態のデザイン情報を取得
- [ ] Step 4: 状態一覧を整理
- [ ] Step 5: 未定義状態を特定
- [ ] Step 6: 状態遷移条件を整理
- [ ] Step 7: spec.md の「UI状態」セクションを更新
```

### Step 0: spec.md の存在確認

```bash
# spec.md が存在するか確認
ls .outputs/{screen-id}/spec.md

# 存在しない場合はテンプレートから初期化
cp .agents/templates/screen-spec.md .outputs/{screen-id}/spec.md
# 基本情報（{{SCREEN_NAME}}等）を置換
```

### Step 1: Figmaフレーム一覧を取得

```bash
mcp__figma__get_metadata(fileKey, nodeId)
```

親フレーム（ページまたはセクション）を指定し、子フレーム一覧を取得。

### Step 2: 状態バリエーションを検出

フレーム名から状態を自動検出：

| パターン | 検出される状態 |
|----------|---------------|
| `Screen_Default`, `Screen` | default |
| `Screen_Empty`, `Screen_NoData` | empty |
| `Screen_Error`, `Screen_Failed` | error |
| `Screen_Loading`, `Screen_Skeleton` | loading |
| `Screen_Success`, `Screen_Complete` | success |
| `Screen_Disabled` | disabled |
| `Screen_Selected`, `Screen_Active` | selected |
| `Screen_Expanded`, `Screen_Open` | expanded |
| `Screen_Collapsed`, `Screen_Closed` | collapsed |

### Step 3: 各状態のデザイン情報を取得

検出した各状態フレームに対して：

```bash
mcp__figma__get_screenshot(fileKey, nodeId)
mcp__figma__get_design_context(fileKey, nodeId)
```

### Step 4: 状態一覧を整理

各状態について以下を文書化：

- **状態名**: default, empty, error, loading等
- **条件**: この状態になる条件
- **表示内容**: 主要な表示要素の説明
- **Figma Node**: 参照用ノードID
- **差分**: default状態との違い

### Step 5: 未定義状態を特定

一般的に必要だがFigmaに存在しない状態を明示。

### Step 6: 状態遷移条件を整理

状態間の遷移を文書化（Mermaid stateDiagram-v2）。

### Step 7: spec.md の「UI状態」セクションを更新

**重要**: 以下の手順で spec.md を更新

1. **セクションを特定**

```markdown
<!-- 
================================================================================
SECTION: UI状態
Generated by: documenting-ui-states
================================================================================
-->

## UI状態
```

2. **ステータスを更新**

```markdown
> **ステータス**: 完了 ✓  
> **生成スキル**: documenting-ui-states  
> **更新日**: {DATE}
```

3. **プレースホルダー `{{UI_STATES_CONTENT}}` を内容に置換**

4. **完了チェックリストを更新**

```markdown
- [x] UI状態 (documenting-ui-states)
```

5. **変更履歴に追記**

```markdown
| {DATE} | UI状態 | documenting-ui-statesにより生成 |
```

## 出力形式

### spec.md「UI状態」セクションの内容

```markdown
## UI状態

> **ステータス**: 完了 ✓  
> **生成スキル**: documenting-ui-states  
> **更新日**: 2024-01-15

### 状態一覧

| 状態 | 条件 | Figma Node |
|------|------|------------|
| default | データが正常に取得できた場合 | `1234:5679` |
| empty | データが0件の場合 | `1234:5680` |
| loading | API通信中 | `1234:5681` |
| error | API通信失敗 | `1234:5682` |

### 状態詳細

#### default
- **条件**: データが正常に取得できた場合
- **表示内容**: メインコンテンツを表示
- **Figma Node**: `1234:5679`

#### empty
- **条件**: データが0件の場合
- **表示内容**: 空状態イラスト + メッセージ + アクションボタン
- **Figma Node**: `1234:5680`
- **default との差分**: リスト部分が空状態UIに置換

[他の状態も同様...]

### 未定義状態

| 状態 | 必要性 | 推奨対応 |
|------|--------|----------|
| partial_error | 🟡 中 | 一部成功時の表示を設計者に確認 |

### 状態遷移図

\```mermaid
stateDiagram-v2
    [*] --> loading
    loading --> default: データあり
    loading --> empty: データなし
    loading --> error: API失敗
    error --> loading: リトライ
\```

### 状態遷移表

| From | To | トリガー | 条件 |
|------|-----|----------|------|
| [*] | loading | 画面表示 | - |
| loading | default | APIレスポンス | 成功 & データあり |
| loading | empty | APIレスポンス | 成功 & データなし |
| loading | error | APIレスポンス | 失敗 |
| error | loading | リトライボタン | - |
```

## 完了チェックリスト

生成後、以下を確認：

```
- [ ] spec.md の「UI状態」セクションが更新されている
- [ ] ステータスが「完了 ✓」になっている
- [ ] 全ての状態バリエーションが記載されている
- [ ] 各状態の条件が明確に記載されている
- [ ] default状態との差分が明示されている
- [ ] 未定義状態がリストアップされている
- [ ] 状態遷移が整理されている
- [ ] 完了チェックリストが更新されている
- [ ] 変更履歴に記録が追加されている
```

## 注意事項

### 他のセクションを変更しない

このスキルは「UI状態」セクションのみを更新します。
他のセクション（構造・スタイル、インタラクション等）は変更しないでください。

### Figma命名規則

状態バリエーションの検出は**Figmaのフレーム命名規則**に依存します。
命名規則が不明確な場合は、設計者に確認してください。

### 部分状態 vs 画面状態

- **画面状態**: 画面全体の状態（loading, error等）→ このスキルで扱う
- **部分状態**: 画面内の特定コンポーネントの状態（ボタンのhover等）→ extracting-interactions で扱う

## 参照

- **[workflow.md](references/workflow.md)**: 詳細なワークフロー
- **[state-patterns.md](references/state-patterns.md)**: 状態パターン集
- **[section-template.md](references/section-template.md)**: セクション出力テンプレート
- **[managing-screen-specs](../managing-screen-specs/SKILL.md)**: 仕様書管理スキル