product-ui-prototyping

プロダクト UI プロトタイピング

概要

生成・編集した画面画像を使って、プロダクトのアイデアをテスト可能な UI の動作に変換します。状態ごとのビジュアル、クリックして確認できる画面遷移のロジック、プラットフォームごとのビューアーを作成し、実装前にチームが最初から最後まで操作できるようにします。

プロトタイプのフォルダー規約（プロジェクト内）

• プロトタイプごとに、現在のプロジェクトの ui-prototypes/ ディレクトリ内にフォルダーを作成または使用します。
  • ui-prototypes/<prototype-name>/
• それぞれのプロトタイプが自己完結するよう、すべての成果物をそのフォルダーにまとめます。
• <prototype-name> には、内容がわかりやすい kebab-case の名前を付けます。
• 画像アセットはプラットフォームごとに分けます。
  • ui-prototypes/<prototype-name>/images/web/<flow>/...
  • ui-prototypes/<prototype-name>/images/ios/<flow>/...
  • ui-prototypes/<prototype-name>/images/android/<flow>/...
• フローマップはプラットフォームとフローごとに分けます。
  • ui-prototypes/<prototype-name>/flow-maps/<platform>/<flow>.json
• 各画像に対応する正確な生成・編集プロンプトをマッピングするマニフェストを用意します。
  • ui-prototypes/<prototype-name>/image-prompt-manifest.md
  • ui-prototypes/<prototype-name>/prompts/<platform>/<flow>/<screen>-<state>.md
• ユーザーが別の場所を指定した場合は、指定されたパスに従います。

入力方針（柔軟）

• ui-prototypes/<prototype-name>/experience-story.md が存在する場合は、画面、アクション、画面遷移の上流ソースとして使用します。
• 存在しない場合は、そのまま進め、このワークフロー内で画面と画面遷移を定義します。
• 特定の上流ファイルがないことを理由に、プロトタイピングを止めないでください。

ワークフロー

音声通知（Speak ツール、必須）

• ユーザーが画面を常に見ていなくても済むよう、重要な段階の開始・完了を知らせる際は Speak ツールを使用します。
• 絶対ルール：以下の各重要段階について、段階の開始時と完了時の両方で必ず音声通知します（選択的に省略してはいけません）。
• 音声通知が必須の段階：
  • ワークフロー開始（prototype target acknowledged、next stage）
  • 画面遷移モデルの段階（started、続いて ui-behavior-test-matrix.md drafted/updated）
  • プラットフォームとフローごとのベースライン画面の段階（started、続いてベースライン一式を書き込み済み）
  • プラットフォームとフローごとのインタラクション状態の段階（started、続いて状態一式を書き込み済み）
  • マニフェスト同期の段階（started、続いて image-prompt-manifest.md を更新し、整合性を確認済み）
  • クリック可能な一式の作成段階（started、続いてフローマップとビューアーを書き込み済み）
  • ビューアーのスモークテスト段階（started、続いて Pass／Fail の結果）
  • 最終引き渡し段階（started、続いてパッケージの完成）
• 音声通知のトリガーポリシー：
  • 必須の段階開始・完了通知を省略しないでください。
  • 完了通知は、マイルストーンが確実に完了した後（ファイルを書き込み、関連するチェック結果が判明した後）にのみ行います。
  • 段階開始・完了の必須通知の間に行う、途中の草稿やプロンプトの反復については通知しません。
  • マイルストーンの更新が短時間に続く場合は、短いメッセージ1つにまとめます。
• 音声メッセージはそれぞれ1～2文の短いものとし、ステータスを先に伝え、次のステップを明確に1つ示します。
• Speak ツールが失敗した場合、または使用できない場合は、ワークフローを続け、同じ更新内容をテキストで伝えます。
• シークレット、トークン、機密性の高いペイロード全体を読み上げないでください。

ツール実行時のルール

• 画像ツールの呼び出しは、必ず1つずつ実行します。
• 画面や状態が異なる複数の画像生成・編集呼び出しを、並行して実行しないでください。
• 各呼び出しの完了を待ち、出力を確認してから次の呼び出しを行います。
• 複数の画面や状態をまとめて処理する場合は、順序が定まったキューに従って逐次処理します。
• 画像ツールを呼び出す際は、常に絶対ファイルシステムパスを使用します。
• 生成画像には、必ず絶対パスの output_file_path を指定します。
• 編集呼び出しでは、ソース画像に絶対パスを使用します。

プロンプトの系譜と更新の規律

