ux-extract

UX Extract

参考Webアプリを徹底的に調査し、再利用可能なパターンライブラリを作成します。あらゆる場所を巡り、すべてを記録して、別の監査や構築で参照できるドキュメントに整理します。

ux-audit の逆です。

• 監査で問うこと：基準を満たしているか？
• 抽出で問うこと：基準とは何か？

抽出せずに監査すると、「他のアプリについての自分の記憶」を暗黙の比較対象にしてしまい、脆弱で一貫性に欠けます。抽出によって、その記憶を具体的で参照しやすい成果物にできます。そうすれば監査では、*「/app/clients の空状態には CTA がありません。参考例（claude.ai）では、同じ位置に 3 つのキーボードショートカットと『新しいチャット』が表示されています」*と記述でき、「少し寂しい印象です」のような曖昧な指摘を避けられます。

使用するタイミング

• 新機能を構築する前 — 優れたアプリがその機能をどのように実現しているか調査します
• 構築したものを評価するとき — 参考例を抽出してから、それを基準に監査します
• デザイナーやエンジニアのオンボーディング — 優れたデザインの具体例を示します
• 競合調査 — 競合の UX を記録し、有意義な差別化につなげます
• 古いアプリを刷新するとき — 現代の類似アプリからパターンを抽出し、更新の指針にします

対象範囲と倫理

始める前に、対象が調査して問題のないものか確認してください。

1. 自分のアカウントを使う — 正当に保有していない認証情報を必要とするものはスクレイピングしないでください
2. 認証なしでクロールする場合は robots.txt を尊重する
3. アクセス頻度を制限する — クローラーではなく、人間のユーザーのように行動してください。ページ間で休止を入れます
4. 利用規約を確認する — ほとんどの SaaS の利用規約では個人による閲覧は認められていますが、自動スクレイピングは禁止されています
5. ライブの競合アプリのスクリーンショットを公に 再配布しない — パターンライブラリは社内参照用です

対象が有料の壁の向こうにある場合や、トライアルアカウントが必要な場合は、作業を進める前に、正規のアクセス権があるかユーザーに確認してください。

セットアップ

1. ブラウザツール

対象	ツール	備考
認証が必要な参考例（アカウントを保有している場合）	Chrome MCP	ログイン済みのセッションを使用します
公開されている参考例（マーケティングページ、ドキュメント、公開デモ）	Playwright MCP	ログインは不要です

コマンドについては、../ux-audit/references/browser-tools.md を参照してください。

2. ビューポート

基準として 1440×900（MacBook の標準）を固定します。レスポンシブパターンについては 768 と 375 もキャプチャします。幅は 2000px を超えないようにしてください。

2b. スクリーンショットの後処理

Retina 対応の Mac では、Chrome は論理ビューポートの 2 倍のサイズでキャプチャします。幅 1440 のウィンドウでは、幅 2880 の PNG が生成されます。ライブラリに大きすぎるファイルが増えないよう、各バッチの後に後処理を行ってください。

img-process batch ./screenshots --action optimise --max-width 1440

冪等性があるため、すでに小さいファイルには何も行いません。各ルートのキャプチャ後、または抽出の最後に screenshots/ フォルダー全体を対象に実行します。Playwright MCP ユーザーはコンテキストオプションで deviceScaleFactor: 1 を設定すれば、この手順を省略できます。

3. 対象範囲

開始前に決めてください。

• アプリ全体 — 到達できる場所をすべて巡ります（数時間かかることもありますが、包括的なライブラリを作成できます）
• 機能領域 — 1 つのセクション（「設定フロー」「ダッシュボード」「請求フロー」など）
• パターンの種類 — 空状態のみ、エラー処理のみ、オンボーディングのみなど

範囲を絞るほど、ライブラリのまとまりが良くなり、役立つものになります。「アプリ全体」が適しているのは、直接の類似アプリを構築する予定がある場合に限ります。

4. 注目する観点（任意）

キャプチャの観点を任意で指定できます。例：

• 「データ量の多いリストのパターンに注目」 — テーブル、フィルター、検索、仮想化のスクリーンショットを優先します
• 「オンボーディングと空状態に注目」 — 初回利用時のフローとデータがない画面を優先します
• 「権限の境界に注目」 — 複数のロールでログインし、違いを記録します

観点の指定がない場合は、幅広くキャプチャしてください。

発見

サイトマップのクロール

すべてのルートを洗い出します。

1. 公開サイトマップ — /sitemap.xml と /robots.txt を確認し、発見可能性を調べます
2. ナビゲーションのクロール — トップナビゲーション、サイドバー、フッターに表示されている各セクションをすべてクリックします
3. アプリ内での探索 — アプリ内に入ったら、表示されるリンクをすべて記録します（パンくずリスト、タブ、コンテキストメニューなど）
4. URL の調査 — アプリによっては、メインナビゲーションにはない /settings、/preferences、/admin に役立つパターンがあります

