build-prototype

プロトタイプを構築する

全体の画面を網羅した、使い捨て可能でありながら完成品のように見えるモデルを構築し、実装前に構造、関係性、動作をユーザーが決められるようにします。

プロダクト層と意思決定層を分けます。prototype.html には正式なプロダクト画面とフローを配置し、一時的な compare.html では、現在のユーザーの疑問を具体的な状況に応じて解決します。比較の範囲は、意思決定に必要な対象に合わせて、コンポーネント、画面、短いフローのいずれかに限定します。

ユーザーがどの端末でプレビューを開く必要があるか不明な場合は、作業を実行しているコンピューターだけで確認するのか、別の端末でも確認するのかを一度だけ尋ねます。ホストが対応していれば、作業を妨げない質問を使用します。対応していない場合は、確認端末に依存しない構築を完了してから尋ねます。実行ホストから確認端末を推測したり、回答がないことを選択として扱ったりしないでください。特定のプラットフォームを指定せず、利用可能な環境に応じて実行方法とホスティング方法を選びます。

特定の比較をローカルで依頼された場合は、1つの意思決定を比較するに進み、その意思決定に必要な構築と検証だけを行います。全体の画面の棚卸し、レビュー、保持に関するゲートは、この中間成果物ではなくプロトタイプに適用されます。

労力を設定する

effort=standard または effort=high を指定できます。引数が省略された場合は standard を推奨し、使用します。

どちらの労力設定でも、基本完了ゲートを1つ通過します。完成品のように見える画面を作り、依頼されたすべての画面と関連する状態を網羅し、意図された操作とリセット経路を機能させ、ブラウザーですべての関連ビューポートを検証し、検査中に見つかった再現可能な不具合をすべて修正し、ユーザーが開けるアドレスを共有します。このゲートは standard で固定します。

• standard では、基本ゲートを最終成果とします。
• high では、同じ基本ゲートを通過したうえで、レビューして近づけるを通じて、調査可能な現行プロダクトまたはリファレンスに視覚的に近づけます。ホストがサブエージェントに対応している場合は、新規のレビュアーサブエージェント1つに、モデルの労力を高く設定して監査を委任し、ビルダーの調査結果を渡さずにリファレンスと候補成果物を提供します。対応していない場合は、構築と検証のパスを分け、レビュアーの独立性またはモデルの労力を確保できなかったことを報告します。リファレンスを調査できない場合は、視覚的な同等性は未検証であることを報告し、追加のパスはレイアウトの堅牢性を高めるためだけに使用します。

プロトタイプの根拠を固める

依頼と会話の内容をスコープとして使用します。存在する場合は、GLOSSARY.md、docs/decisions/README.md の関連トピック、そして依頼または以前の引き継ぎで特定されている場合に限り、作業単位の仕様を読みます。仕様を検索しないでください。

既存のプロダクトとデザインシステムを根拠として調査します。それらに正式な用語、インターフェースの言語、トークン、コンポーネントがあれば使用し、ない場合はユーザーの言語とテンプレートの完成度の高いミニマルなスタイルを使用します。ユーザーがベースラインと候補のどちらかを選ぶ場合に限り、レビューにベースラインを含めます。矛盾は、暗黙に解決せず表面化させます。

確認済みの関係性は固定します。ユーザーがその関係性を再検討していない限り、オーバーレイ、ドロワー、モーダルは元の画面に紐付けたままにします。

1 つの標準的なプロダクト画面を構築する

画面一覧を修正可能なドラフトとして提示し、承認を待たずに構築を始めます。

templates/shell.html を一時的な単一の自己完結型 HTML ファイルにコピーし、その中にすべてのプロダクト画面を作成します。テンプレートの契約コメントを保持し、それに従ってください。このコメントは、レビュー用の枠組み、プロダクトピクセルの境界、画面と状態の意味、ビューポートの動作を定めています。このファイルには、各プロダクト画面の標準版を 1 つずつ保持します。

ワンクリックで起きる変更や一時的な変更は、見た目がどれほど異なっていても、プロダクトの操作として実装します。セレクタのプリセットは、重要な複数ステップの結果、強制的なデータやエラー、簡単には再現できない構造に限定します。操作によって宣言済みのプリセットに入ったり、そこから離れたりしたときは、セレクタを同期させます。

プロジェクトのトークンをそのまま :root にコピーします。トークンファイルがない場合は、既存のデザイン言語を抽出します。プロジェクトにダークパレットがある場合は、それを .sh-theme-dark の下にコピーして、シェルのテーマ切り替えを表示します。ダークパレットがないプロジェクトでは、独自にダークモードを作成せず、プロトタイプにテーマコントロールを表示しません。すべての画面をこれらのトークンでスタイルし、デザインシステムのコンポーネント名を data-component に指定します。対応するコンポーネントがない場合に限り、new:Name を使用します。

実際の長さの名前、もっともらしい文章、不揃いな数値、そして関連する境界条件だけを使って、現実味のあるダミーコンテンツを作成します。lorem ipsum は使用しないでください。実データ、API、レイテンシ、本番環境のルーティングや状態の配線、フレームワーク、ビルド手順、ネットワークへの依存は含めないでください。

