Paidax01/web-to-design-md

Webサイト → DESIGN.md

概要

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

目的はサイトをクローンすることではありません。目的は、別のエージェントが元のWebサイトを見なくても、同じデザイン言語、コンテンツのトーン、インタラクションの感触を再現できるように、サイトを十分に深く調査することです。

HTMLプレビューは実用的なレビュー画面です。マークダウンを一目でわかるデザインボードに変換し、ユーザーがサイトを再度開かなくても、パレット、タイポグラフィ、スペーシング、コンポーネントの手がかり、そして生のマークダウンソースを検査できるようにします。

ユニバーサルブラウザルール

このスキルは常に 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 を使用し、ユーザーが agent-browser をインストールまたは公開できるように支援します。
4. 主要なパスとして、現在のフォルダにPlaywright、Chrome CLI、またはローカルブラウザの実行可能ファイルがないか検査しないでください。
5. ユーザーが明示的にそのフォールバックを要求しない限り、PlaywrightまたはChrome CLIに黙ってフォールバックしないでください。
6. マークダウン出力ファイルのデフォルトを DESIGN.md にします。
7. コンパニオンプレビューファイルのデフォルトを同じベース名に -preview.html を付けたものにします。例：DESIGN-preview.html または design-preview.html。
8. ユーザーが明示的に design.md、カスタムファイル名、またはカスタムフォルダを要求した場合は、それを正確に尊重し、ユーザーが要求しない限り、HTMLプレビューをその隣に配置します。
9. 複数のURLが提供された場合は、それぞれを個別に調査し、ビジュアル言語がページ間で明確に一貫している場合にのみ、1つの共有デザインシステムに統合します。

ブラウザツーリングのブートストラップ

ブラウザツーリングのセットアップを、個別のユーザーの作業ではなく、スキルの一部として扱います。

検出

この順序で確認します：

• agent-browser が既に呼び出し可能かどうか
• そうでない場合、すぐにインストールまたは公開できるかどうか

バンドルされたチェッカースクリプトは以下を報告します：

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

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

agent-browser が利用できない場合は、ユーザーがそれをインストールするか PATH に公開できるように支援し、スキルを使用する前に agent-browser --help で確認します。

インストール動作

• スキルが一貫して agent-browser を使用できるようにインストールが必要であることを説明します。
• ネットワークまたはサンドボックスの制限により最初のインストール試行が失敗した場合は、必要な承認を要求して再試行します。
• インストールが成功した場合は、同じターンでサイト分析に直接進みます。
• インストールが失敗した場合は、何が不足しているかをユーザーに明確に伝え、別の抽出ツールに黙って切り替えずに停止します。
• ツールがないという理由だけで、静的なHTMLスクレイピングに黙ってダウングレードしないでください。

必須抽出パス

何を検査すべきかについてより深いリマインダーが必要な場合は、references/website-reading-checklist.md のチェックリストを使用します。

1. ページのスコープを定義

• ページの目的を特定します。
• ページがマーケティング、製品、ダッシュボード、ドキュメント、Eコマース、編集、または混合のいずれであるかを特定します。
• 上部から下部までの重要な可視セクションを特定します。
• アクセスできない領域や隠れた領域がある場合は、それを発明せずにメモします。

2. ベースラインを取得

• 最初にデスクトップでページを検査します。
• レイアウトが実質的に変更される場合は、タブレットとモバイルも検査します。
• 何かを書く前に、ページ全体をゆっくりスクロールして、遅延アニメーション、固定UI、またはプログレッシブディスクロージャーを見逃さないようにします。
• ページがライブの間にブラウザ側のコードエビデンスを取得します：レンダリングされたHTML、主要なノードの outerHTML、ルートCSS変数、読み取り可能なスタイルシートルール、および代表的なコンポーネントの計算済みスタイル。
• 別のブラウザスタックに切り替えるのではなく、直接の agent-browser eval 呼び出しまたは agent-browser 駆動のラッパースクリプトを優先します。
• scripts/extract-browser-evidence.mjs は、ユーザーが明示的にシェル生成のJSONアーティファクトを希望し、かつ agent-browser を使い続ける場合にのみ使用します。
• デフォルトのパス中はスクリーンショットキャプチャのために一時停止しないでください。ページ評価を使用して、実行中のページから構造とスタイルを直接抽出します。

2.1 推奨Evalワークフロー

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-and-style抽出パスを優先します。期待されるエビデンスの順序は次のとおりです：

1. レンダリングされたHTMLと主要なノード構造
2. 計算済みスタイルとCSS変数
3. インタラクション状態の差分
4. ユーザーが明示的に要求した場合、またはDOMエビデンスがあいまいな場合にのみ、オプションのスクリーンショットクロスチェック

ページがライトテーマとダークテーマをサポートしている場合、出力契約では以下も必要です：

1. DESIGN.md での明示的な テーマモード の文書化
2. 実質的に異なる場合のライトモードとダークモードのトークンノートの分離
3. コンパニオンHTMLプレビューでの可視のライト/ダークテーマの要約ブロック

文書には通常、次のセクションを含める必要があります：

