screenshotting-apps

注釈付きスクリーンショットのドキュメント

任意のウェブアプリまたは公開ウェブサイトの注釈付きスクリーンショットを含む Markdown ドキュメントを生成します。

前提条件

• agent-browser CLI がグローバルにインストールされていること（npm i -g agent-browser && agent-browser install）

フェーズ 1：対象を決定する

A）公開ウェブサイト

1. URL を正規化します（https:// がない場合は追加します）。

   agent-browser open https://example.com && agent-browser wait --load networkidle
   

2. セマンティックロケーターを使って Cookie／同意バナーを閉じます（最も確実です）。

   agent-browser find text "Accept" click
   

   または、スナップショットで同意ボタンの ref を見つけて、ref を直接クリックします。

   agent-browser snapshot -i -s "[role=dialog], [class*=cookie], [class*=consent]" -c
   agent-browser click @e1  # Use the ref from snapshot
   

   消えたことを確認します：agent-browser is visible "[role=dialog]" または agent-browser wait "[role=dialog]" --state hidden
3. ログイン画面やボット対策で問題が起きた場合は、references/live-sites.md を参照してください。

B）ローカル開発サーバー

1. 開発サーバーを探すか起動します（ポート 3000／5173／4321／8080 を確認するか、package.json を使って起動します）。
2. 自己署名証明書の場合：agent-browser --ignore-https-errors open https://localhost:<port>

フェーズ 2：サイトの構成を把握する

1. ホームページを開きます：agent-browser open <url> && agent-browser wait --load networkidle
2. ページを調査するため、番号付き ref ですべてのインタラクティブ要素にラベルを付ける、自動注釈付きのスクリーンショットを手早く撮影します。

   agent-browser screenshot --annotate docs/screenshots/_survey.png
   

   出力の凡例を読み、ページ上の要素（@e ref に対応付けられたボタン、リンク、入力欄）を確認します。
3. ナビゲーションのスナップショットを撮り、ページを見つけます。

   agent-browser snapshot -i -s "header, nav, [role=navigation]" -c
   

   DOM を詳しく調べるには、agent-browser snapshot -i -c -d 3 を実行します。
4. クライアント側ルーティングを使用する SPA の場合は、ソースコード内のルート定義も確認します（grep -r "path:" src/router など）。ナビゲーションからリンクされていないルートもあります。
5. ページの一覧をユーザーに確認してもらいます。公開サイトの場合は、最大 5～10 ページを提案してください。

フェーズ 3：各ページのスクリーンショットを撮る

ページごとのワークフロー：セレクターを検証 → 注釈を付ける → FAILED の有無を確認 → スクリーンショットを検証 → 修正するか続行する。

セットアップ（すべてのスクリーンショットを撮る前に 1 回だけ実行）：

agent-browser set viewport 1440 900
export AGENT_BROWSER_SCREENSHOT_DIR=docs/screenshots

オーバーレイを表示したり、ページの読み込みを遅くしたりする広告およびトラッキングスクリプトをブロックします（公開サイトの場合）。

agent-browser network route "**/*.doubleclick.net/**" --abort
agent-browser network route "**/googlesyndication.com/**" --abort
agent-browser network route "**/analytics.js" --abort
agent-browser network route "**/gtm.js" --abort

注釈スクリプトのパスを解決します（一般的なインストール先を確認します）。

ANNOT_JS="$(find . .claude .agents ~/skills -path '*/app-screenshots/references/annotate.js' 2>/dev/null | head -1)"
[ -z "$ANNOT_JS" ] && echo "ERROR: annotate.js not found — check skill installation"

ページごとに、以下を実行します。

ステップ 1：移動

agent-browser open <url> && agent-browser wait --load networkidle

公開サイトの場合は、遅延読み込みコンテンツに対応するため agent-browser wait 2000 を追加します。途中の出力が不要な場合は、次のようにチェーンします：agent-browser open <url> && agent-browser wait --load networkidle && agent-browser wait 2000

ステップ 2：Cookie／同意バナーを閉じる（公開サイトの場合）