• 反復更新では、最新の承認済みソース画像（「シェル」）を基準にした edit image をデフォルトで使用します。
• 初回のドラフト、大幅な構造のリセット、または編集を繰り返しても精度を回復できない場合は、generate image を使用します。
• 画像を更新する前に、マニフェストの Prompt Path から現在のプロンプトを読み込み、Parent Image（存在する場合）を特定します。
• 現在のプロンプトを更新して次のプロンプトを作成します（変更しない制約は維持し、要求された差分のみを変更し、変更しない領域を明記します）。
• 更新したプロンプトは、最新の唯一の正本として同じプロンプトパスに保存します。
• 編集操作では、プロンプトファイルに次の内容を記載する必要があります。
  • 人間による意図のヘッダー：UI Purpose、User Can Do、Transition Outcome
  • 遷移メタデータ：Trigger、From State、To State
  • 入出力の関連付け：Input Image、想定する Output Image
• 差し替え更新では、ユーザーが新しいバリアントを明示的に要求しない限り、新しい画像を同じ画像パスに書き込みます。
• ユーザーが分岐を明示的に要求しない限り、バージョンが増殖するプロンプトファイル（v2、v3 など）は作成しません。
• 各画面／フローにつき正本のシェルを1つだけ維持し、状態バリアントはそのシェルまたは承認済みの派生物から作成します。

遷移のトレーサビリティモデル

• ドキュメントを、次の4つの関連レイヤーとして扱います。
  • 正本となる動作の意図：ui-behavior-test-matrix.md（transition_id、トリガー、遷移元／遷移先の状態、受け入れ確認項目）
  • ナビゲーションのランタイム：flow-maps/<platform>/<flow>.json の遷移（動作マトリックスから派生）
  • 編集の実行：対象状態のプロンプトファイル（正確な編集プロンプトと遷移メタデータ）
  • 成果物の系譜：image-prompt-manifest.md（入力／出力画像のパスと親子関係）
• 1つの遷移については、4つすべてのレイヤーで同じ transition_id を使用します。
• 反復間で同じ画像パスを再利用する場合は、最新の出力をディスク上に保持し、プロンプトファイルに反復ログのセクション（差分の簡潔な要約と前回の入力画像パス）を追記します。

成果物のライフサイクルに関する規律（必須）

• 最新のプロダクトビジョンと現在有効なユースケースに合致するアクティブな成果物だけを維持します。
• ユースケース／フロー／画面／状態が無効、非推奨、または旧式になった場合は、次の場所から該当ファイルを削除します。
  • images/
  • prompts/
  • flow-maps/
  • viewer/（フローを削除する場合）
• ユーザーがアーカイブを明示的に要求しない限り、「念のため」に非推奨の成果物を残してはいけません。
• 命名が古い、または不明瞭な場合は、現在のプロダクト用語とユースケースの意図を反映するよう、ファイル／フォルダー名を変更します。
• 名前の変更や削除を行った後は、同じ変更内で次のすべての参照を更新します。
  • image-prompt-manifest.md
  • フローマップの screens[].image パス
  • ビューアーマップのパス設定
• プラットフォーム、フロー、画面、状態が伝わる、安定した説明的なケバブケースの名前を優先します。

アスペクト比に関する規律

• すべての画像生成プロンプトで、アスペクト比を明示します。
• サポート対象の比率のみを使用します：1:1、4:3、3:4、3:2、2:3、5:4、4:5、16:9、9:16、21:9。
• プラットフォームとフローの組み合わせごとに、すべての画面／状態で比率を固定し、歪みのばらつきを避けます。
• 編集では、ベースラインとなるソース画像と同じ比率を維持します。
• ユーザーが明示的に要求しない限り、生成した画像の比率を統一したり、引き伸ばしたり、再エンコードしたりしないでください。

1) プロダクトの意図と制約を定義する

• 対象プラットフォーム（web、ios、android）とビューポートの前提を定義します。
• サポート対象の比率一覧から、プラットフォーム／フローごとの目標アスペクト比を定義します。
• ユーザーペルソナ、主な達成目標、重要な操作経路を定義します。
• ブランドのトーン、アクセシビリティ要件、コンポーネントのスタイル、データ密度など、デザイン上の制約を定義します。
• アセットを生成する前に、忠実度のレベル（wireframe、mid、high）を定義します。
• ローカルビューアーで操作可能にするプラットフォーム／フローの組み合わせを定義します。

2) 画面、アクション、状態をマッピングする

