flow-preview

フローのプレビュー

このスキルの scripts/generate.mjs を使って、一時的で自己完結したプレビューを生成します。移動するときは、このスキルフォルダー全体をまとめて保管してください。CLI は Node の組み込み機能だけを使用し、Halo パッケージやワークスペースの設定なしで、任意のプロジェクトのルートから実行できます。キャンバスは開発ツールであり、本番アプリケーションの状態ではありません。

実際の UI をもとにストーリーを組み立てる

• 本番コンポーネントとその利用箇所、状態遷移を読み取ります。リクエストに関係するユーザーの開始点、アクション、成功、読み込み、検証、失敗、再試行、権限分岐を整理します。グリッドを埋めるために画面を捏造しないでください。
• 実際の本番コンポーネントを、props とローカルのフィクスチャコールバックを通じて適用します。サーバー呼び出しとレンダリングが一体化している場合は、小規模なプレゼンテーション用コンポーネントへの切り出しを提案します。見た目だけ似せた UI を別途保守しないでください。
• フィクスチャとシミュレートしたリクエストは一時的なプレビュー内に置き、本番コードに条件分岐を追加しないでください。サムネイルはすべての状態を同時にマウントします。サムネイルのレンダリングによってリクエストが送信されたり、実際の処理が開始されたり、本番データが変更されたりしないようにしてください。タイムスタンプやランダムなコンテンツではなく、決定論的な値を使用します。
• 利用可能な場合は Maui スキルを使って UI を構成します。フロー固有の文言やビジネスデータはシナリオ／アダプターに置き、汎用キャンバスには置かないでください。
• 追加の画面ラベル、ヘッダー、説明パネル、シミュレーションに関する免責フッターを加えずに、本番 UI をレンダリングします。コンテキストはノードの note に記載します。現在の状態に必要なローカルのシミュレーションボタンのみを、 “Simulate grant access” のような明確なアクションラベル付きで表示します。「Preview controls」ヘッダーは追加しないでください。
• マップのサムネイルは、通常時に枠を付けないでください。ホバー時は、タイトル、レビュー用チェックボックス、サムネイルを含むノード全体を、要素間の余白も含めて背景で囲みます。本番コンポーネント独自のサーフェスは維持します。ギャラリー風の点線パネルを使うのは、選択中のインタラクティブプレビューのみとし、その中で UI を中央に配置します。状態タイトルに番号の接頭辞を付けないでください。グラフとアウトラインがすでに順序を示しています。

生成して配信する

対象プロジェクトのルートから、インストール済みスキルの場所にあるスクリプトを実行します。通常、Skills CLI は .agents/skills/flow-preview にインストールします。エージェントのディレクトリが異なる場合は、パスを調整してください。

node .agents/skills/flow-preview/scripts/generate.mjs preferences-flow 4180
npm --prefix tmp/preferences-flow install --workspaces=false

引数は <lowercase-name> [port] です。ポートのデフォルトは 4180 です。名前にパスを含めることはできません。既存のプレビューは上書きされません。スクリプトは、スキルの場所ではなく、カレントディレクトリを基準に tmp/<name>/ を作成します。キャンバスと Vite ヘルパーに加え、scenario.tsx、main.tsx、index.html、vite.config.mjs、非公開の package.json をコピーします。生成されたプレビューは、このスキルや Halo からインポートしないため、スキルを移動しても壊れません。

tmp/<name>/scenario.tsx を編集します。依存関係はそのプレビュー内にのみインストールし、プロジェクトのワークスペースには追加しないでください。実際のアプリケーションコンポーネントをインポートする場合は、React と Maui のバージョンをそのプロジェクトに合わせ、Vite ヘルパーの重複排除設定を維持します。vite.config.mjs では、必要なソースディレクトリのみを sourceRoots として previewConfig に渡します（パスはプレビューディレクトリからの相対パスです。例：sourceRoots: ["../../packages/web/src"]）。デフォルトの許可リストで対象となるのはプレビューディレクトリのみです。プロジェクトのルートやランタイムのワークスペースは、決して許可しないでください。認証情報ファイル、.git、.halo、.amp は、許可されたソースディレクトリ内であっても引き続きアクセスが拒否されます。ポータルを共有する前に、HTTP 経由でこれらの境界を検証してください。

Amp オーブ内では、スクリプトが出力する、監視付きの正確なコマンドに従ってください。

