website-to-design-md

Web サイトから DESIGN.md を作成

概要

このスキルを使うと、実際の Web サイトを、再利用可能な design.md または DESIGN.md ドキュメントと、それに対応する HTML プレビューに変換できます。

目標は、サイトを複製することではありません。別のエージェントが元の Web サイトを見なくても、同じデザイン言語、コンテンツのトーン、操作感を再現できるよう、サイトを十分に詳しく調査することです。

HTML プレビューは、実用的なレビュー用の画面です。Markdown をひと目で確認できるデザインボードに変換し、元のサイトを再度開かなくても、ユーザーが配色、タイポグラフィ、余白、コンポーネントの手がかり、未加工の Markdown ソースを確認できるようにします。

共通のブラウザルール

このスキルでは、常に最初に agent-browser を使用してください。

• 抽出ワークフローの中心として、agent-browser open、agent-browser wait、特に agent-browser eval を使用してください。
• ユーザーが使っているアプリやプラットフォームの確認から始めないでください。
• ユーザーが Codex、Trae、Claude、Cursor、その他のホストを使っているかどうかで、処理を分岐しないでください。
• 現在のプロジェクトフォルダーに Playwright、Chrome CLI、ローカルのブラウザパッケージがあるかどうかの確認から始めないでください。
• agent-browser が利用できない場合は、インストールするか PATH に追加するようユーザーを支援してから、同じワークフローを続けてください。
• ユーザーから別のフォールバックを明示的に求められない限り、Playwright、Chrome CLI、またはスクリーンショット主導の抽出に、黙って切り替えないでください。

作業スタイル

ブラウザを優先し、証拠に基づいて作業してください。

• 生の HTML の取得よりも agent-browser を優先してください。実際の Web サイトでは、ハイドレーション、スクロール状態、ホバー状態、レスポンシブレイアウトの変化の背後に、重要な挙動が隠れていることがよくあります。
• agent-browser eval を主要な抽出レイヤーとして扱ってください。主な根拠は、ブラウザーのランタイム内で取得した DOM 構造、レンダリング済み HTML、計算済みスタイル、CSS 変数、読み取れるスタイルシートのルール、操作状態に基づくものとします。
• スクリーンショットを標準の根拠として使用しないでください。agent-browser eval または同等のページ評価手段が利用できる場合は、DOM、計算済みスタイル、CSS 変数、読み取れるスタイルシートのルール、抽出したテキストを主要な根拠として使用してください。
• スクリーンショットは、DOM の根拠が不十分な場合、またはユーザーから視覚的な検証を明示的に求められた場合に限り、最後の手段として任意の照合に使用してください。
• Playwright や Chrome CLI に黙ってフォールバックしないでください。agent-browser が利用できない場合は、そのことを明示的に検出し、インストールするか利用可能にするようユーザーを支援してください。
• 静的ソースファイルは補足的な根拠として扱い、主な情報源にはしないでください。
• 技術的な詳細はデザイン言語に置き換えてください。CSS をそのまま大量に出力せず、エージェントが実際に活用できる形にまとめてください。
• 実際に観測した事実と推論を区別してください。判断や、直接観測した値ではなくルールの可能性を示す場合は、その旨を明確に記してください。
• ユーザーから明示的に不要と指定されない限り、HTML プレビューも標準の成果物に含めてください。

事前確認

1. 対象を 1 つ以上の URL に正規化します。
2. agent-browser がすでに使用可能か確認します。
3. agent-browser が見つからない場合は、scripts/check-browser-tooling.mjs を使用してから、インストールするか利用可能にするようユーザーを支援します。
4. 現在のフォルダーで Playwright、Chrome CLI、ローカルのブラウザー実行ファイルを主要な方法として調べないでください。
5. ユーザーから明示的にフォールバックを求められない限り、Playwright や Chrome CLI に黙ってフォールバックしないでください。
6. Markdown の出力ファイルは、既定で DESIGN.md にします。
7. 対応するプレビューのファイル名は、既定で同じベース名に -preview.html を付けたものにします。たとえば、DESIGN-preview.html または design-preview.html です。
8. ユーザーが design.md、カスタムファイル名、またはカスタムフォルダーを明示的に指定した場合は、その指定を厳密に守り、別途求められない限り HTML プレビューも同じ場所に置きます。
9. 複数の URL が指定されている場合は、それぞれを個別に調査し、各ページのビジュアル言語に明確な一貫性がある場合に限り、共通のデザインシステムにまとめます。

