| 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. セクションの更新
各スキルは担当セクションのみを更新します。
更新手順
- セクション位置を特定
## {セクション名}
### {サブセクション名}
- プレースホルダーを内容に置換
{{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: テンプレートファイル