HTMLプロトタイプ構築

HTMLプロトタイプを構築する

すべてのプロトタイプは、このスキルのディレクトリ内の assets/template.html に基づいて構築します。これは自己完結型のHTMLファイルです。テンプレートには、ヘッダー、ブラウザフレーム、状態切り替え、メモパネル、画面マップ、レビューアコメント、k-*コンポーネントとランタイムを含むKoobiqトークンなど、全体のシェルがすでに含まれています。シェルUIは英語またはロシア語で、OS/ブラウザの言語設定に応じて選択されます。プロトタイプ自身のコピーは、あなたが記述する任意の言語で構いません。あなたは、PROTOTYPEブロック（JS）とセクション 5. PROTOTYPE STYLES（CSS）のみを記述します。テンプレートを壊さないでください。シェルを再構築、再スタイリング、説明することは絶対にしないでください。

コードの前に設計を

プロトタイプは、画面のギャラリーではなく、1つの意思決定のためのツールです。prototype.js を記述する前に、以下の手順を実行してください。

1. コンテキストを収集する。 ユーザーは誰か（役割、専門知識）、どんなジョブを実行しているか、そのトリガーは何か、彼らにとって「完了」がどのように見えるか。プロダクトが存在する場合（リポジトリ、スクリーンショット、Figma、ドキュメント、以前のプロトタイプ）、そこからナビゲーション、用語、エンティティ、データを取得し、変更箇所のみを設計します。フィーチャーの周りにプロダクトを発明しないでください。

2. 質問に名前を付ける。 1文（大規模なプロトタイプの場合は複数文可）で、レビューアが何を決定しなければならないか、またはUIで最も疑問な点は何か（ユーザーはXを見つけるか、Yを理解するか、Zは実際のデータで成り立つか）を述べます。各質問について、レビューアがそれに答えるために見る必要があるものと、どの状態やデータがデザインを壊す可能性があるかをメモします。リクエストに質問が指定されていない場合は、最もリスクの高い決定を質問とみなし、ステップ4で作成者に提示します。

3. シナリオを記述する ユーザーの言葉で、トリガーから結果まで：「アナリストがスパイクを確認する → ルールを開く → しきい値を下げる → どれだけのインシデントが発生するかを確認する」。その後、質問に必要なブランチのみを追加します：キャンセル、バリデーションエラー、空/初回使用、および誰も以前に見たことのない要件が表面化する難しいケース：権限なし、別のオブジェクトとの競合、制限、大量のデータ、オブジェクトの現在の状態が禁止するアクション。ステップは STEPS に、ブランチは状態に、横断的条件（役割、機能フラグ、データ量）は SWITCHES になります。

4. 構築前に作成者と合意する。 短いメッセージで、以下を送信します：

   • 質問；
   • 表示予定のブランチと難しいケースを含むシナリオ；
   • リクエストやプロダクトから取得したのではなく、あなたが推測したすべての項目を、1項目1ステートメントの番号付きリストとして（作成者が番号で回答できるように：「2 — いいえ、マネージャーの承認が必要です」）。

   回答を待ってください。既存のプロトタイプへの小さな編集については、このステップをスキップします。作成者が質問しないように依頼した場合、あなたの推測に基づいて構築し、それらを返信にリストします。

5. 各ステップ×状態セルの深さを設定する：

   • 完全 = 質問のパス上：クリック可能、すべての状態、ストレステータ；
   • もっともらしい = コンテキスト：静的だが現実的；
   • 対象外 = 返信でカバーされないと指定されたもの。

   質問に必要な状態のみを使用：理想、空/初回使用、部分、エラー、権限なし、1ステップあたり最大約6状態。特定の何か（長時間の操作、進捗、部分的な結果）を示す場合にのみローディングを追加します。ロード失敗が状態になる価値はほとんどありませんが、「このオブジェクトの状態では許可されていない」は通常価値があります。設計されていない結果を決して偽装しないでください。

6. まず言葉で各画面を設計する： その目的を1フレーズで、主要なアクション1つ、そしてユーザーがここで決定するために見る必要があるものを重要度順に並べます。その後、標準のKoobiqパターン（テーブル、フォーム、サイドパネル、モーダル、空状態）から構築します。新規性は質問がある場所にのみ配置します。それ以外はすべて、プロダクトの通常の画面のように見えます。

   • すべてのアクションには可視の結果があります：何が起こったか、オブジェクトが現在どこにあるか。
   • 破壊的アクションは、オブジェクトと結果に名前を付けます。ボタンは通常、動詞を言います。
   • エラーは修正方法を示し、入力を保持します。
   • 画面、パンくずリスト、トースト、URL全体で、1つのものには1つの名前を使用します。UIコピーはユーザーの言語であり、ux-write がインストールされている場合はそれに従います。