ブラウザツールのセットアップ

ブラウザツールのセットアップは、ユーザーが別途行う作業ではなく、スキルの一部として扱ってください。

検出

次の順序で確認します。

• agent-browser をすでに呼び出せるか
• 呼び出せない場合、すぐにインストールするか、利用可能な状態にできるか

同梱のチェッカースクリプトでは、次の内容を確認できます。

• node と npm を利用できるか
• agent-browser を呼び出せるか
• 次に使用すべきツール
• インストールが推奨されるか

インストールのデフォルト動作

agent-browser を利用できない場合は、ユーザーがインストールするか、PATH に追加できるよう支援し、スキルを使う前に agent-browser --help で動作を確認してください。

インストール時の動作

• スキルで agent-browser を安定して使えるようにするため、インストールが必要であることを説明してください。
• ネットワークまたはサンドボックスの制限により最初のインストールが失敗した場合は、必要な許可を求めてから再試行してください。
• インストールに成功した場合は、同じターン内にそのままサイト分析を続けてください。
• インストールに失敗した場合は、不足しているものをユーザーにはっきり伝え、別の抽出方法に黙って切り替えずに中止してください。
• ツールがないという理由だけで、静的 HTML のスクレイピングに黙って切り替えないでください。

必須の抽出手順

詳しく確認する必要がある場合は、references/website-reading-checklist.md のチェックリストを使用してください。

1. ページの範囲を把握する

• ページの目的を特定します。
• ページがマーケティング、製品、ダッシュボード、ドキュメント、EC、編集記事、またはその混合のいずれに当たるかを特定します。
• 上から順に、重要な表示セクションを特定します。
• アクセス制限のある領域やアクセスできない領域は、内容を捏造せずに記録します。

2. 基準状態を取得する

• まずデスクトップ表示でページを調べます。
• レイアウトが大きく変わる場合は、タブレット表示とモバイル表示も調べます。
• 遅延アニメーション、固定表示 UI、段階的に表示されるコンテンツを見落とさないよう、書き始める前にページ全体をゆっくりスクロールします。
• ページが表示されている間に、ブラウザー側のコードに関する証拠を取得します。レンダリング済み HTML、主要ノードの outerHTML、ルートの CSS 変数、読み取り可能なスタイルシートのルール、代表的なコンポーネントの計算済みスタイルが対象です。
• 別のブラウザースタックに切り替えるのではなく、agent-browser eval の直接呼び出し、または agent-browser を使用するラッパースクリプトを優先してください。
• scripts/extract-browser-evidence.mjs は、agent-browser を使用し続けたまま、シェルで生成した JSON アーティファクトをユーザーが明示的に求めた場合にのみ使用してください。
• デフォルトの手順では、スクリーンショットの取得のために作業を中断しないでください。ページ評価を使って、実行中のページから構造とスタイルを直接抽出してください。

2.1 推奨する評価ワークフロー

agent-browser eval または同等のブラウザー評価手段を利用できる場合は、次の順序で進めてください。

1. ページを開く
2. 読み込みとハイドレーションを待つ
3. ページをスクロールし、遅延読み込みコンテンツと固定状態の変化を発生させる
4. 代表的なノードのレンダリング済み HTML を抽出する
5. 見出し、ボタン、カード、ナビゲーション、セクションのラッパーの計算済みスタイルを抽出する
6. ルートの CSS 変数と、読み取り可能なスタイルシートのルールを抽出する
7. 表示されているテキストのスニペットと CTA の文言を抽出する
8. DOM または計算済みスタイルの変化を通じて、ホバー、アクティブ、固定、展開状態を調べる

手順 4 から 8 をスクリーンショットで置き換えないでください。

3. デザインシステムを抽出する

ページ固有の見た目だけでなく、再利用可能なルールを取得してください。

• 色とその役割
• サイトが対応している場合は、ライトテーマとダークテーマのバリエーション
• タイポグラフィの階層
• 余白のリズムとグリッドの動作
• 角丸の傾向
• 境界線の処理
• 影とサーフェスの重ね方
• 画像のスタイル
• アイコンのスタイル
• モーションとトランジションのスタイル
• 情報密度と余白に関する方針
• 観察できる場合は、スタイルシートと CSS 変数の規則
• 繰り返し使用されるコンポーネントが実際にどのように構成されているかを示す DOM のパターン

