既存UIから画面横断のUX仕様を作る
画面やワイヤーフレームには、表示要素だけでなく、機能の入口、操作できる条件、遷移先、データの変化が現れている。 しかし、1つの画面を説明するだけでは、複数画面にまたがる処理や、失敗後の回復方法までは共有できない。
この不足を埋める文書を、本ページでは UX仕様 と呼ぶ。 UX仕様は、ユーザーが目的を達成するまでに見る情報、実行する操作、システムの応答、状態の変化を、検証できる形で記録する文書である。
UX仕様は完成した画面からも作成できる。 既存UIを観察して現在の動作を記録し、不明な部分を未決事項として残せば、重要なフローから段階的に仕様を育てられる。
既存の成果物をUX仕様へ統合する
UX仕様は、企画やデザインの成果物をすべて置き換える文書ではない。 各成果物で決まった内容のうち、ユーザーが観測できる振る舞いを取り出し、Screen Spec、Flow Spec、Feature Spec、Pattern Specのいずれかへ統合する。
統合後も、課題を発見した経緯、アイデアの比較、レイアウトの検討過程は元の成果物に残す。 一方、実装と検証で参照する確定済みの振る舞いはUX仕様を正本とし、同じ規則を複数の文書へ複製しない。
| 既存の成果物 | 元の成果物に残す内容 | UX仕様へ統合する内容 | 統合先 |
|---|---|---|---|
| プロダクトブリーフ | 対象ユーザー、課題、提供価値、成功指標 | 機能の目的、対象範囲、ユーザーに提供する結果 | Feature Spec |
| ユーザーストーリー、要件 | 優先順位、採用理由、対象リリース | 機能の規則、権限、状態、受け入れ条件 | Feature Spec |
| ユーザーフロー | 検討案、ジャーニー上の感情や課題 | 開始条件、画面遷移、システム応答、分岐、失敗後の回復 | Flow Spec |
| ワイヤーフレーム、既存UI | レイアウト、視覚表現、デザインの検討過程 | 入口、表示情報、操作と結果、出口、画面固有の状態 | Screen Spec |
| UIの状態一覧 | 状態用語、分類、状態ケースの棚卸し | 対象画面の成立条件、期待する表示と操作 | Screen Spec、Pattern Spec |
| ユーザビリティやアクセシビリティ基準 | 一般原則、適用基準 | 対象機能で観測できる受け入れ条件 | 各UX仕様 |
| デザインレビュー | 証拠、判定、修正提案 | 確認した動作、矛盾、未決事項、修正後に確定した振る舞い | 影響するすべてのUX仕様 |
| 実装Issue | 変更の目的、作業範囲、実装タスク | 今回実装するUX仕様のIDと受け入れ条件 | UX仕様を参照する |
| ADR | 技術や構造に関する重要な決定 | ユーザーが観測できる結果が変わる場合だけ、その変更内容 | UX仕様を更新してADRを参照 |
ユーザー体験の計画は、ユーザー理解からUIデザインまでの検討を扱う。 本ページは、その計画や既存UIから、実装と検証に使える振る舞いを取り出す段階を扱う。
計画からレビューまでを循環させる
UX仕様への統合は、一度だけ行う移行作業ではない。 企画、設計、実装、レビューの各段階で得た決定を、次の順序で仕様へ戻す。
- 要件定義で、機能の目的と共通規則をFeature Specへ記録する。
- ユーザーフローで、開始から完了までの遷移と分岐をFlow Specへ記録する。
- ワイヤーフレームや既存UIから、各画面の表示と操作をScreen Specへ記録する。
- 複数画面や複数機能に繰り返し現れる振る舞いをPattern Specへ切り出す。
- 実装Issueは対象となる仕様IDと受け入れ条件を参照する。
- レビューで見つ けた差分を、観察、矛盾、未決のいずれかとして仕様へ戻す。
- 合意または修正後に確定した内容と変更影響を更新する。
元の成果物とUX仕様が異なる場合は、黙って一方へ合わせない。 根拠と差分を矛盾として記録し、決定後に両者の役割に応じて更新する。
4つの仕様を使い分ける
画面ごとの情報と、画面をまたぐルールを1つの文書へ詰め込むと、同じ決定が重複する。 そこで、対象の違いに応じて4つの仕様へ分ける。
| 種類 | 対象 | 答える問い | IDの例 |
|---|---|---|---|
| Screen Spec | 一つの画面や場所 | 何を表示し、何を操作でき、次にどこへ進むか | SCR-profile-edit |
| Flow Spec | 開始から終了までの画面横断フロー | ユーザーとシステムが、どの順序で何をするか | FLOW-update-profile |
| Feature Spec | 複数画面に現れる一つの機能 | どのルール、権限、状態が全体に適用されるか | FEAT-profile |
| Pattern Spec | 複数機能で再利用する振る舞い | 共通の操作やフィードバックをどう統一するか | PAT-form-submit |
Screen Specは、Flow Specを構成する場所になる。 Feature Specは、複数のScreen SpecとFlow Specで共有するルールの正本になる。 Pattern Specは、特定の機能に依存し ない共通の振る舞いを定める。
すべての種類を最初から用意する必要はない。 1つの画面だけで完結する変更ならScreen Specから始め、同じルールが別画面にも現れた時点でFeature SpecやPattern Specへ切り出す。
根拠の強さを区別する
既存UIに表示されている動作が、意図された仕様とは限らない。 実装の不具合や、更新されていないワイヤーフレームも根拠に含まれるためである。
各決定には、必要な範囲で次の区分を付ける。
- 確定：承認済みの仕様、要件、テスト、外部契約で確認できる内容
- 観察：現在のUIや実装で確認できるが、意図された動作かは確認できない内容
- 推測：観察した内容から補った仮説
- 未決：判断に必要な情報がなく、決定者の確認が必要な内容
- 矛盾：複数の根拠が異なる動作を示している内容
根拠には、文書の見出し、Issue、画面名、ワイヤーフレームのフレーム名、実装箇所、テスト名などを記録する。 確認していない動作を滑らかな文章で補うと、実装者が推測を確定事項として扱ってしまう。
- [確定] Issue #42「プロフィール編集」の完了条件
- [観察] ワイヤーフレーム「プロフィール編集 # 保存中」
- [推測・中] 保存後は詳細画面へ戻る。
現在のボタンと画面構成から推測した。
- [未決] 保存に失敗した場合、入力内容を何分間保持するか。
- [矛盾] ワイヤーフレームは自動再試行、実装は手動再試行を示している。
既存UIから仕様を発掘する
対象と成功条件を決める
最初に、対象ユーザー、達成する目的、開始点、終了条件を決める。 「設定画面を仕様化する」では範囲が画面に閉じるため、「利用者が表示名を変更し、変更後の表示を確認する」のようにユーザーの目的で区切る。
併せて、今回調査しない画面や外部サービスを対象外として記録する。 対象外と未調査を分けることで、仕様がない理由を後から確認できる。
画面の入口と出口を集める
対象となる各画面について、入口、出口、表示する情報、操作、権限による差を記録する。 ボタンやリンクには、押した後の遷移先または結果が必要である。
深いリンク、通知、ブラウザ履歴、戻る操作も入口や出口になり得る。 画面内の主要ボタンだけを追うと、途中離脱や再開の仕様が抜ける。
操作からデータの変化を追う
各操作について、実行条件、即時のフィードバック、成功時の結果、失敗時の結果を確認する。 作成、更新、削除を伴う場合は、どのデータがいつ確定するかも記録する。
同じ操作が複数画面に現れる場合は、画面ごとに異なる点だけをScreen Specへ書く。 共通する権限やデータ更新の規則はFeature Specへ、共通する表示と操作はPattern Specへ置く。
正常系を一本通す
最初の版では、最も重要な正常系と、その正常系に必要な画面だけをつなぐ。 この段階で全画面を列挙するより、開始から成功までを一度通すほうが、画面間で受け渡す情報を確認しやすい。
正常系を記録したら、各ステップで失敗した場合を調べる。 失敗の表示だけでなく、入力や選択を保持するか、再試行できるか、どこから再開するかまで記録する。
状態と例外を追加する
画面の状態名と組み合わせは、UIの状態パターンを正本として使う。 本ページでは同じ状態を再定義せず、Flow SpecやFeature Specから必要な状態ケースを参照する。
次の項目は、対象フローに該当するかを確認する。
- Loading、Empty、Error、部分的な取得、古いデータの表示
- 未入力、形式違反、重複、サーバー側の拒否
- 未認証、権限不足、操作中の権限変更
- 同時編集、別タブからの更新、古い版からの保存
- オフラ イン、接続断、タイムアウト、外部サービスの障害
- 二重送信、再試行、成功応答を受け取れなかった場合
- 取消、戻る、離脱、再開、入力内容の保持
該当しない状態は、理由を確認できる場合だけ対象外とする。 判断できない状態は対象外にせず、未決事項として残す。
アクセシビリティを観測可能な条件にする
ユーザービリティの原則を、対象画面で確認できる条件へ変換する。 たとえば、「アクセシブルにする」では実装結果を判定できない。
次のように、操作と結果を特定する。
- キーボードだけで保存操作へ到達し、実行できる
- 入力エラーが発生すると、エラーの要約へフォーカスが移動する
- 保存結果が画面上の表示だけでなく、支援技術にも通知される
- 色だけに依存せず、エラー箇所と修正方法を特定できる
- 文字を拡大しても、主要な情報と操作を失わない
関連仕様を結ぶ
仕様には安定したIDを付け、双方向に関連付ける。 Screen Specから関連するFlow Spec、Feature Spec、Pattern Specへリンクし、各仕様から使用画面へ戻れるようにする。
同じルールを複数の文書へ複製すると、片方だけを変更した際に矛盾が生じる。 ルールの正本を1つに決め、ほかの文書には参照と、その場所だけに固有の差を書く。
受け入れ条件を書く
受け入れ条件には、ユーザーまたは外部の観測者が確認できる結果を書く。 内部のコンポーネント名や関数呼び出しは、UX仕様の受け入れ条件には含めない。
必要に応じてGiven、When、Thenの順に記述する。 1つの条件には、1つの独立した結果を対応させる。 1つの受け入れ条件を1つの箇条書きとし、Given、When、Thenはそれぞれ改行する。
- Given 編集権限を持つ利用者がプロフィール編集画面を開いている、
When 表示名を変更して保存する、
Then 詳細画面に変更後の表示名を表示する。
- Given 保存中に通信が切断された、
When 保存処理が失敗する、
Then 入力内容を保持したまま、失敗理由と再試行操作を表示する。
- Given キーボードだけで操作している、
When 必須項目を空にして保存する、
Then 最初の入力エラーへ移動できる位置にフォーカスを置く。
正常系だけでなく、データ消失や権限制御に関わる失敗も受け入れ条件に含める。 すべての例外を受け入れ条件へ変換する必要はないが、実装の合否を変える条件は残す。
変更影響を記録する
仕様を変更するときは、変更する文書だけでなく、そこへ入るフローと、そこから出るフローを確認する。 同じFeature SpecやPattern Specを使う画面も影響を受ける可能性がある。
影響先は、次の四区分で記録する。
- 変更対象：今回、仕様を直接変更する対象
- 影響あり：変更に伴って確認または修正が必要な対象
- 確認済み、影響なし：関連を調べ、変更が不要だと判断した対象
- 未確認：関係する可能性があるが、確認先や所有者が分からない対象
| 対象 | 判定 | 影響 | 根拠または対応 |
|---|---|---|---|
| SCR-profile-edit | 変更対象 | 保存中の再送信を止める | FEAT-profileの更新規則を変更する |
| FLOW-update-profile | 影響あり | 保存失敗後の再開手順を追加する | 編集画面を参照している |
| PAT-toast | 確認済み、影響なし | 既存の通知規則を使える | 通知の契約を変更しない |
| 分析イベント | 未確認 | 保存失敗の記録方法を確認する | 所有者を確認する必要がある |
変更影響には、画面とフローのほかに、権限、通知、監査履歴、分析イベント、ヘルプ、テストを含める。 関連仕様が異なる動作を示す場合は、黙って片方へ合わせず、矛盾として決定者へ提示する。
文書の配置例
既存の配置規則がある場合は、その規則を優先する。 新しく置き場所を決める場合は、種類ごとのディレクトリと一覧を用意する。
docs/ux-spec/
├── index.md
├── screens/
├── flows/
├── features/
└── patterns/
index.mdには、必須項目として対象と目的、仕様ID、名称、文書の状態、関連仕様、未決事項をまとめる。
根拠の優先順位、主要フロー、共通語彙、対象外は、該当する場合に追加する。
既存仕様を変更する場合は、更新履歴を追加する。
文書自体の状態（下書き、確認待ち、承認済み、廃止）と、個々の主張の根拠区分は分けて管理する。
仕様のひな型
既存の仕様形式がある場合は、見出し名を合わせる。 最初からすべてのセクションを埋める必要はない。 項目を次の三段階に分け、最小ひな型から書き始める。
| 必須度 | 記載する条件 |
|---|---|
| 必須 | 最初の版から記載する |
| 該当時必須 | 対象にその条件がある場合、または共通仕様を参照できない場合に記載 |
| 更新時必須 | 承認済みま たは実装済みの仕様を変更する場合に記載 |
該当しない追加セクションは、空の見出しとして残さない。 該当するか判断できない場合は省略せず、未決事項として記録する。
アクセシビリティ、エラー、権限、通信障害、競合は必ず適用有無を確認する。 専用セクションを追加する必要がないのは、対象外の理由が分かる場合か、関連するFeature SpecやPattern Specを参照できる場合だけである。
Screen Spec
最小ひな型
---
id: SCR-<slug>
type: screen
status: draft
---
# <画面名>
## 目的と対象範囲
## 入口と出口
## 表示、操作、結果
## 状態
## 受け入れ条件
## 関連仕様、根拠、未決事項
該当時必須のセクションは、対象ユーザーと権限、バリデーションとエラー回復、通信障害、競合と多重実行、画面固有のアクセシビリティ要件である。 既存仕様の変更時は、変更影響を追加する。
Flow Spec
最小ひな型
---
id: FLOW-<slug>
type: flow
status: draft
---
# <ユーザーが達成すること>
## 目的と開始、終了条件
## 正常系
## 主要な分岐と復旧
## 受け入れ条件
## 関連仕様、根拠、未決事項
該当時必須のセクションは、ユーザーと状況、取消と再開、権限による差、競合と多重実行、通信障害とタイムアウト、通知と外部チャネルである。 既存仕様の変更時は、変更影響を追加する。
Feature Spec
最小ひな型
---
id: FEAT-<slug>
type: feature
status: draft
---
# <機能名>
## ユーザー価値
## 対象と対 象外
## ビジネスルール
## 状態と操作
## 画面ごとの現れ方
## 受け入れ条件
## 関連仕様、根拠、未決事項
該当時必須のセクションは、用語と対象オブジェクト、権限、状態のライフサイクル、通知と監査履歴、競合と整合性、通信障害、機能固有のアクセシビリティ要件である。 既存仕様の変更時は、変更影響を追加する。
Pattern Spec
最小ひな型
---
id: PAT-<slug>
type: pattern
status: draft
---
# <共通パターン名>
## 解決する問題と適用範囲
## 振る舞いと状態
## 使用箇所
## 受け入れ条件
## 関連仕様、根拠、未決事項
該当時必須のセクションは、構成要素、コンテンツ規則、キーボードとフォーカスと読み上げ、エラーと回復、バリエーションである。 既存仕様の変更時は、変更影響を追加する。
プロフィール更新の記入例
プロフィール一覧から編集画面を開き、表示名を変更する既存UIを対象とする。 観察できた画面だけで仕様を確定せず、画面横断のフローと不足する決定を分けて記録する。
仕様の構成
| ID | 種類 | 記録する内容 |
|---|---|---|
SCR-profile-list | Screen | 一覧に表示する情報と編集画面への入口 |
SCR-profile-edit | Screen | 入力、保存、取消、各状態の表示 |
FLOW-update-profile | Flow | 一覧から編集し、変更結果を確認するまでの流れ |
FEAT-profile | Feature | 編集権限、表示名の規則、更新結果 |
PAT-form-submit | Pattern | 送信中、成功、失敗、再送信の共通動作 |
正常系
| 番号 | 場所 | ユーザー操作 | システム応答 | データ変化 | 次の場所 |
|---|---|---|---|---|---|
| 1 | プロフィール一覧 | 編集を選ぶ | 現在の値を読み込む | なし | プロフィール編集 |
| 2 | プロフィール編集 | 表示名を変更する | 入力値を検証する | 未保存の変更を保持する | プロフィール編集 |
| 3 | プロフィール編集 | 保存する | 保存中を示し、再送信を止める | 表示名を更新する | プロフィール詳細 |
| 4 | プロフィール詳細 | 変更結果を確認する | 変更後の表示名を示す | なし | フロー終了 |
失敗と復旧
| 失敗点 | ユーザーに見えること | 保持するもの | 回復手段 | 根拠区分 |
|---|---|---|---|---|
| 初期読込 | 読込失敗と再試行操作 | なし | 再試行または一覧へ戻る | 観察 |
| 入力検証 | 対象項目の理由と修正方法 | 入力内容 | 値を修正する | 確定 |
| 保存 | 保存失敗の理由 | 入力内容 | 同じ内容で再試行する | 推測 |
| 保存後の応答 | 保存結果を確認できない状態 | 入力内容 | 詳細画面で結果を確認する | 未決 |
この例では、保存失敗時の入力保持はまだ推測である。 実装を始める前に、保持期間と再試行時の重複更新を決める必要がある。
受け入れ条件
- Given 編集権限を持つ利用者がプロフィール編集画面を開いている、
When 有効な表示名を保存する、
Then 詳細画面に変更後の表示名を表示する。
- Given 表示名が入力規則に違反している、
When 保存する、
Then 理由と修正方法を対象項目の近くに表示する。
- Given 保存処理が進行中である、
When 利用者が保存を再度実行しようとする、
Then 同じ更新を重複して送信しない。
- Given 保存中に通信が切断された、
When 保存処理が失敗する、
Then 入力内容を保持したまま再試行操作を表示する。
更新の単位
UX仕様は、最初から網羅的に完成させる文書ではない。 最重要の正常系、そのフローで起きる主要な失敗、関連画面の順に追加する。
未調査の範囲は未決として残し、次に調査する画面や決定者を添える。 仕様の完成度よりも、確定した内容と不明な内容を区別できることを優先する。
関連文書
- ユーザー体験の計画：UX仕様の前提となるユーザー、価値、体験を計画する
- UIの状態パターン：画面と対象UIの状態名、成立条件、組み合わせを定義する
- ユーザービリティ：画面とフローを評価する基本原則を確認する
- AIエージェント向けUI構築ガイドライン：仕様をUIとして実装する際の制約を確認する
- AIによるモバイルアプリのデザインレビュー：仕様と実機の動作を証拠に基づいて比較する