agent-browser find text "Accept" click
agent-browser wait "[class*=overlay]" --state hidden

複雑なバナーや iframe 内のバナーについては、references/live-sites.md を参照してください。

ステップ 3：注釈を付ける前にセレクターを検証する

必ず最初にセレクターをテストしてください。 セレクターに失敗すると、注釈は表示されません。

複雑な JavaScript には eval --stdin と heredoc を使います（シェルのクォートに関する問題を回避できます）。

agent-browser eval --stdin <<'EVALEOF'
const sels = ['selector1', 'selector2'];
sels.map(s => {
  const el = document.querySelector(s);
  if (!el) return 'MISSING: ' + s;
  const r = el.getBoundingClientRect();
  return 'OK: ' + s + ' (' + Math.round(r.width) + 'x' + Math.round(r.height) + ')';
}).join('\n')
EVALEOF

一致数を簡単に確認するには：agent-browser get count "<selector>"

要素が見つからない場合は、agent-browser snapshot -i -c を使って正しいセレクターと ref を調べます。**壊れたセレクターで注釈を付けないでください。**ヒントについては references/selectors.md を参照してください。

スクロールせずに見えない位置にある要素は、先に画面内へスクロールします：agent-browser scrollintoview "<selector>"

ステップ 4：注釈を追加する

eval --stdin を使って、注釈スクリプトを安全に追加します。

agent-browser eval --stdin <<EVALEOF
$(cat "$ANNOT_JS")
annotateMulti([
  {sel: 'selector', label: 'Label', type: 'box'},
  {sel: 'selector', label: 'Label', type: 'click'}
])
EVALEOF

重要： 出力が FAILED: で始まる場合は、スクリーンショットを撮る前にセレクターを修正してください。注釈を消去して、再試行します。

agent-browser eval "clearAnnotations()"

注釈の種類：

• click — 塗りつぶし円＋矢印＋番号付きラベルです。ボタン、リンク、入力欄に使用します。
• box — 破線の枠線＋番号付きラベルです。セクション、カード、コンテナーに使用します。
• circle（デフォルト）— 半径に上限のある破線の円＋矢印＋番号付きラベルです。一般的なコールアウトに使用します。

色は赤、青、緑、アンバー、紫の順に自動で切り替わります。注釈には相互参照できるよう、自動で番号（1、2、3…）が付けられます。

スクリーンショット 1 枚あたり、注釈は最大 3 つです。 必要に応じて、複数のスクリーンショットに分けてください（例：03a-top.png、03b-actions.png）。

種類の選択ルール：

• 小さな要素（ボタン、リンク、アイコン）には click を使用します。半径が制限されているため、大きくなりすぎません。
• 中くらいの領域（カード、フォームグループ、サイドバー）には box を使用します。要素の形状に沿って表示されます。
• 全幅の要素（ナビゲーションバー、ヘッダー）には circle や box を絶対に使用しないでください。その中の特定の項目に注釈を付けてください。

ページの種類ごとに注釈を付ける対象：

• ホームページ：ヒーロー CTA、検索入力欄、ナビゲーションの例を 1 つ
• 製品一覧：製品カードを 1 つ、フィルター切り替え、並べ替えドロップダウン
• 製品詳細：価格、カートに追加、サイズ／バリエーション選択
• 検索結果：検索入力欄、結果カードを 1 つ、フィルターサイドバー
• ダッシュボード：指標カードを 1 つ、グラフを 1 つ、主要アクション
• テーブル／データビュー：列ヘッダー、フィルターコントロール、データ領域
• 設定／フォーム：主要なフォームフィールド、送信ボタン

ステップ 5：スクリーンショットを撮る

agent-browser screenshot <NN>-<page-name>.png

番号にはゼロ埋めを使用します：01-homepage.png、02-category.png など。コンテンツが画面下部より下に続く場合は、--full を使ってページ全体のスクリーンショットを撮ります。

ステップ 6：スクリーンショットの品質を確認する