4. コンポーネントと状態を抽出する

主要な繰り返しパターンを調べます。

• ナビゲーション
• お知らせバー
• ヒーローブロック
• ボタンとリンク
• カード
• バッジ
• フォームと入力欄
• タブまたはピル
• アコーディオン
• テーブル
• フッター

重要な各コンポーネントについて、関連する表示状態を確認します。

• デフォルト
• ホバー
• アクティブまたは選択中
• 表示されている場合はフォーカス
• 表示されている場合は無効
• スクロール時または固定表示のバリエーション
• 開いた状態または展開した状態
• サイトがテーマ切り替えに対応している場合は、ライトモードとダークモードのバリエーション

5. インタラクションの挙動を抽出する

静的なビジュアルだけで終わらせないでください。

以下を記録します。

• スクロール時に変化する内容
• ホバー時に変化する内容
• クリック時に変化する内容
• ユーザーがライトモードとダークモードを切り替えたときに変化する内容
• ビュー内にアニメーションで表示される要素
• カルーセル、タブ、固定サイドバーが、クリック、スクロール、時間のいずれを起点として動作するか
• 動きの速さや、控えめ、鮮明、映画的、遊び心がある、抑制的といった印象
• ブラウザーで確認できる場合、インタラクション中に変化する CSS または DOM の状態

6. コンテンツとブランドの声を抽出する

デザインを形作るトーンを把握します。

• 見出しのスタイル
• CTA の表現
• 文の密度
• プロダクトの位置づけ
• 信頼性を示す要素
• 機能名のパターン
• コピーが技術的、遊び心のある、高級感のある、直接的、学術的、会話調のいずれか

優れた DESIGN.md では、ビジュアルとプレゼンテーションの両方を導く必要があるため、これは重要です。

6.1 テーマモードの確認

サイトが外観の切り替えに対応している場合：

• ブラウザーでライトモードとダークモードの切り替えを直接実行します
• 両モードの DOM と計算済みスタイルの根拠を抽出します
• 反転するトークンと、変わらないアクセントを記録します
• 画像、影、境界線、カード、コードブロックの扱いがモード間でどう変わるかを記録します
• 最終的なマークダウンと HTML プレビューの両方に、両モードの情報を反映します

出力要件

assets/DESIGN.template.md の構成に従って最終ドキュメントを作成します。

マークダウンの作成後、可能であれば scripts/render-design-preview.mjs を使って対応する HTML プレビューを生成します。

ブラウザーツールを利用できる場合は、作成前に DOM とスタイルを抽出することを優先します。根拠の確認順は次のとおりです。

1. レンダリングされた HTML と主要なノード構造
2. 計算済みスタイルと CSS 変数
3. インタラクション状態の差分
4. スクリーンショットによる任意の照合。ユーザーが明示的に求めた場合、または DOM の根拠が曖昧な場合に限ります

ページがライトテーマとダークテーマに対応している場合、出力要件には次の内容も含まれます。

1. DESIGN.md に Theme Modes の説明を明記する
2. 大きな違いがある場合、ライトモードとダークモードそれぞれのトークンに関する注記を分けて記載する
3. 対応する HTML プレビュー内に、ライト／ダークテーマの概要ブロックを表示する

通常、ドキュメントには次のセクションを含めます。

1. Visual Theme & Atmosphere
2. Color Palette & Roles
3. Typography Rules
4. Component Stylings
5. Layout Principles
6. Depth & Elevation
7. Do's and Don'ts
8. Responsive Behavior
9. Agent Prompt Guide

実質的な価値がある場合に限り、任意の付録を追加します。

• Interaction Patterns
• Content & Messaging Patterns
• Observed Pages
• Evidence Notes

サイトから十分な根拠が得られる場合は、これらのセクション内で、Stitch スタイルのより詳細な小見出しを優先します。

• Key Characteristics
• Primary、Interactive、Neutral Scale、Surface & Overlay、Shadows & Depth
• Font Family、Hierarchy、Principles
• Buttons、Cards & Containers、Inputs & Forms、Navigation、Image Treatment、Distinctive Components
• Spacing System、Grid & Container、Whitespace Philosophy、Border Radius Scale
• Breakpoints、Touch Targets、Collapsing Strategy
• Quick Color Reference、Example Component Prompts、Iteration Guide