各ルートの目的を記録します：/settings/billing — サブスクリプションプラン、支払い方法、請求書の履歴。

パターンの一覧

詳細なキャプチャを始める前に、アプリを一度確認し、記録するパターンの種類を列挙します。一般的なカテゴリは次のとおりです。

• 目的地への誘導（ナビゲーション、パンくずリスト、現在地、戻る）
• リストとテーブル（行、ホバー、アクションの表示、選択、並べ替え、フィルター、ページネーション、空の状態）
• フォーム（ラベル、入力検証、エラー、必須項目、インラインヘルプ）
• モーダルとダイアログ（起動、フォーカス、エスケープ、スクロール、確認）
• フィードバック（トースト、インライン、進行状況、読み込み中、保存済み）
• オンボーディングと空の状態（初回起動、データがない場合の CTA、ガイド付きツアー）
• 権限とロール（制限されたビュー、アクセス拒否、ロールの表示）
• コピーとマイクロコピー（ボタン、見出し、エラー、プレースホルダー、ツールチップ）
• キーボード（ショートカット一覧、フォーカス、タブ順序、コマンドパレット）
• モーション（遷移、表示、読み込み、ジェスチャー）
• レスポンシブ対応（ブレークポイント、モバイル固有の要素：ボトムシート、タブ、スワイプ）

すべてのアプリがすべてのカテゴリを使うわけではありません。該当するカテゴリを記録します。

キャプチャフェーズ

各ルートを漏れなくキャプチャします。スクリーンショットは手軽に撮れるため、必要以上に撮る方を選びます。

すべての状態をスクリーンショットに収める

意味のある要素ごとに、次の状態をキャプチャします。

状態	トリガー
デフォルト	ページ読み込み後、何も操作していない状態
ホバー	ボタン、行、ナビゲーション項目にマウスを合わせた状態
フォーカス	Tab キーでキーボードフォーカスを移動した状態
アクティブ	ボタンをクリックしている途中、入力中の状態
開いた状態	ドロップダウンを開いた状態、メニューを展開した状態
閉じた状態	ドロップダウンを閉じた状態、メニューを折りたたんだ状態
展開	アコーディオンを開いた状態、詳細パネルを展開した状態
折りたたみ	アコーディオンを閉じた状態
選択済み	チェックボックスにチェックした状態、行を選択した状態、タブをアクティブにした状態
読み込み中	スケルトン、スピナー、保留中の状態
空	項目がないリスト
データあり	項目が多く表示されたリスト
エラー	インライン、トースト、または全ページのエラー
成功	操作後の確認

パターンごとの詳しいチェックリストについては、references/capture-checklist.md を参照してください。

コピーを一字一句そのまま記録する

句読点、省略記号、トーンを含め、テキストを正確にコピーします。

• ボタンラベル："チャットを開始"、"プランをアップグレード"、"完全に削除"
• 空の状態："まだ会話はありません。ここに表示するには、新しく始めてください。"
• エラーメッセージ："変更を保存できませんでした。もう一度お試しください。問題が続く場合は、サポートにお問い合わせください。"
• 確認ダイアログ："このプロジェクトを削除しますか？14 件のタスクと 3 人のメンバーがすべて削除されます。この操作は取り消せません。"
• プレースホルダーテキスト："例：[email protected]"
• ツールチップ："Cmd+K を押すと、どこからでもこれを開けます"

生のコピーはライターにとって貴重な資料であり、アプリのトーンを把握する手がかりになります。

インタラクションを記録する

インタラクティブな要素ごとに、次の項目を記録します。

• トリガー：クリック／ホバー／キーボード／長押し／ドラッグ
• 対象：影響を受けるもの（モーダルを開く、リストをフィルターする、画面遷移するなど）
• フィードバック：即座に視覚的な反応があるか？遅れて確認が表示されるか？
• 取り消し可能性：元に戻せるか？破壊的な操作か？

キーボードのパターンを記録する

• ショートカット一覧：? または Cmd+/ でショートカット一覧が表示されますか？表示される場合はキャプチャします。
• コマンドパレット：Cmd+K などがありますか？パレットを開いた状態、検索中、結果を選択した状態、アクションを実行した状態をキャプチャします。
• フォーカスインジケーター：ページ内を Tab キーで移動し、リングのスタイル、色、太さを記録します。
• タブ順序：論理的ですか？予想外のジャンプはありませんか？

レスポンシブ対応のキャプチャ

各ルートについて、1440、768、375 でスクリーンショットを撮影します。「動作する」だけでなく、何が変わるかを記録してください:

• ナビゲーションがサイドバーからハンバーガーメニューに変わる [ブレークポイント]
• テーブルが積み重ねカードに折りたたまれる [ブレークポイント]
• モーダルが全画面になる [ブレークポイント]
• 複数列フォームが単一列になる [ブレークポイント]