7. ビューの前にデータを記述する。 レイアウトにストレスを与える現実的なドメインデータを使用します：1つの長い名前、0 / 1 / 多数のカウント、まれなステータス。固定の日付と値を使用し（Date.now() / Math.random() は不使用）、lorem ipsumも使用しません。

バリアント、質問が「どのソリューションか」の場合のみ。レビューアのために選択する代わりに、VARIANTS 内に2～3個（最大5個）を構築します。

• 構造（レイアウト、階層、主要アクション）が異なり、色やコピーは異なりません。2つのドラフトが似ている場合は、明示的な禁止（「カードグリッドなし」）を付けて1つをやり直します。
• バリアントはデータを共有しても構いませんが、レイアウトは絶対に共有しません。
• 各バリアントに title と1行のアイデアを text で与えます。
• 最良のフィードバックは「Bのヘッダー、Cのリスト」です。

完了条件

返信する前に、プロトタイプを各項目に対してチェックします：

• 表示されているすべてのパスが最初から最後まで動作する。 ユーザーがトリガーに遭遇する場所から始まり、ログインやダッシュボードからではありません。表示されているすべてのブランチは、パスに戻るか、結果に至って終了します。別の製品やシステムへのハンドオフは、可視の結果（トースト、または「Jiraにタスク作成済み」のような状態）を持つスタブであり、他のUIのコピーではありません。セカンダリコントロールは何もしなくても構いません（メニュー項目は close するだけでもよい）、そこから始まるシナリオがない限り。
• 議論の余地があるものはマークされている。 変更された、または議論の余地があるすべての要素にはノートがあります。質問がどのソリューションを取るかである場合、構造が異なる2～3のバリアントがあります。
• 余分なものはない。 すべての状態、スイッチ、ノートは、質問に答えるか、要件についての推測をテストするのに役立ちます。残りは削除します。

構築

1. 編集可能な部分を取得する。 SKILL_DIR = このスキルのディレクトリ、A=$SKILL_DIR/scripts/assemble.mjs（node で実行、依存関係なし）、作業ディレクトリ例 /tmp/proto-<name>/：

   • 新しいプロトタイプ：node $A --split $SKILL_DIR/assets/template.html /tmp/proto-<name>；
   • 既存の変更：node $A --split <ファイル>.html /tmp/proto-<name>。再アセンブルすると、そのシェルもアップグレードされます。

   これにより、prototype.js（デモPROTOTYPEブロック）と prototype.css（セクション5）が生成されます。

2. prototype.js を書き換える、すべてのデモコンテンツを置き換えます：PROTO、STEPS、SWITCHES、S、NOTES、LINKS（通常は []）、データ、VIEWS、ACTIONS。カスタムCSSは prototype.css に記述します。パスで作業します：

   1. メインパス、理想的な状態で最初から最後までクリック可能；
   2. その他の状態とブランチ；
   3. ノート；
   4. 確認と完了条件。

   画面を通るパスが機能する前に、画面を磨かないでください。

3. アセンブルする： node $A <ターゲット>.html /tmp/proto-<name>/prototype.js /tmp/proto-<name>/prototype.css。構文と必要な宣言をチェックします。HTMLのみを納品します。

4. ビュー： ステップごとに1つの VIEWS[step](S) で、HTML文字列を返し、S.state / S.sw で分岐します。k-* クラスから構築します。references/koobiq-cheatsheet.md を参照してください。

   • すべての状態は、直接開かれたときに完全にレンダリングされる。 直接開く（ポップオーバー、ハッシュリンク、マップサムネイル、ノート、←/→、protoCheck）は、初期の S にその状態の seed を加えたものから始まります。例：{ id: 'confirm', title: '確認', seed: { name: 'ブルートフォース: RDP' } }。フロー内の goto() は、ユーザーが入力したものを保持します。VIEWSは S と定数データのみを読み取ります。
   • オーバーレイ。 モーダルまたはサイドパネルは、それがカバーする画面の上に、同じビュー内で描画されます。1回限りのオーバーレイ（確認）は、そのステップの状態（form/confirm）です。独自のサブフロー（フォーム → エラー → 確認）を持つオーバーレイは、カバーする画面を下に描画する独自のステップにすることができます。パネルの上のモーダルの場合、パネルの後にモーダルをレンダリングします：最後の .k-overlay が最上位であり、そのマーカーのみが表示されます。
   • スクロール。 ブラウザフレームよりも高い画面は、ページのように内部でスクロールします。新しいステップは先頭から始まります。同じステップでの新しい状態またはバリアントはスクロール位置を保持するため、レビューアは同じ場所でそれらを比較できます。アプリシェル（.app-body + .app-content）は、以前と同様に .app-content 内でスクロールします。
   • data-act → ACTIONS でクリックを配線します。goto(step, state) / data-goto を使用してのみ画面を変更し、状態ボタン、URLバー、ハッシュが同期したままになるようにします。

5. ノート（3～7個） は、質問の対象となる要素、つまり変更された、または議論の余地のある要素にのみ配置します。

   • 要素に `class=