画面仕様(UI) 作成ルール

本ドキュメントは、業務分析・要求定義のために 画面仕様（User Interface: UI）を統一形式で記述する標準ルールです。

1. 全体方針

• 画面仕様は、業務ユーザー視点での画面の目的・表示項目・操作・遷移を明確に記述します。
• 画面の機能に着目し、画面のレイアウトやワイヤーフレームは含めません。
• 実装詳細（例: 物理テーブル名、SQL、実装クラス/関数名、UIコンポーネント名）は記載しません。
• 1ファイル = 1画面。

2. 用語定義

用語	定義
画面	業務ユーザーが操作する単位。目的・表示項目・操作・遷移を持つ
表示項目	画面に表示する情報（一覧列、詳細項目、集計値、メッセージ等）
操作	ユーザーが実行できるアクション（検索、登録、更新、削除、確定等）
遷移	画面間の移動。条件・遷移先・引き渡し（識別子など）を含む
バリデーション	入力値の妥当性判定（必須、形式、範囲、相関等）
エラー表示	入力不備・権限不足・対象なし等をユーザーに伝える表示

3. ファイル命名・ID規則

• ファイル名: uis-<番号>-<短い日本語名>.md（例: uis-0010-商品一覧.md）
• Frontmatter:
  • id: uis-product-list のように小文字ハイフン形式
  • title: 「商品一覧」などの画面名

4. 推奨 Frontmatter 項目

項目	説明	必須
id	画面ID（小文字ハイフン）	○
type	screen 固定	○
title	画面名	○
status	draft/ready/deprecated	○
based_on	根拠となる仕様ID（API/ドメイン/他画面など）	任意

NG/OK例（抜粋）

• NG例: id: UI_ProductList（大文字/アンダースコアNG）, type: domain（screen以外NG）, extra: foo（未定義プロパティNG）
• OK例: id: uis-product-list, type: screen, status: ready

5. 本文構成（標準テンプレ）

各 UI 仕様ファイルは以下見出しを順番に並べます。

1. 概要
2. 対象ユーザー/利用目的
3. 表示項目
4. 操作
5. 遷移
6. バリデーション
7. エラー表示
8. メモ / 将来課題

6. 記述ガイド詳細

6.1 概要

短い一文で「この画面が何をするか」を業務用語で書きます。

6.2 対象ユーザー/利用目的

• 対象ユーザー（例: 店員、店主）
• 利用目的（例: 商品を検索し、詳細確認や販売登録へ進む）

6.3 表示項目

• 一覧/詳細/集計など、画面で表示する項目を列挙します。
• レイアウト指定ではなく、何が表示されるかを記述します。

推奨フォーマット:

項目名	種別	表示形式	編集可	必須	備考
商品名	一覧	テキスト	-	-	部分一致検索対象
販売価格	一覧	金額	-	-	税込/税別は別途ルールに従う

6.4 操作

• ユーザーが実行できる操作を列挙し、前提条件と結果（更新/遷移）を明確にします。
• クリック手順の逐語列挙ではなく、操作の意味を書きます。
• ボタンなどのUI部品は原則として列挙しません（操作に包含します）。
  • 例外: 誤解を避ける必要がある場合のみ、備考に**表示ラベル（文言）**を補足してもよい（レイアウト指定はしない）。

推奨フォーマット:

操作名	対象	前提条件	結果（更新/遷移）
検索	検索条件	なし	条件に合致する商品一覧を表示
新規登録	-	権限がある	商品登録画面へ遷移

6.5 遷移

遷移元/遷移先/遷移条件/引き渡す識別子（概念レベル）を明確にします。

推奨フォーマット:

遷移名	遷移先	条件	引き渡し	備考
詳細へ	商品詳細（uis-product-detail）	一覧行を選択	商品ID	-

6.6 バリデーション

入力欄がある場合、必須/形式/範囲/相関（開始日 ≤ 終了日など）を列挙します。

6.7 エラー表示

代表的な2〜4ケース（入力不備、権限不足、対象なし等）と、ユーザーに見せるメッセージ方針（短く・行動可能）を記述します。

7. 命名・記述スタイル

• 画面名は「名詞＋用途」: 例 商品一覧, 売上登録, 在庫照会
• 操作名は短く動詞で: 例 検索, 登録, 更新, 取消, 確定
• 画面/項目/操作は業務用語で統一し、略語は用語集にあるもののみ使用します