モーションのキャプチャ

記録する価値のあるアニメーションは GIF（Chrome MCP の gif_creator）で録画します:

• ページ遷移
• モーダルの表示/非表示
• リスト項目の表示/非表示
• ローディング → ロード完了
• 成功アニメーション（紙吹雪、チェックマーク）
• ドラッグ＆ドロップのフィードバック

3 秒の GIF 1 つは、段落 1 つ分の説明に値します。

重複排除フェーズ

キャプチャ後、多くのパターンが複数のページに現れます。重複を排除します:

• 5 つのリストページに同じ行パターン → 1 つの「リスト行」エントリとし、*「使用箇所: /clients、/projects、/invoices、/reports、/team」*という注記を付ける
• 同じ空状態レイアウトでコピーだけが異なる → 1 つの「空状態」エントリとし、コピーのバリエーションを列挙する
• 同じモーダルの外枠 → 1 つの「モーダル」エントリとし、個別のモーダルを使用箇所として列挙する

パターンごとに 2 つのカウントを維持します:

• 出現回数 — このパターンが現れる回数
• バリエーション — 意味のある差異（アイコンあり vs なし、小 vs 大、CTA あり vs なし）

1 回しか現れないパターンは、独自性があり注目に値する場合を除き、記録する価値はほとんどありません。

出力

docs/ux-extracts/<app-name>/（または、そのディレクトリが存在する場合は .jez/artifacts/ux-extracts/<app-name>/）に書き込みます:

docs/ux-extracts/claude-ai/
├── pattern-library.md      ← main document
├── copy-corpus.md          ← optional, raw copy by page (for writers)
└── screenshots/
    ├── 001-home-default.png
    ├── 002-home-hover-cta.png
    ├── 003-new-chat-empty.png
    └── ...

出力構造については、references/pattern-library-template.md を参照してください。

パターンライブラリは次のようであるべきです:

• ナビゲート可能 — 先頭に目次があり、すべてのセクションへのジャンプリンクがある
• 相互参照されている — 「関連項目: モーダルの外枠」
• スクリーンショットが豊富 — すべての主張が参照されたスクリーンショットによって裏付けられている
• コピーが正確 — 言い換えではなく、コードブロックまたは引用ブロック内に逐語的なテキスト
• 正直 — 良い点だけでなく、欠けている点や弱い点も記録する。リファレンスライブラリは絶対的な聖典ではありません。

ux-audit がこれをどう利用するか

ux-audit は .jez/artifacts/ux-extracts/<ref>/pattern-library.md または docs/ux-extracts/<ref>/pattern-library.md にパターンライブラリがあるか確認します。見つかった場合、比較の基準として使用します。監査結果は次のように特定のパターンを引用できます:

「/app/clients の空状態には説明文も CTA もありません。リファレンスライブラリ [claude.ai § 空状態] では、同じ位置に CTA と 2 つのサンプルプロンプトが表示されています。」

期待されるパスにライブラリを生成する以外に、統合は必要ありません。

自律性

• そのまま実行する: ナビゲート、スクリーンショット、テキストのコピー、計算済みスタイルを読み取るための JavaScript の注入、参照用の静的アセット（ロゴ、アイコン）のダウンロード
• 先に確認する: ユーザーが使用を許可していない認証情報を必要とするログイン、利用規約やレート制限が曖昧なサイトのスクレイピング
• 停止して確認する: 対象にログインの壁があり、明確な許可がない場合は、続行する前に停止して確認する

参照ファイル

いつ	読むもの
pattern-library.md の出力を構築するとき	references/pattern-library-template.md
パターンごとのキャプチャチェックリスト（何をスクリーンショットし、何を記録するか）	references/capture-checklist.md
ブラウザツールのコマンド	../ux-audit/references/browser-tools.md

ヒント

• スクリーンショットの撮影には手間がかかりません — 多めに撮影してください。抽出をやり直して撮影するより、ライブラリからスクリーンショットを削除するほうが簡単です。
• コピーは見つけた瞬間に記録してください — あとで戻るつもりでいるのはやめましょう。戻ってきたときには、別の状態になっています。
• 存在しないものも記録してください — アプリにキーボードショートカット一覧がない場合、それも記録する価値のあるパターン上の判断です。
• 観察と評価を分けてください — 抽出では、何があるかを記録し、それが良いかどうかは評価しません。意見は抽出ではなく監査に記載します。
• 抽出内容は古くなります — アプリは変化します。ライブラリにタイムスタンプを付け、可能であれば archive.org の該当日付へのリンクを追加してください。頻繁に比較するアプリについては、6～12 か月ごとに再抽出する計画を立てましょう。
• 少しずつ作成してください — 最初にライブラリファイルを開き、作業しながら追記してください。最後にすべてをまとめて構成しようとしないでください。