preview-screens

プラグインチェック：node "${PLUGIN_ROOT}/scripts/check-version.js" を実行します。メッセージが出力された場合は、続行する前にユーザーに表示してください。

共通の指示：shared-instructions.md — 最初にお読みください。

画面プレビュー

アプリ内のすべての画面を、タブナビゲーションとダーク／ライト切り替え機能付きのスマートフォンフレームのモックアップ（375 × 812）として表示する、自己完結型の HTML ファイルを生成します。エージェントは TSX ファイルを読み、Tamagui コンポーネントツリーを把握したうえで、同等の HTML／CSS を生成します。TSX をプログラムで解析することはありません。

使用する場合

• 画面を生成したあと、Metro／Expo を実行せずに手早く視覚的にプレビューする場合
• ステークホルダーとスクリーンショット用のモックアップを共有する場合
• デプロイ前にレイアウトを確認する場合

使用しない場合

• 実際のアプリを実行する場合 → npm run dev を使用してください
• 画面を変更する場合 → /edit-app を使用してください。screen-builder は、オーケストレーターのスキルから呼び出される内部エージェントです

ワークフロー

1. プロジェクトの場所を特定 → 2. 画面を検出 → 3. 参照マッピングを読み込み → 4. 各画面を読み込んで変換 → 5. preview.html を組み立て → 6. ファイルを書き込み → 7. ブラウザーで開く

---

ステップ 1 — プロジェクトの場所を特定

作業ディレクトリを決定します。

• $ARGUMENTS に --working-dir <path> が含まれている場合は、そのパスを使用します。
• それ以外の場合は、現在の作業ディレクトリを使用します。

プロジェクトを検証します。

Glob pattern="power.config.json" path="<working_dir>"

見つからない場合は、package.json があるか確認します。どちらも存在しない場合は、エラーを報告して終了します。

memory-bank.md がある場合は、ページタイトルに使うプロジェクト名を取得するために読み込みます。

Grep pattern="^# " path="<working_dir>/memory-bank.md"

フォールバックとして、package.json の name を読み込みます。

ステップ 2 — 画面を検出

テレメトリチェックポイント：discover_app_screens

アプリのディレクトリ以下にあるすべての TSX ファイルを検索します。

Glob pattern="app/**/*.tsx" path="<working_dir>"

以下のパターンは画面ではないため、除外します。

• _layout.tsx（ナビゲーションレイアウト）
• +not-found.tsx（Expo Router のエラーバウンダリー）
• . で始まるディレクトリ内のファイル
• アプリのルートにある index.tsx が認証リダイレクトのみを含む場合（内容を読んで確認）
• ほかに表示可能な画面が 1 つ以上ある場合の、変更されていないテンプレート app/(app)/home.tsx。 ソースに Power Apps Standalone と Build your first screen by connecting data sources の両方がまだ含まれている場合に限り、これを認識します。 表示可能な画面がこれだけの場合は、プレビューが空にならないように残します。

ファイルパスから画面名を導き出します。

• app/(app)/home.tsx → 「ホーム」
• app/(app)/recipes/index.tsx → 「レシピ」
• app/(app)/recipes/[id].tsx → 「レシピ詳細」
• app/login.tsx → 「ログイン」
• app/oauth-callback.tsx → スキップ（表示可能な画面ではありません）

作業ディレクトリに native-app-plan.md がある場合は、人にわかりやすいラベルを取得するために、その ## Screens セクションを読み込みます。

順序付きリストを作成します：[ { path, screenName, screenId } ]。

デフォルトのタブ順序 — 最初にホーム、次に詳細画面を 2 つ、その後に残りの画面。 ステップ 5 では最初の項目が active として設定されます。そのため、以下の順序によって preview.html を開いたときに最初に表示される画面が決まります。

次の優先順位でリストを並べ替えます。

1. 最初にホーム／ダッシュボード。 native-app-plan.md でホーム画面またはランディング画面として指定されている画面を優先します。 それ以外の場合は、以下のパスのいずれかに一致する最初の残りの画面を、この優先順位で使用します。 app/(app)/home.tsx、app/(app)/index.tsx、app/(app)/dashboard.tsx、app/index.tsx （実際のホーム画面である場合に限ります。ステップ 2 で除外された認証リダイレクトや変更されていないスタータールートは対象外です）。
2. 次に詳細画面を最大 2 つ。 「詳細」画面とは、ルートセグメントに動的パラメーターを使う TSX ファイルです。ファイルパスに [ と ] が含まれます（例：app/(app)/recipes/[id].tsx、app/(app)/orders/[orderId]/edit.tsx）。検出順で最初の 2 つを選びます（パスのアルファベット順でもかまいません）。
3. その後に残りのすべての画面。 検出順に並べます。