• 各フローの状態遷移表を作成します。
  • transition_id（gateway_validate_to_success などの安定したキー）
  • screen
  • trigger（クリック／タップ／送信／ナビゲーション／システムイベント）
  • from_state
  • to_state
  • expected_feedback（視覚的なフィードバック＋マイクロコピー）
• この表を正とし、マップ／マニフェスト内のすべての遷移 ID を表に合わせます。
• 該当する場合、最低限、default、focus、pressed、disabled、loading、success、error、empty を網羅します。
• まず重要なフローを 1 つ優先し、その後、二次的なフローへ範囲を広げます。

3) 正式なプロダクトベース仕様を 1 つ作成し、シェルを固定する

• 再利用可能な product_base_spec（プラットフォーム、ビューポート、タイポグラフィ、間隔、トークン、アクセシビリティの意図）を 1 つ作成します。
• 画面間のスタイルのずれを防ぐため、すべての生成／編集プロンプトで同じベース仕様を再利用します。
• 各画面について、状態を分岐させる前に正式なシェル画像を作成し、固定します。
• 最初の生成結果が正確でない場合は、レイアウトとビジュアルアイデンティティが安定するまで、同じシェルを繰り返し編集します。

4) ベースライン画面を生成する

• 画像生成ツールを使って、新規画面のドラフトを生成します。
• ドラフトの精度が十分でない場合は、正式なシェルが固定されるまで edit image を繰り返して調整します。
• ベースライン作業は順番に進めます。ツール呼び出し 1 回につき画面を 1 つ処理し、次に進む前に結果を確認します。
• 各生成プロンプトで比率を明示し、そのプラットフォーム＋フローでは一定に保ちます。
• すべての生成／編集ツール呼び出しで、絶対パスの output_file_path を使用します。
• 各ベースライン画像に使用した正確なプロンプトを、次の場所に保存します。
  • ui-prototypes/<prototype-name>/prompts/<platform>/<flow>/<screen>-default.md
• 決定的なスタイル指示と共有ベース仕様を使用し、画面間でタイポグラフィ、間隔、アイコン、色の一貫性を保ちます。
• 固定したシェルの出力を、安定した構成で保存します。
  • ui-prototypes/<prototype-name>/images/<platform>/<flow>/<screen>-default.png
• 対象のプラットフォーム＋フローのベースライン画面一式が実際に書き込まれた後に、完了を伝えます。

5) ベースラインからインタラクション状態を作成する

• 状態を繰り返し更新する場合は、固定済みのシェル（または直近で承認された状態の前段）から edit image を使用するのを基本とします。
• 状態の作成に generate image を使用するのは、意図的に構造を大きく変える必要がある場合に限ります。
• 更新後のプロンプトでも、変更しない制約と固定されたシェル要素を引き継ぎ、レイアウトとビジュアルアイデンティティの一貫性を保ちます。
• 状態更新は順番に進めます。更新ごとにツール呼び出しを 1 回行い、次に進む前に結果を確認します。
• すべての編集呼び出しで、ソース画像の比率を維持します。
• 編集の入力と output_file_path には絶対パスを使用します。
• 編集呼び出しごとに、ツール呼び出しの入出力をマニフェストの行に記録します。
  • Input Image（必須）
  • Output Image（分岐がない限り Image Path と同じ）
• 編集した各状態を、次の遷移タプル 1 つに対応させます。
  • (transition_id, trigger, from_state, to_state)
• 編集した各画像に使用した正確なプロンプトを、次の場所に保存します。
  • ui-prototypes/<prototype-name>/prompts/<platform>/<flow>/<screen>-<state>.md
• 状態に関連する差分のみを編集します。
  • ホバー／フォーカスリング
  • 押下時の深さ
  • 無効状態のコントラスト
  • 読み込み中の表示
  • 検証／成功／エラーメッセージ
• 出力を次の場所に保存します。
  • ui-prototypes/<prototype-name>/images/<platform>/<flow>/<screen>-<state>.png
• 対象のプラットフォーム＋フローのインタラクション状態一式が実際に書き込まれた後に、完了を伝えます。

6) 画像／プロンプトマニフェストを維持する（必須）

• ui-prototypes/<prototype-name>/image-prompt-manifest.md をリアルタイムで維持します。
• このマニフェストを最新の信頼できる情報源として扱います（現在のアーティファクトセットのみ）。
• 画像アーティファクトごとに1行追加します（default と各編集状態）。
• 各行には、最低限次の項目を記録します。
  • Transition ID
  • Use Case
  • Platform
  • Flow
  • Screen
  • State
  • Trigger
  • From State
  • To State
  • Situation/Purpose
  • Image Path
  • Input Image（編集の場合）
  • Prompt Path
  • Source（Generate／Edit）
  • Parent Image（編集状態の場合）