amp orb service start flow-preferences-flow --command 'npm --prefix tmp/preferences-flow run dev' --port 4180 --portal

返されたポータル URL を共有してください。localhost やオーブの直接ホスト URL は共有しないでください。オーブの外では、npm --prefix tmp/preferences-flow run dev を使用します。プレビューディレクトリを削除する前に、サービスを停止してください。オーブ内では、nohup やシェルのバックグラウンドプロセスでプレビューサーバーを起動しないでください。

状態を記述する

FlowScenario と FlowNode は、生成された ./FlowCanvas.tsx からエクスポートされます。

• シナリオ：安定した id、title、initialState、nodes を指定します。description、navigationLabel、dimensions は任意です。
• 各ノード：一意で安定した id、title、（入力されたユーザーアクションを表す）action、任意の parent、0 以上の row、および render({ mode }) を指定します。親を子より先に配置し、ルートには parent を指定しません。初期状態は存在している必要があります。ジャーニーで状態を再訪する場合は、循環を作成するのではなく、別の出現 ID を使用します。
• 列は親の深さに従い、空きスロットを作らずに縦方向に詰めて配置します。row は各列内の状態の順序を指定するもので、全体にわたるレーンを確保するものではありません。矢印は、垂直位置が異なっていても、実際の親と子を接続します。
• render は実際のコンポーネントアダプターを返します。mode は thumbnail または preview です。それぞれ異なる DOM ID を使用してください。表示されるコンテンツは同等に保ちます。任意の note はインタラクティブなプレビューにのみ表示し、サムネイルのタイトルの下には表示しません。
• dimensions：previewWidth は、拡大縮小前のコンポーネントのデフォルト幅です。nodeWidth はサムネイルの幅、nodeHeight はサムネイルの最大高さです。各ノードでは、拡大縮小前のピクセル単位で maxWidth と maxHeight を設定できます。本番コンポーネントに既存の幅の上限がある場合はそれを使用し、未使用の余白の中でコンテンツが縮小するのではなく、サムネイル内を埋めるようにします。インタラクティブ UI は、使用可能な幅の範囲でその上限まで広がり、コンテンツに合わせて高さが伸びます。また、高さの上限（デフォルトでは拡大縮小前のサムネイルの高さ）と使用可能なペインの高さのうち、小さい方に合わせてスクロールします。タイトルとナビゲーションは、そのスクロール領域の外に配置してください。高さの低いプレビューは、ヒットターゲットと矢印アンカーを含め、レンダリングされた高さに合わせて縮みます。タイトル行には固定高さの見出し領域を使わず、自然な高さを適用します。columnGap／rowGap は分岐間の間隔を指定します。関連するコンテンツが見えるように、最大高さを十分に大きく設定してください。

キャンバスには、階層的なアウトライン、各サムネイルの上にあるタイトルとチェックボックス、スクロールによるパン、ズーム、アニメーション付きの選択／クロスフェード、リセット、アニメーション付きのサイドバー切り替えが用意されています。プレビューの UI 要素は、状態タイトル、レビュー用チェックボックス、リセット、ナビゲーション操作に限定してください。「インタラクティブプレビュー」や「このフローをたどる」という見出しを繰り返し表示しないでください。両方のサイドバーには、Maui の浮き上がった要素用サーフェスを使用します。サムネイルには、通常時にカード用のサーフェスや枠線を付けません。ノード全体に単一のネイティブ CSS :hover を適用して、Maui のホバー背景を即座に表示します。トランジション、ジオメトリの変更、タイトル色の変更は行いません。ヘッダー、チェックボックス、サムネイル、およびそれらの間隔は、この連続したホバー領域の内側に配置します。選択ボタンは、React Aria の遅延した data-hovered だけでなく、ネイティブの :hover 時にも透明に保ち、最初のフレームで UI を覆う塗りつぶしが一瞬表示されないようにします。選択中はタイトルをアクセントカラーにし、セミボールドにします。タイトルまたはサムネイルをクリックすると状態を選択します。チェックボックスではレビュー状態のみを変更します。ホバーでは状態を選択したりリセットしたりしません。画面遷移元のシーンとサムネイルの内容は操作できません。操作を試すにはインタラクティブプレビューを使用してください。動きを減らす設定では、クロスフェードを維持したまま移動をなくします。 選択した UI を、Maui gallery の Panel レシピに合わせたパネル内に配置してください。背景は gray-1、ドットは gray-alpha-3 を 12px 間隔で配置し、アウトラインの境界線と特大の角丸を使用します。マップキャンバスにも同じドット背景のレシピを使用してください。四辺すべてに均等でコンパクトな内側余白を設け、パネルの最小高さは設定しないでください。左右に広い余白を残さず、パネル自体の幅は UI の幅に内側余白と境界線を加えた幅を上限にします。スクロールを受け持つのは余白のあるパネルであり、UI の周囲にぴったり合わせたラッパーではありません。実運用コンポーネントのシャドウが角のマークでクリップされないようにしてください。背の高いコンテンツの範囲を制限しつつ、サムネイルにはシャドウ用の小さなクリップ余白を設けてください。実運用 UI が持つ余白は維持してください。これはギャラリーのスタイリングであり、Panel パッケージのインポートではありません。Previous state と前進アクションはそのパネルの外に置き、標準のボタンスタイルのまま右揃えにしてください。免責事項のフッターは追加しないでください。サイドバーの両境界はドラッグとキーボードによるサイズ変更に対応させ、幅はシナリオごとにブラウザーの localStorage に保存してください。アウトラインの選択背景はレビュー用チェックボックスを含む行全体を囲みます。このチェックボックスをクリックしても、変更されるのはレビュー状態だけです。サイドバーの幅はマップ用のスペースを残すように制限し、狭い画面で縦に積み重ねるレイアウトでは、保存済みのデスクトップ幅を置き換えずにサイズ変更ハンドルを非表示にしてください。