1. ビジュアルテーマと雰囲気
2. カラーパレットと役割
3. タイポグラフィルール
4. コンポーネントスタイリング
5. レイアウトの原則
6. 奥行きと高さ
7. すべきこととすべきでないこと
8. レスポンシブ動作
9. エージェントプロンプトガイド

付加価値がある場合にのみ、オプションの付録を追加します：

• インタラクションパターン
• コンテンツとメッセージングパターン
• 観察されたページ
• エビデンスノート

これらのセクション内では、サイトがサポートしている場合、よりリッチなStitchスタイルのサブセクションを優先します：

• 主要な特性
• プライマリ、インタラクティブ、ニュートラルスケール、サーフェスとオーバーレイ、シャドウと奥行き
• フォントファミリー、階層、原則
• ボタン、カードとコンテナ、入力とフォーム、ナビゲーション、画像処理、特徴的なコンポーネント
• スペーシングシステム、グリッドとコンテナ、ホワイトスペースの哲学、ボーダー半径スケール
• ブレークポイント、タッチターゲット、折りたたみ戦略
• クイックカラーリファレンス、コンポーネントプロンプトの例、イテレーションガイド

サイトがより正確であるための十分なエビデンスを公開している場合、文書を高レベルの要約のレベルに留めないでください。

HTMLプレビュー契約

デフォルトでマークダウンの隣に1つのHTMLファイルを生成します。

プレビューは：

• 別途手動でメンテナンスされたサマリーではなく、最終的な DESIGN.md を真実のソースとして使用する必要があります
• 実行ごとに新しく発明されたHTMLフレームワークではなく、固定されたプレビューシェルテンプレートを使用する必要があります
• 最も有用な視覚ルールを左側に表示します。例：概要、パレット、タイポグラフィ、スペーシング、半径、ボタン、カード、奥行き、レスポンシブノート
• ユーザーが元の文書をすばやく検査またはコピーできるように、マークダウンソースを専用ペインに表示し続ける必要があります
• プレーンなマークダウンレンダリングではなく、洗練されたデザインボードのように感じさせる必要があります
• 実用的な場合は抽出されたデザイントークンを使用して、プレビュー自体が文書化されたシステムを反映するようにします

利用可能な場合は、assets/design-preview-shell.template.html をデフォルトシェルとして使用します。そのテンプレートを安定したインフラストラクチャとして扱い、文書化されたトークンとコンテンツのみをそれに入力します。ユーザーが明示的に新しいレイアウトの方向性を要求した場合を除きます。

ユーザーがレイアウトの視覚的なリファレンスを提供する場合、マークダウンデータから生成されている間に、HTMLが同じファミリーであることが認識できる程度にそれに厳密に従います。

合成ルール

最終ファイルを作成するとき：

• 生のトークンラベルよりも意味的な名前を優先します。
• 色の精度が重要な場合は、正確な16進数値を含めます。
• 半径、スペーシング、シャドウ、タイプスケールを、別のエージェントがすぐに使用できる平易な言語に変換します。
• 文書を意見があり、使用可能な状態に保ちます。巨大なデータダンプは避けます。
• 外観だけでなく、機能的な役割を説明します。
• 繰り返しパターンをシステムにグループ化します。
• ニュアンスを保持します。サイトが2つのビジュアルモードを混在させている場合は、両方を説明し、それぞれがいつ表示されるかを示します。
• 観察可能な場合は、正確な数値詳細を優先します：正確な16進数値、フォントサイズ、行の高さ、文字間隔、半径値、スペーシング単位、マルチレイヤーシャドウ式。
• パターンがサイトのアイデンティティの中心である場合、短い哲学または根拠を追加します。例：「シャドウ・アズ・ボーダー」または「圧縮としてのアイデンティティ」。
• 別のエージェントがソースサイトを見ずに一致するUIを構築するのに役立つ場合、コンポーネント固有の実装の手がかりを含めます。
• かなりのサイトでは、エージェントプロンプトガイド に、少なくともヒーロー、カード、ボタン、またはナビゲーションパターンのプロンプトレディな例を含めます。
• 一部の値が観測ではなく推測された場合は、明確にラベル付けされたままにしますが、それでも有用にします。

良い例：

• 「プライマリアクションは、クールなエレクトリックブルー #3B82F6 と、白いテキストに14pxのセミボールドのInterフォントを使用します。ホバー時には背景が #2563EB に暗くなり、box-shadow: 0 4px 12px rgba(59, 130, 246, 0.4) が追加されます。transition: all 0.2s ease でスムーズに変化します。」

悪い例：

• 「ボタンは青くてホバー時に変化します。」

ファイル

• assets/DESIGN.template.md — 出力マークダウンのテンプレート構造
• assets/design-preview-shell.template.html — データが入力されるHTMLプレビューシェル
• scripts/check-browser-tooling.mjs — ブラウザツーリング検出
• scripts/extract-browser-evidence.mjs — オプションのブラウザエビデンス抽出ラッパー（agent-browser 上で動作）
• scripts/render-design-preview.mjs — テンプレートにデータを入力してHTMLプレビューをレンダリング
• references/website-reading-checklist.md — 抽出中に何を検査するかのチェックリスト