---

name: managing-screen-specs description: Initializes and updates screen specification documents. Use as a foundation skill for all screen documentation workflows. allowed-tools: [Read, Write, Glob]

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. セクションの更新

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

更新手順

1. セクション位置を特定

## {セクション名}

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

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

{{PLACEHOLDER}} → 実際の内容

3. 変更履歴に追記

| {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: テンプレートファイル