撮影したばかりのスクリーンショットファイルを読み込み、次の点を確認してください。

• 注釈が見えていて、互いに重なっていないこと
• ラベルがビューポートの端で切れていないこと
• ページのコンテンツが正しく読み込まれていること（スピナーや壊れた画像がないこと）
• Cookie バナーやオーバーレイが表示を妨げていないこと

問題があれば、agent-browser eval "clearAnnotations()" を実行し、問題を修正して注釈を付け直し、スクリーンショットを再撮影してください。品質に問題のあるスクリーンショットで先に進まないでください。

インタラクティブなスクリーンショット

検索、メニュー、モーダル、ホバー状態には、スナップショット → refs → 操作のパターンを使用します。

# 1. Snapshot to get refs
agent-browser snapshot -i
# 2. Interact using refs (more reliable than CSS selectors)
agent-browser click @e5          # Click search input by ref
agent-browser type @e5 "shoes"
agent-browser wait 2000
# 3. Annotate the result
agent-browser eval --stdin <<EVALEOF
$(cat "$ANNOT_JS")
annotateMulti([{sel: '[class*=suggest]', label: 'Suggestions', type: 'box'}])
EVALEOF
# 4. Screenshot
agent-browser screenshot 05-search-results.png
# 5. Verify — read the screenshot and check quality

注：iframe 内の refs はそのまま機能するため、操作に frame の切り替えは必要ありません。

インタラクティブな操作の記録（任意）

複雑な操作（チェックアウトのフロー、複数ステップのウィザードなど）では、スクリーンショットとあわせて動画を記録します。

agent-browser record start docs/screenshots/checkout-flow.webm
# ... perform the interaction steps, taking screenshots along the way ...
agent-browser record stop

Markdown に動画へのリンクを追加します：チェックアウトのフローを見る

モバイル／レスポンシブのスクリーンショット

モバイルレイアウトを記録するには、次のようにします。

# Use device emulation (sets viewport + user agent together)
agent-browser set device "iPhone 14"

その後、同じ注釈 → スクリーンショット → 確認のワークフローに従います。ファイル名には -mobile の接尾辞を付けます：01-homepage-mobile.png。

デスクトップ表示に戻すには、agent-browser set viewport 1440 900 を実行します。

注：狭いビューポートでは、画面が混み合わないよう、スクリーンショット 1 枚あたりの注釈は最大 2 つにすることをおすすめします。

フェーズ 4：Markdown を生成する

ファイル名：docs/<domain>-screenshots.md（公開サイト）または docs/app-screenshots.md（ローカル）。

説明内の番号付き参照 （1）、（2）、（3） を使って、各スクリーンショットに表示される注釈バッジを相互参照します。

# <Site/App Name> - Visual Guide

Brief description of the site/app.

**URL:** <base-url>
**Date:** <today's date>

**Annotation key:** Red = primary actions, Blue = secondary elements, Green = content areas

---

## <Page Name>

1-3 sentences describing the page. Reference annotations by number:
"The **Search bar** (1) supports autocomplete. Use the **Category nav** (2) to browse departments.
The **Hero banner** (3) rotates seasonal promotions."

![<Page Name>](screenshots/<filename>.png)

---

フェーズ 5：環境を比較する（任意）

ステージング環境と本番環境の差異、または再設計前後の差異を記録する場合：

# Visual pixel diff between two URLs
agent-browser diff url https://staging.example.com https://prod.example.com

# Diff against a baseline screenshot
agent-browser diff screenshot --baseline docs/screenshots/01-homepage-before.png

# Accessibility tree diff (detect structural changes)
agent-browser diff snapshot

何が変わったかを示すため、差分のスクリーンショットを Markdown に含めます。

フェーズ 6：クリーンアップ

# Remove network intercepts
agent-browser network unroute
agent-browser close

リファレンス

• セレクターのヒントとトラブルシューティング：references/selectors.md を参照してください。
• 公開サイトのヒント（Cookie、遅延読み込み、レート制限、地域）：references/live-sites.md を参照してください。