--- name: web-ui-spec description: | **Web UI設計書ジェネレーター＆バリデーター**: 日本語のWeb UI設計書（.xlsx）を新規作成、既存ファイルの品質検証、または改修を行うスキル。 「UI設計書」「画面設計書」「外部設計」「画面仕様書」「Web仕様書」「式样书」と言及された場合はこのスキルを使用する。 Figmaデザインやワイヤーフレームからの設計書生成、既存設計書のレビュー・補完、新規機能の設計書起草にも対応する。 - MANDATORY TRIGGERS: UI設計書、画面設計書、外部設計書、式样书、Web仕様書、画面レイアウト、処理詳細、UI spec --- # Web UI設計書スキル このスキルは、日本のSIer開発プロジェクトで使われる「Web UI設計書（Excel形式）」を高品質に作成・検証するためのガイドである。 単にExcelの「フォーマット」を再現するのではなく、**開発者が迷わず実装できる設計書を書く**ことが目標。設計書の本質は「開発者との契約書」であり、曖昧さは実装コストに直結する。 ## スキルの使い方 ### モード判定 ユーザーの要求に応じて3つのモードで動作する: 1. **新規作成モード** — 「〇〇機能のUI設計書を作って」→ ヒアリング → 生成 2. **検証モード** — 「この設計書をチェックして」→ 品質検証スクリプト実行 → レポート 3. **補完モード** — 「この設計書に△△を追加して」→ 既存ファイル読み込み → 差分追記 ### 最初にやること 1. **xlsx スキル** を読む — Excel操作の技術的ガイド（プラットフォームのxlsxスキルを参照） 2. 本スキルの `references/writing-guide.md` を読む — 記述品質のルール 3. 本スキルの `scripts/validate_spec.py` を検証モードで使う --- ## 第1章 設計書の全体構成 ### シート構成（必須6シート＋任意） | シート名 | 役割 | 視点 | |---------|------|------| | `表紙` | 文書メタ情報 | 管理者向け | | `外部-機能概要` | 何をする機能か、全体像 | PL/PM向け | | `外部-画面レイアウト-{画面名}` | 各UI要素の振る舞い定義 | **フロントエンド開発者向け** | | `内部-処理詳細` | API契約（リクエスト/レスポンス） | **バックエンド開発者向け** | | `別紙-{名称}` | 補足情報（権限表、定数表等） | 全員向け | | `改定履歴` | 変更追跡 | 管理者向け | 画面が複数ある場合、`外部-画面レイアウト-{画面名}` を画面数分作成する。 ### なぜこの構造か 「外部」シートはユーザー視点（画面で何が起きるか）、「内部」シートはシステム視点（APIで何を送受信するか）。この分離により、フロントエンド開発者とバックエンド開発者がそれぞれ自分に関係するシートだけ見ればよい。 --- ## 第2章 画面レイアウトシートの書き方（最重要） このシートが設計書の核心。UI要素ごとに「開発者が実装に必要な全情報」を記述する。 ### オブジェクト定義の構造 各UI要素は以下の階層で記述する: ``` B列: オブジェクトNo.（連番） C列: オブジェクト名（日本語） D列: 定義項目ラベル H列: 定義内容 E列: サブ定義ラベル H列: サブ定義内容 ← 複合要素の場合のみ ``` ### 必須定義項目チェックリスト すべてのインタラクティブ要素（ボタン、アイコン、入力フィールド等）には以下を定義する: | 項目 | 記述内容 | 省略可否 | |------|---------|---------| | **種類** | UI要素のタイプ（ボタン/アイコン/テキスト/ラベル/画像/チェック/ラジオ/リスト） | 必須 | | **属性** | CSS属性等（例: `cursor：pointer`） | インタラクティブ要素は必須 | | **動作** | ユーザー操作→システム応答の因果関係 | 必須 | | **表示制御** | 表示/非表示/活性・非活性の条件 | 条件付き要素は必須 | | **API** | 呼び出すAPIのID（例: `機能ID/操作名`） | API連携がある場合必須 | | **エラー** | エラー条件、メッセージID、表示位置 | エラーが起こりうる操作は必須 | ### 動作（動作）の書き方 — 最も重要 動作の記述が曖昧だと開発者が迷う。以下のルールに従う: **原則: 「条件 → 結果」を明示する** 良い例: ``` 上アイコンを押下する時、表示している社員の直前社員へ切替して表示する 先頭の社員の場合、末尾の社員へ切り替える ``` → 条件（上アイコン押下/先頭の場合）と結果（直前社員へ/末尾へ）が明確 悪い例: ``` 社員を切り替える ``` → いつ？どの方向に？境界条件は？が不明 **複数行に分けて書くべきケース:** - 条件分岐がある場合（各条件を1行ずつ） - 操作手順が複数ステップある場合 - 正常系と異常系を分ける場合 ### 表示制御の書き方 表示制御は「いつ見える/見えない/触れない」を定義する。以下のパターンで書く: ``` 「{条件}の場合、{非表示/非活性/表示}とする」 ``` **網羅すべき状態:** - モード条件: 「一覧モードの場合のみ表示する」 - データ条件: 「顔写真がある場合のみ表示する」 - 権限条件: 「起動権限ある機能のみ表示する」 - 人数条件: 「複数人の場合は非活性とする」 ### エラー定義の書き方 エラーは3列のインラインテーブルで定義する: ``` H列(結合H:AF): エラー条件の説明 ← 薄グレー背景 AG列(結合AG:AQ): メッセージID ← 薄グレー背景 AR列(結合AR:AW): 表示ｵﾌﾞｼﾞｪｸﾄNo ← 薄グレー背景 H列: 「{具体的なエラー条件}」 AG列: MSG_XXXXX ``` **エラー定義で書くべきこと（現実のプロジェクトで不足しがちな部分）:** - エラー条件（いつ発生するか） - メッセージID（メッセージマスター参照用） - エラー後の復帰動作（画面をどう戻すか） - 入力値のバリデーション規則 ### ネスト構造（D→E列）の使い分け **ネストする場合:** - 1つの論理領域に複数の操作がある（例: 顔写真領域 → アップロード/ダウンロード/削除） - 関連する入力要素とアクション要素のペア（例: テキスト入力 + 検索ボタン） **ネストしない場合:** - 単一機能の要素（ラベル表示、単体ボタン等） --- ## 第3章 処理詳細シートの書き方 ### 全体構造 処理詳細シートは「広幅」フォーマット（列A〜AZ）を使用する。共通ヘッダー（行1〜7）は他のシートと同じだが、**行7の追跡バーが異なる**: ``` A7: チケットNo. B7: 参照オブジェクトNo. C7〜AX7(結合): 処理 AY7: 改定日付 AZ7: 改定者 ``` **作成/更新者の扱い**: ヘッダーのAZ列は`${username}`プレースホルダーとする。新規作成時はユーザーに作成者名を確認し、設定ファイルの`author`/`update_author`に設定する。 ### コンテンツ階層（5段インデント） 処理詳細のコンテンツは以下の階層構造を**厳密に**守る。列の使い分けがこのシートの生命線： ``` B列: コンポーネント名（物理名） ← 機能名＋英字物理名（例: 現職エリア（gensyokuarea）） C列: アクション名 ← 「初期表示」は全UIに固定で存在 D列: API名 / APIリクエスト / APIレスポンス ← セクション区分 E列(結合E:Q): パラメーター名 ← テーブルのキー列 R列(結合R:AT): 値/マッピング ← テーブルの値列 AA列: ※補足条件 ← 省略可 ``` ### 具体的な記述パターン（原本に忠実） **第1層: コンポーネント宣言（B列、行8付近）** ``` B9: 現職エリア（gensyokuarea） ``` ここで機能の日本語名＋物理名（括弧付き英字camelCase）を書く。1つのコンポーネントに対して複数のアクションが続く。 **第2層: アクション宣言（C列）** ``` C11: 初期表示 ← 全UIに必ず存在する固定アクション ``` 「初期表示」は画面ロード時のAPI呼び出しを定義する。その後、ユーザー操作ごとにアクションが続く: ``` B41: 1 C41: 社員切替 ← 画面レイアウトのオブジェクトNo.との紐付け B78: 2 C78: 社員コード検索 ``` **第3層: API定義セクション（D列）** ``` D12: API名 D14: APIリクエスト D20: APIレスポンス ``` **第4層: API名（E列）** ``` E13: (共通)現職エリア-表示 ← 「(種別)機能名-操作名」の命名規則 ``` **第5層: リクエストパラメーターテーブル** テーブルヘッダー行（薄グレー背景、thin罫線、center揃え）: ``` E15(結合E:Q): リクエストパラメーター ← F2F2F2背景 R15(結合R:AT): 値 ← F2F2F2背景 ``` データ行（thin罫線、left揃え）: ``` E16(結合E:Q): 社員コードリスト R16(結合R:AT): 表示対象社員の社員コードリスト E17(結合E:Q): 機能ID R17(結合R:AT): アクティブメニューの機能ID E18(結合E:Q): 設定データ R18(結合R:AT): サイドバーの設定メニュー内容 ``` **第6層: レスポンス処理の記述パターン** ``` D20: APIレスポンス E21: レスポンスデータを画面に表示する ← 処理概要テキスト E22: ■ブロック表示 ← 表示モード（■は見出しマーカー） ``` レスポンスマッピングテーブル: ``` E23(結合E:Q): 画面項目 ← F2F2F2背景ヘッダー R23(結合R:AT): レスポンスパラメーター ← F2F2F2背景ヘッダー E24: 項目名 R24: 現職エリアのタイトル AA24: ※現職エリアの空白フラグが「1」の場合、表示しない E25: 項目値 R25: 現職エリアの項目値 AA25: ※現職エリアの空白フラグが「1」の場合、表示しない ``` **AA列の※補足**: レスポンスパラメーターの条件付き表示制御やフラグ解釈を記載する。 ### 画面レイアウトとの対応関係 処理詳細の各アクション（C列）は、画面レイアウトのオブジェクト（B列No.）と対応する: - `初期表示` は対応なし（画面全体の初期化） - `B:1 C:社員切替` → 画面レイアウトのオブジェクトNo.1 - `B:2 C:社員コード検索` → 画面レイアウトのオブジェクトNo.2 ただし1:1ではなく: - 1つのUI要素 → 複数のAPI呼び出し（例: 顔写真領域 → upload/download/delete） - 複数のUI要素 → 同じAPI（例: 社員切替と社員コード検索 → 同じ表示API） ### API契約で書くべきこと リクエストパラメーターには以下を明記する: - パラメーター名（日本語 + 英字キー名の括弧書き。例: `ページ番号（pageNumber）`） - 値の説明（何を渡すか具体的に） - AA列に補足条件（null時の振る舞い、フラグ値の意味等） レスポンスマッピングは表示モードごとに分けて書く（■ブロック表示 / ■一覧表示）。 --- ## 第4章〜第8章: 詳細リファレンス 以下の詳細はコンテキスト効率のため別ファイルに分離している。必要時に参照すること。 | 章 | ファイル | 内容 | |---|---------|------| | 第4章 品質基準 | `references/quality-criteria.md` | レベル1〜3の品質チェックリスト | | 第5章 Excelフォーマット | `references/format-spec.md` | セル配置・列幅・結合パターン・命名規則の定数 | | 第6章 生成ワークフロー | `references/generation-workflow.md` | 新規作成・検証・補完の手順 | | 第7章 Config生成ルール | `references/config-generation-rules.md` | JSON自動生成時の命名・記述ルール | | 第8章 Code2Excel | `references/code2excel-protocol.md` | Spring Boot + Vue のコード逆引き手順・信頼度付きパラメーター抽出 |