ネイティブアプリのモックアップにはスマートフォンのフレームを使用し、モバイルファーストのプロトタイプはテンプレートの狭いビューポートから始めます。シミュレートされたレスポンシブ動作は、テンプレートのクラスで制御します。

レビューと調整

提示する前に成果物をレンダリングして確認します。ブラウザーで、すべての画面、宣言済みの状態、操作の開始方法とリセット方法、関連するビューポートを試してください。現在のハーネスでサポートされている方法を使って完成した HTML を実行し、ユーザーが開けるアドレスを共有します。相違点、理由、レビュー時のガイダンスは、プロダクトピクセルの外側にある会話で説明します。成果物と修正可能な画面ドラフトを提示し、画面ごとに内容を説明して、変更したい点を尋ねます。レビューが進行中のまま、完了報告で締めくくらないでください。

high の場合は、独立した 2 つの観点から監査します。画面、状態、ビューポートの座標を一致させて、参照とプロトタイプのタイポグラフィ、間隔、配置、折り返し、はみ出し、アセットの扱いを比較します。別の観点から、現実的な長文や扱いにくいコンテンツでレイアウトと操作からの復旧を徹底的に試します。重大な不一致の候補には、それぞれ正確な座標、確認された根拠、再現手順を付けます。利用可能な場合は、新しいレビュアーのサブエージェントに候補の再現を依頼します。再現しない候補は破棄し、再現が確認された項目がなくなるまで修正します。 修正後は、その座標と、変更したトークン、コンポーネント、またはシェルの動作を共有するほかの画面や状態を再レンダリングします。監査した範囲と、未確認の座標や忠実度に関する主張があれば、会話で報告します。

1つの決定を比較する

未解決のビジュアルまたはインタラクションに関する決定が1つある場合は、 templates/comparison-shell.html を一時的な compare.html にコピーします。具体的なユーザーの状況を示し、判断に必要な最小限のコンテキストを添えて、最大3つの選択肢を表示します。断片だけで十分な場合もあれば、関連する複数のビューが必要なフローもあります。この範囲はプロトタイプの画面一覧とは独立しています。比較は、判断が必要になったときに作成してください。製品の画面ごとに一度ずつ作成するのではなく、無関係な製品作業はプロトタイプ内に残します。

テンプレートのスタイルと契約コメントはそのまま維持してください。これらは比較コントロールを管理し、製品内のナビゲーションを各選択肢の中に収めます。判断の対象となる選択肢以外は、コンテンツ、データ、周囲のレイアウト、動作、確定済みの要素を固定します。レビュー担当者は一度に1つの選択肢を確認し、それらを切り替えるため、比較を開いたときに表示される選択肢だけでなく、各選択肢を同じ状態とビューポート座標で検証してください。判断に必要なインタラクション、状態、サイズだけを表示して検証し、実行可能な比較を共有して、選択を尋ねます。

ユーザーが選択したら、その結果を影響を受ける製品 UI とフローに同じ prototype.html 内で適用し、そこで影響を受ける動作を検証します。統合後、一時的な比較を削除してから、プロトタイプのレビューまたは具体化のセッションを再開します。次の決定には新しい比較を作成してください。過去の比較を集めたり、compare.html を最終成果物にしたりしないでください。プロトタイプがまだ作成されていない場合は、選択を記録して比較を破棄し、統合を示すためだけに製品全体を構築することは避けてください。

承認済みの結果を保持する

作業ファイルは一時的なものにし、レビューが終了するまで docs/specs/ には何も書き込まないでください。すべての画面が承認されるか、明示的に保留されたら、エージェントが選んだ変更しやすい既定値は、上書き可能な前提として保持します。承認済みの画面で決まっていない重要な動作については質問するか、明示的に保留し、無関係な画面レビューを再開せず、その影響を残存リスクとして記録します。

実装に関係する重要な製品上の決定がすべて確定または明示的に保留され、エージェントが選んだ変更しやすい既定値にすべて上書き可能な前提としてラベルが付けられたら、特定済みの作業単位フォルダーを再利用するか、ケバブケースのスラッグを付けます。確定した動作と、明示的にラベル付けした前提および保留事項を docs/specs/<slug>/spec.md に記録し、具体化で使用する同じ安定した製品契約を新規作成または更新します。実装前に、ユーザーに見える成果、承認済みの範囲、観測可能な受け入れ基準、確定した制約とその理由、前提、対象外領域とその理由、保留事項、リスク、準備事項を記録または保持します。## Setup before implementation 見出しの下に、実装に必要なリポジトリ外の作業をそれぞれ1行で記載します。たとえば、ベンダーアカウント、発行済みのキー、コンソールまたは DNS の設定などです。各行には、必要なもの、それが実現する成果、そして仕様で提供する作業を実施しなくても確認できる完了条件を記載します。必要なものがない場合は None. と記載し、シークレットの値は決して記載しないでください。予測されるファイル、関数、コード構造、技術レイヤー、実装手順は記載しないでください。承認済みの画面を docs/specs/<slug>/prototype.html として保存し、リンクします。ソースの順序や視覚的な近接性から、ナビゲーション、順序、動作を推測してはなりません。

ユーザーが確認した、再利用可能で、自明ではないトレードオフのみを、仕様書からプロジェクトの意思決定契約に反映します。

中間成果物は破棄してください。承認済みのプロトタイプは参照用であり、本番コードではありません。