サイトから十分な根拠が得られる場合は、高水準の概要だけにとどめず、より具体的な内容を記載してください。

HTML プレビューの仕様

デフォルトでは、Markdown と同じ場所に HTML ファイルを 1 つ生成します。

プレビューは次の要件を満たす必要があります。

• 別途手作業で管理された要約ではなく、最終版の DESIGN.md を情報源として使用する
• 実行のたびに新しい HTML フレームワークを考案するのではなく、固定のプレビューシェルテンプレートを使用する
• たとえば、概要、カラーパレット、タイポグラフィ、スペーシング、角丸、ボタン、カード、奥行き、レスポンシブ対応に関する注記など、最も有用な視覚ルールを左側に表示する
• ユーザーが元のドキュメントをすばやく確認したりコピーしたりできるよう、Markdown ソースを専用ペインに表示する
• 単なる Markdown のレンダリングではなく、洗練されたデザインボードのような見た目にする
• 可能な範囲で抽出したデザイントークンを使用し、プレビュー自体にドキュメント化されたデザインシステムを反映させる

利用可能な場合は、デフォルトのシェルとして assets/design-preview-shell.template.html を使用してください。このテンプレートは安定した基盤として扱い、ユーザーが新しいレイアウトの方向性を明示的に求めない限り、ドキュメント化されたトークンとコンテンツのみを入力してください。

ユーザーがレイアウトの視覚的な参考資料を提示した場合は、Markdown のデータから生成しつつ、HTML が同じ系統のデザインだと見てわかる程度に、その参考資料に忠実に従ってください。

構成ルール

最終ファイルを作成するときは、次の点を守ってください。

• 生のトークン名より、意味が伝わる名前を優先する
• 色の精度が重要な場合は、正確な 16 進数値を含める
• 角丸、スペーシング、シャドウ、文字サイズのスケールを、ほかのエージェントがすぐに活用できる平易な言葉で説明する
• ドキュメントは明確な意図があり、実用的なものにする。膨大なデータの羅列は避ける
• 見た目だけでなく、機能上の役割も説明する
• 繰り返し使われるパターンは、システムとしてまとめる
• ニュアンスを損なわない。サイトに 2 つのビジュアルモードが混在する場合は、両方と、それぞれが使われる場面を説明する
• 観察できる場合は、正確な 16 進数値、フォントサイズ、行の高さ、文字間隔、角丸の値、スペーシングの単位、複数レイヤーのシャドウの式など、具体的な数値を優先する
• サイトのアイデンティティにとって重要なパターンには、「境界線のようなシャドウ」や「圧縮によるアイデンティティ」のように、短い理念や理由を加える
• 元のサイトを見なくても別のエージェントが一致する UI を構築できるよう、役に立つ場合はコンポーネントごとの実装上の手がかりを含める
• 充実したサイトでは、Agent Prompt Guide に少なくともヒーロー、カード、ボタン、ナビゲーションのパターンについて、プロンプトに使える例を含める

値が観察結果ではなく推定の場合は、推定であることを明確にしつつ、実用的な情報として記載してください。

良い例：

• 「主要なアクションには、ダークチャコールのサーフェス上でクールなエレクトリックブルー #3B82F6 を使用します。」
• 「カードはアプリの UI というより編集的な印象です。控えめな境界線、大きな内側の余白、ごく軽い影による分離を特徴とします。」

悪い例：

• 「ボタンの背景色は rgb(59, 130, 246) です。」
• 「スペーシングがあり、角が少し丸くなっています。」

品質基準

最終版の DESIGN.md は、ほかのエージェントが追加の説明なしにプロンプトのコンテキストとして使えるものでなければなりません。

完成前に、次の点を確認してください。

• このドキュメントだけで、ほかのエージェントがサイトの雰囲気を再現できるか
• 主要な色が、それぞれ具体的な役割に結び付けられているか
• タイポグラフィの階層が、再利用できる程度に具体的か
• 主要なコンポーネントが、状態の違いも含めて十分に説明されているか
• 構成に大きく影響するレスポンシブ時の変化が記載されているか
• UI の外観だけでなく、文章のトーンも捉えられているか
• 実際には確認できないページや、表示されていない状態を捏造していないか
• 一致するコンポーネントライブラリを構築するのに必要なスペーシング、角丸、シャドウの挙動を、ほかのエージェントが把握できるか
• 代表的なセクションやコンポーネントを再現するための、プロンプトに使える例を 2〜4 個、ほかのエージェントに提示できるか

