---
name: documenting-screen-flows
description: Documents screen-to-screen navigation flows, user journeys, and state transitions across multiple screens. Updates the "画面フロー" section in screen spec.md.
allowed-tools: [Read, Write, Glob, mcp__figma__get_screenshot, mcp__figma__get_design_context, mcp__figma__get_metadata]
---

# Screen Flow Documentation Skill

画面間のナビゲーションフロー、ユーザージャーニー、状態遷移を整理するスキルです。

## 目次

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

## 概要

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

1. **画面遷移の整理**: どの画面からどの画面へ遷移するか
2. **遷移トリガー**: 遷移を引き起こすアクション
3. **遷移パラメータ**: 画面間で受け渡すデータ
4. **条件分岐**: 条件による遷移先の違い
5. **フロー図**: Mermaid形式での可視化

## 禁止事項

**以下は絶対に行わないこと：**
- ルーティング実装コードの生成（React Router/Next.js等）
- 特定のナビゲーションライブラリの提案
- 技術スタック固有の実装詳細

このスキルの目的は「画面間の関係性」の**情報整理のみ**です。

## 適用条件

このスキルは**複数画面間の遷移がある場合**に適用します。

### 適用する場合

- 一覧 → 詳細 の遷移がある
- フォーム → 確認 → 完了 の遷移がある
- 条件によって遷移先が分岐する
- モーダル/ダイアログの表示がある
- タブ/ステップの切り替えがある

### 適用しない場合

- 単一画面で完結する
- 他画面への遷移がない

**遷移がない場合**、spec.md の画面フローセクションに「該当なし」と記載します。

## 出力先

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

```
.outputs/{screen-id}/
├── spec.md                 # ← このスキルが「画面フロー」セクションを更新
├── index.html              # 参照用HTML
└── assets/
```

## クイックスタート

### 基本的な使い方

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

エージェントは自動的に：
1. 画面内の遷移トリガーを検出
2. 遷移先を特定
3. 遷移条件を整理
4. フロー図を生成
5. **spec.md の「画面フロー」セクションを更新**

## 詳細ガイド

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

- **[workflow.md](references/workflow.md)**: 画面フロー整理のワークフロー
- **[flow-patterns.md](references/flow-patterns.md)**: 一般的なフローパターン
- **[section-template.md](references/section-template.md)**: セクション出力テンプレート

## Workflow

画面フロー整理時にこのチェックリストをコピー：

```
Screen Flow Documentation Progress:
- [ ] Step 0: spec.md の存在確認
- [ ] Step 1: 遷移トリガーを検出
- [ ] Step 2: 遷移先を特定
- [ ] Step 3: 遷移パラメータを整理
- [ ] Step 4: 条件分岐を整理
- [ ] Step 5: フロー図を生成
- [ ] Step 6: spec.md の「画面フロー」セクションを更新
```

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

```bash
ls .outputs/{screen-id}/spec.md
```

### Step 1: 遷移トリガーを検出

画面内で遷移を引き起こす要素を特定：

- リンク（`<a>`）
- ナビゲーションボタン
- カードクリック
- フォーム送信
- モーダル表示ボタン
- 戻るボタン

### Step 2: 遷移先を特定

各トリガーの遷移先を整理：

| トリガー | 遷移先 | 種別 |
|----------|--------|------|
| 講座カードクリック | 講座詳細画面 | push |
| 戻るボタン | 前の画面 | pop |
| ログインボタン | ログインモーダル | modal |

### Step 3: 遷移パラメータを整理

画面間で受け渡すデータを特定：

| 遷移 | パラメータ | 型 | 説明 |
|------|-----------|-----|------|
| 一覧 → 詳細 | courseId | string | 講座ID |
| 検索 → 一覧 | query | string | 検索キーワード |

### Step 4: 条件分岐を整理

条件によって遷移先が変わるケースを整理：

| 条件 | 遷移先A | 遷移先B |
|------|---------|---------|
| ログイン済み | マイページ | ログイン画面 |
| フォーム有効 | 確認画面 | エラー表示（遷移なし） |

### Step 5: フロー図を生成

Mermaid形式でフロー図を生成。

### Step 6: spec.md の「画面フロー」セクションを更新

1. セクションを特定（`## 画面フロー`）
2. ステータスを「完了 ✓」に更新
3. `{{SCREEN_FLOWS_CONTENT}}` を内容に置換
4. 完了チェックリストを更新
5. 変更履歴に追記

## 出力形式