8. 階層分解ガイド

シグナル	分割検討
表示項目が多い（>30）	目的別に分割（一覧/詳細/設定等）
操作が多い（>10）	サブ画面または別仕様へ分割
遷移先が多い（>6）	目的別に導線を分ける

9. 禁止事項

項目	理由
ワイヤーフレーム/座標/ピクセル指定	設計変更に弱く、要求定義段階で過剰
物理テーブル名・カラム名・SQL全文	概念レベル逸脱
実装クラス/関数名・UIコンポーネント名	実装依存で変更に弱い
クリック手順の逐語列挙	可読性低下・変更に弱い

10. よくある誤りと対策

• 「どのDBを参照するか」を書く → 「どの概念データを表示するか」に置換
• クリック手順を長文で列挙 → 操作の前提条件と結果（遷移/更新）に要約
• 表示項目が列挙だけで目的が不明 → 「対象ユーザー/利用目的」を先に明確化

11. サンプル（簡易）

---
id: uis-product-list
type: screen
title: 商品一覧
status: draft
part_of: []
based_on: []
---

## 概要

商品を検索し、詳細確認や登録に進むための一覧画面。

## 対象ユーザー/利用目的

- 対象ユーザー: 店員
- 利用目的: 商品を検索して販売登録に必要な情報を確認する

## 表示項目

| 項目名         | 種別 | 表示形式 | 編集可 | 必須 | 備考            |
| -------------- | ---- | -------- | ------ | ---- | --------------- |
| 商品名         | 一覧 | テキスト | -      | -    | -               |
| 販売価格       | 一覧 | 金額     | -      | -    | -               |
| 商品ステータス | 一覧 | ラベル   | -      | -    | 販売中/販売停止 |

## 操作

| 操作名   | 対象     | 前提条件       | 結果（更新/遷移）            |
| -------- | -------- | -------------- | ---------------------------- |
| 検索     | 検索条件 | なし           | 条件に合致する商品一覧を表示 |
| 詳細表示 | 一覧行   | 対象が存在する | 商品詳細へ遷移               |

## 遷移

| 遷移名 | 遷移先                         | 条件         | 引き渡し | 備考 |
| ------ | ------------------------------ | ------------ | -------- | ---- |
| 詳細へ | 商品詳細（uis-product-detail） | 一覧行を選択 | 商品ID   | -    |

## バリデーション

- 検索条件（商品名）: 100文字以内

## エラー表示

- 検索結果0件: 「該当する商品がありません」
- 権限不足: 「権限がありません」

## メモ / 将来課題

将来: タグ検索を追加

12. 生成 AI への指示テンプレート

生成 AI に画面仕様を作らせるときは、以下のような指示を与えます（このテンプレート内に禁止事項を含め、参照前提にしません）。

• 以下のルールに従って、画面仕様（UI） を 1 画面分作成してください。出力は Markdown とします。

• 対象は 1 つの画面（uis-xxx-xxxx）です。業務ユーザー視点で、目的・表示項目・操作・遷移を明確にしてください。

• 禁止: ワイヤーフレーム/座標指定、物理テーブル名・カラム名・SQL全文、実装クラス/関数名、UIコンポーネント名、クリック手順の逐語列挙

• 本文構成は、次の見出し（日本語）をこの順序で必ず出力してください：

  1. 概要
  2. 対象ユーザー/利用目的
  3. 表示項目
  4. 操作
  5. 遷移
  6. バリデーション
  7. エラー表示
  8. メモ / 将来課題

• 先頭に YAML Frontmatter を付与し、以下の形式で記述してください（id / type / title / status は必須）：

  ---
  id: uis-<英小文字とハイフンで構成したID> # 例: uis-product-list
  type: screen
  title: <画面名> # 例: 商品一覧
  status: draft # draft / ready / deprecated のいずれか
  part_of: []
  based_on: []
  ---

• 表示項目 は、項目名と意味が分かるようにテーブル形式で列挙してください（レイアウト指定は禁止）。

• 操作 は、前提条件と結果（更新/遷移）を明確にし、クリック手順ではなく操作の意味を書いてください。

• ボタン等のUI部品を列挙せず、操作として記述してください。必要な場合のみ、操作の備考として表示ラベル（文言）を補足してください（レイアウト指定は禁止）。

• 遷移 は、遷移先・条件・引き渡し（商品ID等）を明確にしてください。