Screen Spec Management Skill

画面仕様書の初期化とセクション更新を管理するヘルパースキルです。

概要

各スキル（converting-figma-to-html, documenting-ui-states等）は、このスキルの手順に従って画面仕様書を更新します。

ファイル構造

.agents/
├── templates/
│   └── screen-spec.md          # 画面仕様書テンプレート
└── tmp/
    └── {screen-id}/
        ├── spec.md             # 画面仕様書（メインドキュメント）
        ├── index.html          # 参照用HTML
        └── assets/             # 画像等のアセット

テンプレート構造

統一テンプレートは以下のセクションで構成されます：

| セクション | 説明 | |-----------|------| | 概要 | 画面の基本情報（名前、Figma URL、HTML、説明） | | 構造・スタイル | HTML構造とdata-figma属性 | | コンテンツ分析 | 静的/動的コンテンツの分類とAPI依存 | | UI状態 | デフォルト状態、ボタン状態、タブ状態など | | インタラクション | INT-XXX形式でトリガー、アクション、遷移先を定義 | | APIマッピング | APIエンドポイントとの関連付け | | アクセシビリティ | セマンティック要件、フォーカス管理、キーボード操作 | | デザイントークン | カラー、タイポグラフィ、スペーシング | | 画面フロー | mermaid stateDiagram-v2と遷移テーブル | | 変更履歴 | 日付、変更内容、担当の履歴 |

ワークフロー

1. 仕様書の初期化

新しい画面の仕様書を作成する場合：

# テンプレートをコピー
cp .agents/templates/screen-spec.md .outputs/{screen-id}/spec.md

# 基本情報を置換
- {{SCREEN_NAME}} → 画面名
- {{SCREEN_ID}} → 画面識別子
- {{FIGMA_URL}} → Figma URL
- {{HTML_FILE}} → HTMLファイル名
- {{ROOT_NODE_ID}} → ノードID
- {{DATE}} → 作成日
- {{DESCRIPTION}} → 画面の説明

2. セクションの更新

各スキルは担当セクションのみを更新します。

更新手順

セクション位置を特定

## {セクション名}

### {サブセクション名}

プレースホルダーを内容に置換

{{PLACEHOLDER}} → 実際の内容

変更履歴に追記

| {DATE} | {セクション名}を更新 | {担当} |

3. セクション別の責任範囲

| セクション | 担当スキル | 主なプレースホルダー | |-----------|-----------|---------------------| | 概要 | managing-screen-specs | {{SCREEN_NAME}}, {{FIGMA_URL}}, {{HTML_FILE}}, {{DESCRIPTION}} | | 構造・スタイル | converting-figma-to-html | {{HTML_STRUCTURE}}, {{SCREEN_ID}}, {{ROOT_NODE_ID}} | | コンテンツ分析 | converting-figma-to-html | {{CONTENT_NAME}}, {{DATA_ATTRIBUTE}}, {{API_SOURCE}} | | UI状態 | documenting-ui-states | {{ELEMENT_NAME}}, {{ELEMENT_STATE}}, ボタン状態各種 | | インタラクション | extracting-interactions | {{INTERACTION_NAME}}, {{TRIGGER}}, {{ACTION}}, {{DESTINATION}} | | フォーム仕様 | defining-form-specs | （テンプレートには含まない、必要時に追加） | | APIマッピング | mapping-html-to-api | {{API_MAPPING_DESCRIPTION}} | | アクセシビリティ | defining-accessibility-requirements | {{ELEMENT}}, {{ROLE}}, {{ARIA_ATTRS}}, フォーカス/キーボード設定 | | デザイントークン | extracting-design-tokens | カラー/タイポグラフィ/スペーシングの各トークン | | 画面フロー | documenting-screen-flows | {{CURRENT_SCREEN}}, {{NEXT_SCREEN}}, 遷移テーブル |

セクション更新のルール

必須

自分の担当セクションのみを更新する
変更履歴に記録を追加する
プレースホルダーを具体的な内容に置換する

禁止

他のセクションの内容を変更しない
プレースホルダーを削除せずに残さない

初期化の例

入力

画面名: TOP画面
画面ID: top
Figma URL: https://figma.com/design/xxx/Project?node-id=2350:2662
HTMLファイル: top.html
説明: AskAI機能のエントリーポイント画面

出力（spec.md 冒頭部分）

# 画面仕様書: TOP画面

## 概要

| 項目 | 内容 |
| ---- | ---- |
| 画面名 | TOP画面 |
| Figma URL | https://figma.com/design/xxx/Project?node-id=2350:2662 |
| HTML | top.html |
| 説明 | AskAI機能のエントリーポイント画面 |

セクション更新の例

documenting-ui-states による更新

Before:

## UI状態

### デフォルト状態

| 要素 | 状態 | 備考 |
| ---- | ---- | ---- |
| {{ELEMENT_NAME}} | {{ELEMENT_STATE}} | {{ELEMENT_NOTES}} |

After:

## UI状態

### デフォルト状態

| 要素 | 状態 | 備考 |
| ---- | ---- | ---- |
| 背景 | 水色グラデーション表示 | #e1f4ff基調 |
| ナビゲーション | 閉じるボタンのみ表示 | - |
| 写真を共有ボタン | 青背景、有効状態 | #0070e0 |

extracting-interactions による更新

Before:

### INT-001: {{INTERACTION_NAME_1}}

| 項目 | 内容 |
| ---- | ---- |
| トリガー | {{TRIGGER}} |
| 前提条件 | {{PRECONDITION}} |
| アクション | {{ACTION}} |
| API | {{API_CALL}} |
| 遷移先 | {{DESTINATION}} |

After:

### INT-001: 写真を共有ボタンタップ

| 項目 | 内容 |
| ---- | ---- |
| トリガー | 「写真を共有」ボタンをタップ |
| 前提条件 | - |
| アクション | OSのアクションシートを表示 |
| API | なし |
| 遷移先 | action-sheet.html |

仕様書の完了判定

全ての必須セクションが具体的な内容で埋まったら完了です。

必須セクション

概要
構造・スタイル
コンテンツ分析
UI状態
インタラクション
APIマッピング
アクセシビリティ
デザイントークン
画面フロー
変更履歴

条件付きセクション（必要に応じて追加）

フォーム仕様: 入力フォームがある場合

参照

screen-spec.md: テンプレートファイル