### spec.md「画面フロー」セクションの内容

```markdown
## 画面フロー

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

### この画面の位置づけ

| 項目 | 値 |
|------|-----|
| 画面ID | course-list |
| 画面名 | 講座一覧 |
| 前の画面 | ホーム, 検索結果 |
| 次の画面 | 講座詳細, フィルターモーダル |

### 遷移一覧

#### この画面への遷移（流入）

| 元画面 | トリガー | パラメータ |
|--------|----------|-----------|
| ホーム | 「講座一覧」リンク | - |
| 検索結果 | 検索実行 | query: 検索キーワード |
| カテゴリ一覧 | カテゴリ選択 | categoryId: カテゴリID |

#### この画面からの遷移（流出）

| 遷移先 | トリガー | パラメータ | 種別 |
|--------|----------|-----------|------|
| 講座詳細 | カードクリック | courseId: 講座ID | push |
| フィルターモーダル | フィルターボタン | - | modal |
| 検索結果 | 検索実行 | query: 検索キーワード | push |
| ホーム | ロゴクリック | - | replace |

### 遷移パラメータ

#### courseId

| 項目 | 値 |
|------|-----|
| 型 | string |
| 必須 | ✓ |
| 説明 | 講座の一意識別子 |
| 例 | "course-123" |
| 取得元 | 講座カードのdata-id属性 |

#### query

| 項目 | 値 |
|------|-----|
| 型 | string |
| 必須 | - |
| 説明 | 検索キーワード |
| 例 | "プログラミング" |
| 取得元 | 検索入力フィールド |

### 条件分岐

| 条件 | True時の遷移 | False時の遷移 |
|------|-------------|---------------|
| ログイン済み | マイページへ | ログインモーダル表示 |
| 検索結果あり | 結果表示 | Empty状態表示（遷移なし） |

### フロー図

\`\`\`mermaid
flowchart LR
    subgraph 流入
        Home[ホーム]
        Search[検索結果]
        Category[カテゴリ一覧]
    end
    
    subgraph 現在の画面
        CourseList[講座一覧]
    end
    
    subgraph 流出
        Detail[講座詳細]
        Filter[フィルターモーダル]
        SearchResult[検索結果]
    end
    
    Home -->|講座一覧リンク| CourseList
    Search -->|検索実行| CourseList
    Category -->|カテゴリ選択| CourseList
    
    CourseList -->|カードクリック| Detail
    CourseList -->|フィルターボタン| Filter
    CourseList -->|検索実行| SearchResult
    Filter -->|適用/閉じる| CourseList
\`\`\`

### 画面スタック

ナビゲーションスタックの想定：

\`\`\`
[ホーム] → [講座一覧] → [講座詳細]
                ↑
            モーダル: フィルター
\`\`\`

### 特記事項

- 講座詳細からの戻りは講座一覧に戻る（popナビゲーション）
- フィルターモーダルは画面遷移ではなくオーバーレイ
- ログイン必須の操作はログインモーダルを挟む
```

## 完了チェックリスト

生成後、以下を確認：

```
- [ ] spec.md の「画面フロー」セクションが更新されている
- [ ] ステータスが「完了 ✓」になっている
- [ ] 流入元が整理されている
- [ ] 流出先が整理されている
- [ ] 遷移パラメータが明確
- [ ] 条件分岐が整理されている
- [ ] フロー図が生成されている
- [ ] 完了チェックリストが更新されている
- [ ] 変更履歴に記録が追加されている
```

## 遷移がない場合

他画面への遷移がない画面の場合、以下のように記載：

```markdown
## 画面フロー

> **ステータス**: 該当なし  
> **生成スキル**: documenting-screen-flows  
> **更新日**: 2024-01-15

この画面には他画面への遷移がありません。
```

## 注意事項

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

このスキルは「画面フロー」セクションのみを更新します。

### extracting-interactions との違い

| 観点 | extracting-interactions | documenting-screen-flows |
|------|------------------------|-------------------------|
| 対象 | コンポーネントの状態変化 | 画面間の遷移 |
| 内容 | hover, pressed, トランジション | ナビゲーション, パラメータ |
| 単位 | 単一画面内 | 複数画面間 |

### フロー図の記法

Mermaid flowchart記法を使用：

- `flowchart LR`: 左から右へのフロー
- `flowchart TD`: 上から下へのフロー
- `-->`: 通常の遷移
- `-->|ラベル|`: ラベル付き遷移
- `subgraph`: グループ化

## 参照

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