• images/ 内の各画像に、マニフェスト内で対応する行が1行だけあることを確認します。
• すべての Edit 行で、Input Image と遷移タプル（Trigger、From State、To State）が空でないことを確認します。
• 置換更新では、新しい行を作成せず、既存のマニフェスト行を更新します。
• 画像またはプロンプトを置換・削除した場合は、古い行やレガシー行を削除します。
• 現在のプロトタイプリビジョンで有効な画像／プロンプトのペアのみを残します。
• アーティファクトを削除または名前変更した場合は、マニフェストとファイルシステムが1対1で対応するよう、行をただちに更新または削除します。
• マニフェストの同期が実際に書き込まれ、現在のアーティファクトと整合してから完了を報告します。

7) 画面を接続してクリック操作可能なシミュレーションを作成する

• プラットフォームとフローの組み合わせごとに、フローマップを1つ作成します。
  • ui-prototypes/<prototype-name>/flow-maps/<platform>/<flow>.json
• ui-behavior-test-matrix.md からマップの遷移を導出します。独立した遷移定義を維持してはいけません。
• リンクごとに次の定義を含めます。
  • transition_id
  • screen
  • trigger
  • hotspot（x、y、width、height）
  • target_screen
  • transition（instant、fade、slide）
• ホットスポットの命名規則を一貫させ、開発者以外の人もすばやく確認・反復できるようにします。

8) 動作テストマトリックスを作成する

• 遷移ごとに1行を記載した ui-prototypes/<prototype-name>/ui-behavior-test-matrix.md を作成します。
• このファイルを遷移の正式な信頼できる情報源として扱います。
• 次の項目を含めます。
  • transition_id
  • flow
  • screen
  • trigger
  • from_state
  • to_state
  • expected next state image
  • acceptance check
  • open question / risk
• トリガーに対するフィードバックが曖昧、または欠けている場合は、ブロッキングの問題として明示します。
• ui-behavior-test-matrix.md を実際に書き込み、更新してから完了を報告します。

9) 開発者以外の人向けにレビュー用パッケージを用意する

• 簡潔なレビュー用パッケージを作成します。
  • 任意：チームから説明的な概要を求められた場合は、ui-prototypes/<prototype-name>/ui-prototype-spec.md の要約
  • プロンプトと画像の追跡用の ui-prototypes/<prototype-name>/image-prompt-manifest.md
  • クリック操作による画面遷移のリンク用の ui-prototypes/<prototype-name>/flow-maps/<platform>/<flow>.json
  • ローカルでクリック操作できるビューアーファイル ui-prototypes/<prototype-name>/viewer/<platform>/<flow>/
  • フローとプラットフォームごとにまとめた画像ギャラリーへのリンク
  • プロダクト／デザインの承認が必要な未解決の判断事項
• 可能な限り、プロダクト担当者向けの表現を使い、実装に関する専門用語を避けます。

10) ローカルのクリック操作可能なビューアーを公開する

• プラットフォームとフローごとの画像セットについて、ビューアーテンプレートを次の場所にコピーします。
  • ui-prototypes/<prototype-name>/viewer/<platform>/<flow>/
• 各ビューアーのインスタンスが対応するマップファイルを読み込むよう設定します。
  • ../../../flow-maps/<platform>/<flow>.json
• ビューアーのコードでは、マップと画像のURLを必ず絶対ベースURLから解決します。
  • new URL(mapPath, window.location.href) を使ってマップURLを構築します。
  • 解決済みのマップURLを基準に、各 screens[].image を解決します。
• ワークスペースのルートをローカルで配信し、次のURLを開きます。
  • http://localhost:4173/ui-prototypes/<prototype-name>/viewer/<platform>/<flow>/index.html
• プロダクト／デザインレビューでは、プラットフォームとフローごとにビューアーを用意し、各画像セットを直接確認できるようにします。
• 対象のプラットフォームとフローのフローマップおよびビューアーファイルが実際に書き込まれてから、完了を報告します。

11) ビューアーのスモークテスト（必須）

• 引き渡し前に、ビューアーの JavaScript の構文チェックを実行します。
• プロジェクトをローカルで配信し、少なくとも以下を確認します。
  • ビューアーページが読み込まれること
  • フローマップの JSON が読み込まれること
  • 参照されている画像が 1 つ読み込まれること
  • URL 解決エラーなしで開始画面が表示されること
