---

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: 状態抽出のワークフロー
• state-patterns.md: 一般的な状態パターンと検出ルール
• 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 の存在確認

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

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

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

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: 各状態のデザイン情報を取得

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

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. セクションを特定

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

## UI状態

2. ステータスを更新

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

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

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

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

5. 変更履歴に追記

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

出力形式

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

## 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: 詳細なワークフロー
• state-patterns.md: 状態パターン集
• section-template.md: セクション出力テンプレート
• managing-screen-specs: 仕様書管理スキル