いずれかの答えが「いいえ」の場合は、完成前にサイトをもう一度確認してください。

詳細度の基準

ムードボードよりも、デザインルールブックに近いドキュメントを目指してください。

大規模なマーケティングサイトや、洗練されたプロダクトサイトの場合は、次の内容を含めてください。

• Visual Theme & Atmosphere に、少なくとも1つの内容の濃い段落を含める
• 単一の平坦なトークン表だけでなく、複数のカラーグループを含める
• 可能な限りサイズ、ウェイト、行の高さ、字間を記載した、タイポグラフィの階層を網羅する表を含める
• ボタン、カード、ナビゲーション、および独自性のあるパターンを少なくとも1つ取り上げ、コンポーネントの動作を明示する
• アイデンティティを構成する要素であれば、シャドウ、境界線、間隔、角丸について実装レベルの注記を含める
• 最終セクションに、プロンプトですぐ使える例と反復作業のルールを含める

実際に確認した情報量に比べて出力が短いと感じる場合は、完成前に内容を拡充してください。

デフォルトの成果物パターン

ユーザーから別の依頼がない限り、次の手順に従ってください。

1. agent-browser と agent-browser eval を使って、公開中のサイトを調査します。
2. 現在のワークスペースに、洗練された DESIGN.md ファイルを1つ作成します。
3. Markdown から、通常は scripts/render-design-preview.mjs を使って、同じ階層に HTML プレビューを1つ生成します。
4. シェルでの代替手段に切り替えたり、ツールをインストールしたりした場合は、その旨を最終回答で簡潔に伝えます。
5. デフォルトでは、対象フォルダーを整理された状態に保ちます。ユーザーから明示的な依頼がない限り、成果物の隣に単独の notes、note.md、research.md、evidence.md、または証拠の JSON ファイルを残さないでください。
6. 中間証拠ファイルが必要な場合は、対象フォルダーではなく、システムの一時パスを優先してください。scripts/extract-browser-evidence.mjs を使用する場合、ユーザーが成果物の保持を希望しない限り、出力パスを省略してください。
7. 最終回答では、デザインの最大の特徴、生成したファイル名、確認できなかった点を明記してください。

例外的なケース

複数のページ

ユーザーが同じプロダクトの URL を複数指定した場合：

• まず共通のデザインルールを特定します
• ページ固有の違いは別途記載します
• 各ページで同じシステムの説明を繰り返さないようにします

認証によるアクセス制限、または部分的なアクセス

サイトの一部にアクセスできない場合：

• 実際に確認できた内容だけを記録します
• 確認できなかった範囲を明示します
• 非表示のコンポーネントやフローを捏造しないでください

動的なアプリ

マーケティングページではなく複雑なアプリの場合：

• ナビゲーションモデル、情報密度、テーブルやパネルのパターン、フィルター、フォーム、空状態、状態変化の動作に焦点を当てます
• ダッシュボードまたはアプリシェルの構成ロジックを、レイアウト原則の一部として記録します
• ワークフロー固有のインタラクションがビジュアルシステムに影響する場合は、簡潔な付録にまとめます

ツールが利用できない場合

セッション開始時に使用可能なブラウザー自動化ツールがない場合：

• 推測せず、実際の環境を確認します
• まず agent-browser が利用可能かどうかを確認します
• プロジェクトフォルダー内のブラウザー依存関係の確認から始めないでください
• ツールがない場合は、ユーザーがインストールするか、PATH から利用できるようにする方法を案内します
• 実際に agent-browser --help などを実行して、利用可能であることを確認します
• セットアップが調査作業のためであることをユーザーに伝えます
• ユーザーから明示的な指示がない限り、Playwright や Chrome CLI に黙って切り替えないでください

便利な考え方

説明が字義どおりになりすぎると感じたときは、次のように考えてください。

「同じプロダクトのデザイン言語で新しいページを構築する前に、優れたデザインエンジニアリングエージェントが必要とするデザインシステムを記述する。」