レビューと検証

アウトライン、キャンバス、インタラクティブプレビューのレビュー用チェックボックスは、状態ごとに 1 つの値を共有します。チェックすると、そのサムネイルだけを暗くし、チェックマーク付きの緑色の円を重ねて表示します。マーク全体が見える状態を保ち、状態の選択を妨げないようにしてください。ブラウザーの localStorage には、シナリオと状態ごとにフィンガープリントを保存します。リセット、テーマ変更、再読み込みを行っても維持してください。描画内容またはスタイルクラスが変更された場合は、影響を受けた状態のみフィンガープリントを無効にします。フィンガープリントの対象から、生成された ID、テーマ値、一時的なアニメーションの transform／opacity を除外してください。フィンガープリントは編集済みのインタラクティブな下書きではなく、決定的なサムネイルを表すものです。シナリオ ID と状態 ID は安定して維持してください。新しい ID は新しいレビューとして扱われます。レビューはそのブラウザーとオリジン内に限られ、レビュアー間で共有されるストレージではありません。

新しいシナリオでは、ポータル内で関連するすべての状態と実際の操作を実行してください。ブラウザーを操作する前に、利用可能であれば using-agent-browser スキルを使用してください。ライトモード、ダークモード、狭い画面のレイアウト、キーボードナビゲーション、リセット、レビューの同期と永続化、視差効果の低減を確認してください。DOM のアサーションだけでなく、スクリーンショットも確認してください。Amp の orb では、レビュー可能な最終スクリーンショットや録画を .amp/in/artifacts/ に保存してください。それ以外の場合は、プロジェクトのアーティファクトディレクトリを使用してください。作業用のキャプチャはプレビューの tmp/ フォルダーに保存してください。フィクスチャのプレビューを、実際のバックエンド操作が成功する証拠として扱わないでください。

スキルの保守

同梱されている assets/FlowCanvas.tsx と assets/previewConfig.mjs は、CLI がコピーするソースです。これらのファイルまたはジェネレーターを編集した後、このスキルのディレクトリから次を実行してください。

npm install --workspaces=false
npm run typecheck
npm run lint
npm run format:check
npm run test:e2e

ブラウザーテストでは、このスキルを別のコンシューマープロジェクトにコピーし、通知設定フローを生成してから、そのスキルのコピーを削除し、生成されたプレビューをテストします。必要に応じて npx playwright install chromium で Playwright Chromium をインストールするか、インストール済みのブラウザーを PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH に指定してください。このスキルは、リポジトリの lint や TypeScript 設定に依存しません。スキルを変更しても、既存の生成済みプレビューが自動的に更新されることはありません。新しいプレビューを作成するか、シナリオ ID とフィクスチャを維持したうえで、コピーされたキャンバスやヘルパーを意図的に更新してください。