詳細画面が 2 つ未満の場合は、存在する画面のみを含めて、残りの画面に進みます。3 つにするために、詳細画面ではない画面を追加しないでください。

画面を省略してはいけません。このルールで行うのは並べ替えのみです。検出されたすべての画面にタブを割り当てます。

ステップ 3 — マッピングリファレンスを読む

Tamagui から HTML へのマッピングリファレンスを読み込みます：

Read file_path="${PLUGIN_ROOT}/shared/references/tamagui-html-mapping.md"

以下の内容を把握します：

• コンポーネントから HTML 要素および CSS へのマッピング（セクション 1）
• トークンから余白、フォントサイズ、色のピクセル値へのマッピング（セクション 2）
• 変換ガイドライン — プレースホルダーのルール、アイコンの置き換え、スキップする項目（セクション 3）
• Phone frame HTML テンプレート（セクション 4）— 外側のシェルです

プロジェクトにカスタムブランドトークンがあるかどうかも確認します：

Glob pattern="tamagui.config.ts" path="<working_dir>"

見つかった場合は読み込み、カスタムカラートークンを抽出します（tokens: { color: { ... } } を探します）。生成する HTML に追加の CSS カスタムプロパティとして追加します。

ステップ 4 — 各画面を読み込んで変換する

テレメトリチェックポイント：render_screen_preview_frames

開始前に表示：

「→ 個の画面を読み込んで HTML/CSS に変換しています（処理中、画面ごとに 1 回表示します）。」

ステップ 2 の順序付きリストにある各画面について：

1. TSX ファイル全体を読み込みます。

2. コンポーネントツリーを特定します。 JSX の return 文をたどり、すべての Tamagui コンポーネント、その props、および子要素を記録します。

3. ステップ 3 のマッピングを使って、同等の HTML/CSS を生成します：

   • YStack → <div style="display:flex; flex-direction:column; ...">
   • すべての省略形の props を対応する CSS にマッピングします（flex={1} → flex:1、bg="$color2" → background:var(--color2) など）
   • トークン値をピクセル値にマッピングします（p="$4" → padding:16px）
   • <Ionicons name="..." /> アイコンを Unicode の代替表現に置き換えます（マッピングリファレンスのセクション 3、ガイドライン 4 を参照 — アイコン置換テーブルには Ionicons の名前が使われています）

4. 動的コンテンツを処理します：

   • 配列に対する .map() → 代表的なプレースホルダー項目を 3～4 個生成します
   • useQuery / useMutation → データが読み込まれた状態のみを表示します（ローディング／エラー分岐はスキップします）
   • フォームの defaultValues → その値を入力欄に事前入力します

   ネイティブの PDF／ペンのコントロールは、実態に即した静的な近似表現にします：

   • PDF ビューアーのアクション → ファイル名、生成日時、保存先ラベル（例：Stored in Evidence PDF File または On-device share only）、無効化された View PDF ボタンを含む、コンパクトなレポート／PDF ブロックを表示します。ソース URL が明らかに HTTPS でない場合は、偽のビューアーを表示せず、Preview unavailable in browser と表示します。
   • 生成された PDF レポート → 生成済み／準備完了の状態と、プランまたはコードにある永続化ラベル（例：Uploads to Evidence PDF File）を表示します。ブラウザーの PDF iframe を埋め込んだり、ネイティブビューアーがプレビューで動作するかのように示したりしないでください。
   • ペン／署名入力 → インクのストローク例とキャプチャ済みプレビュー状態を含む署名パッドのプレースホルダーを表示します。判明している場合は、Stored in Signature Image や Uploads to Signature File のような永続化ラベルも含めます。
   • ペン入力のキャプチャ、ネイティブ PDF ビューアーの起動、共有、印刷、アップロードを行うふりをするブラウザーのクリックハンドラーは接続しないでください。このプレビューは視覚的な表示のみです。

5. 変換した HTML を <div class="screen" id="screen-{screenId}"> で囲みます。

要素にはインラインスタイルを使用します。テーマ変数を除き、画面間で CSS クラスを共有せず、各画面の HTML を自己完結させます。