• チェックに失敗した場合は、引き渡し前にビューアーのパス解決を修正します。
• チェックの完了後、ビューアーのスモークテスト結果（Pass／Fail）を伝えます。

プロンプトパターンとチェックリスト

• references/prompt-patterns.md を読み、以下に活用します。
  • UX 基準の網羅と製品の基本仕様
  • 本番画面生成と状態編集のテンプレート
  • シェルロックと反復編集のプロンプトパターン
  • 画像／プロンプトマニフェストのテンプレートと記録チェックリスト
  • フローステップとクロスプラットフォーム対応のテンプレート
  • クリック操作可能なフローマップのテンプレート、ビューアーの互換性ルール、受け入れチェックリスト

デフォルトの出力

• ui-prototypes/<prototype-name>/ui-behavior-test-matrix.md
• ui-prototypes/<prototype-name>/image-prompt-manifest.md
• ui-prototypes/<prototype-name>/prompts/<platform>/<flow>/*.md
• ui-prototypes/<prototype-name>/flow-maps/<platform>/<flow>.json
• ui-prototypes/<prototype-name>/viewer/<platform>/<flow>/index.html
• ui-prototypes/<prototype-name>/viewer/<platform>/<flow>/viewer.css
• ui-prototypes/<prototype-name>/viewer/<platform>/<flow>/viewer.js
• ui-prototypes/<prototype-name>/images/web/<flow>/*.png
• ui-prototypes/<prototype-name>/images/ios/<flow>/*.png
• ui-prototypes/<prototype-name>/images/android/<flow>/*.png

品質ゲート

• 重大なトリガーごとに、状態遷移 1 回以内で明確かつ視認可能なフィードバックが得られることを確認します。
• プラットフォームとフローをまたいで状態の視覚的一貫性が保たれていることを確認します。
• 各プラットフォーム＋フローについて、アスペクト比が明示的に定義され、一貫していることを確認します。
• UI の形状を歪めるような方法で、生成画像の正規化や引き伸ばしが行われていないことを確認します。
• すべての画像に、image-prompt-manifest.md 内の対応するプロンプト記録があることを確認します。
• マニフェストに最新の有効なアーティファクトのみが含まれ、古いレガシー項目が残っていないことを確認します。
• 各反復更新プロンプトが、マニフェストの Prompt Path で参照される現在のプロンプトから派生していることを確認します。
• 意図的な構造変更が記録されていない限り、各状態画像でシェルの連続性（レイアウト／フレーム／間隔／コンポーネントの形状）が保たれていることを確認します。
• 編集した画像の系譜を追跡できることを確認します。Parent Image ＋ Input Image ＋（Trigger、From State、To State）が記録されている必要があります。
• 各マニフェストの Transition ID が ui-behavior-test-matrix.md に存在することを確認します。
• 各フローマップの遷移が、マトリックス内の transition_id および対応するトリガーの意味と一致していることを確認します。
• 削除または無効化されたユースケースに関する古い／非推奨のアーティファクトが残っていないことを確認します。
• ファイル名／フォルダー名が最新の製品ビジョンを反映し、画像、プロンプト、マップ、ビューアー間で一貫していることを確認します。
• エラー状態と空の状態に、復旧方法の案内が含まれていることを確認します。
• アクセシビリティの手がかり（フォーカスの視認性、コントラストの意図、読みやすい階層構造）がモックアップに反映されていることを確認します。
• 各フローマップのクリック操作可能なトリガーが、有効な遷移先画面を指していることを確認します。
• 各プラットフォーム＋フローのビューアーで、クリック可能な各ホットスポットと開始画面のナビゲーションが機能することを確認します。
• 各プラットフォーム＋フローのバンドルで、ビューアーのスモークテストに合格することを確認します。

引き渡し

• 承認済みの動作仕様と状態アセットを実装担当者に引き渡します。
• 次にエンジニアリング計画が求められた場合は、ui-prototypes/<prototype-name>/ui-behavior-test-matrix.md、関連する ui-prototypes/<prototype-name>/flow-maps/<platform>/<flow>.json ファイル、ui-prototypes/<prototype-name>/image-prompt-manifest.md、およびビューアーの動作に関する注記を入力として、$software-engineering-workflow-skill を呼び出します。
• 必要な引き渡し用アーティファクトをすべて書き込んだ後、最終的な引き渡しの完了を伝えます。