ステップ 5 — preview.html を組み立てる

マッピングリファレンス（セクション 4）の Phone frame テンプレートを外側のシェルとして使用します。

プレースホルダーを置き換えます：

• {{APP_NAME}} — ステップ 1 のプロジェクト名
• {{TABS}} — 画面ごとに <button class="tab" ...> を 1 つずつ配置し、最初のタブには active クラスを付けます
• {{SCREENS}} — ステップ 4 のすべての画面 <div> ブロックを配置し、最初の画面には active クラスを付けます

プロジェクトにカスタムブランドトークンがある場合（ステップ 3 で確認）、:root CSS ブロックに追加します。

ステップ 6 — ファイルを書き込む

テレメトリチェックポイント：write_screen_preview_document

Write file_path="<working_dir>/preview.html"

完了を表示します：

✅ Preview generated: <working_dir>/preview.html
   Screens: <N> (<comma-separated list of screen names>)
   Toggle: dark/light mode button in top-right

Step 7 — ブラウザーで開く

テレメトリーチェックポイント：open_screen_preview

プロンプトを表示しないでください。 <working_dir>/memory-bank.md の visual_companion フラグには答えがすでに記録されているため、再度尋ねる必要はありません。このフラグはプロジェクト作成中に /design-system（Step 6.75）が設定するか、/design-system が実行されていない場合は yes がデフォルトになります。

フラグを読み取り、次のように対応してください。

grep -E "^visual_companion:[[:space:]]*(yes|no)" '<working_dir>/memory-bank.md' 2>/dev/null

フラグ	対応
MOBILE_APP_EMBED_PREVIEW=1	リンクを表示して終了します。画面は編集プランに組み込まれています。
visual_companion: no	リンクを表示して終了します。自動で開かないでください。
visual_companion: yes（または memory-bank がない場合、または単独で呼び出された場合）	リンクを表示してから、自動で開きます。

visual_companion: no — 次を表示します。

"プレビューはこちらです：file://<working_dir>/preview.html（Visual Companion はオフです — 手動で開いてください。）"

それ以外の場合 — プロンプトを表示せず、リンクの表示と自動で開く処理を続けて行います。

"プレビューはこちらです：file://<working_dir>/preview.html — ただいま開きます。"

その後、OS に適したオープナーを順に試し、どれも動作しない場合はリンクを表示します。

open '<working_dir>/preview.html' 2>/dev/null \
  || xdg-open '<working_dir>/preview.html' 2>/dev/null \
  || MOBILE_APP_PREVIEW_PATH='<working_dir>/preview.html' \
     powershell.exe -NoProfile -Command 'Start-Process -FilePath $env:MOBILE_APP_PREVIEW_PATH' 2>/dev/null \
  || printf '%s\n' 'Could not auto-open. Open this URL in your browser: file://<working_dir>/preview.html'

open は macOS 専用です。この処理では Linux（xdg-open）と Windows（powershell.exe Start-Process）も順に試します。Windows のパスは PowerShell のソースコードではなく、データとして渡されます。ヘッドレス環境またはサポート対象外のクロスホストセッションでは、ブラウザーが開いたと偽らず、起動に失敗したことと手動で開くためのリンクを伝えてください。

---

メモ

• ソースコードは読み取り専用です。 このスキルが作成または上書きするのは preview.html のみです。TSX ファイル、レイアウト、設定、メモリーバンクは変更しません。
• 静的な近似です。 プレビューでは React の実行、状態の処理、データの取得は行いません。動的なリストにはプレースホルダー項目が表示されます。操作（ボタンのタップ、ナビゲーション）は機能しません。
• ネイティブ機能はプレースホルダーです。 PDF ビューアー、PDF レポート、共有、印刷、ペン／署名のキャプチャーは、静的な状態としてのみ表示されます。ブラウザープレビューでは、ネイティブのキャプチャー／ビューアー API が動作するかのように示してはいけません。
• /preview-screens を再実行すると、以前の preview.html が上書きされます。
• メモリーバンクの更新は不要です — プレビューは一時的な成果物です。

参考資料

• tamagui-html-mapping.md — コンポーネントとトークンのマッピング、およびスマートフォンフレームのテンプレート
• tamagui-component-recipes.md — コピーして使える Tamagui のスニペット（パターンを認識するための参考情報）
• screen-templates.md — 画面のアーキタイプレイアウト