extract-design-md

サイトから DESIGN.md を抽出する

ライブ URL を指定すると、YAML 形式のデザイントークン（色、タイポグラフィ、rounded、spacing、components）と正規のセクション順に並んだ説明文を含む DESIGN.md を生成します。コーディングエージェントに渡して、参照元サイトに合った新しい UI を構築できる品質を目指します。

基本理念（調査に基づく）： トークンはサイトの CSS カスタムプロパティと計算済みスタイルにほぼ 1 対 1 で対応するため、手間のかかる処理は、低コストのブラウザー内抽出で済みます。画像認識は不要です。スクリーンショットは説明文のみに使用します。公式リンターは無料の品質チェックとして利用できます。

URL ─▶ 1 DISCOVER ─▶ 2 EXTRACT TOKENS ─▶ 3 HARVEST COMPONENTS
        ─▶ 4 CAPTURE FEEL ─▶ 5 SYNTHESIZE ─▶ 6 VALIDATE ─▶ DESIGN.md

前提条件

このスキルは 3 つの外部ツールを使用します。実行前に、それぞれが利用できることを確認してください。

• playwright-cli が PATH 上にあること。ブラウザー内での抽出とスクリーンショットの取得に使用します。次のコマンドで一度インストールします：npm install -g @playwright/cli@latest の後に playwright-cli install --skills を実行します（Node.js 18 以降が必要です）。確認方法：which playwright-cli。
• 接続可能な Firecrawl インスタンス。ページの検出（firecrawl map）と、任意のコピーのスクレイピングに使用します。ホスト型 API、セルフホスト型またはローカルのインスタンスを利用できます。Firecrawl に接続できない場合、スキルは playwright によるリンク検出にフォールバックします（ページのカバー範囲は狭くなります）。実行前に、インスタンスが応答することを確認してください。
• npx（Node.js）。品質チェックのために、必要に応じて公式の @google/design.md リンターを取得します。利用できない場合でも、スキルはファイルを出力し、「lint skipped」と記録します。

エージェントのサンドボックスでネットワークまたはファイルシステムへのアクセスが制限されている場合は、実行前に、このスキルが行う外部へのアクセス（ヘッドレスブラウジング、Firecrawl、npx）を許可してください。

SKILL をこのスキルのディレクトリとします。安定した playwright セッション名を選びます（例：S=designmd）。

フラグ

フラグ	デフォルト	効果
<url>	必須	エントリーポイント URL
--pages <n>	5	サンプルとして取得するページの最大数
--pages-list <paths>	auto	ページを正確に指定します（確認プロンプトを省略）
--no-screenshots	shots ON	デザインの雰囲気を確認する工程を省略します。説明文はトークン名とコピーを参考にします
--theme <auto|light|dark|both>	auto	auto はテーマを検出します。both はライトとダークの両方を強制し、light／dark は一方を指定します
--out <dir>	.design_mds/<domain>-YYYYMMDD/	出力フォルダー
--no-lint	lint ON	リンターを省略します（npx が利用できない場合は自動的に省略）

---

ステージ 1 — ページを検出する

firecrawl map "<url>" > "<out>/raw/map.json"

返された URL をページタイプごとの枠に分類し、各枠に最も合うページを選びます（ホームページは必ず含めます）。ページ数は --pages（デフォルトは 5）を上限とします。

• ホームページ（入力 URL、必須） — 基本の配色、タイポグラフィ、ヒーローの CTA
• 料金／製品 — カード、切り替え、テーブル
• 認証／ログイン／サインアップ／問い合わせ — 入力欄、フォームフィールド
• ブログ／ドキュメント／変更履歴 — 長文用のタイポグラフィ
• ブランド／会社概要／デザイン — 色とフォントが明記されていることが多く、価値が高い

自動選択したページの一覧を表示し、クロール前に追加／削除／置換を受け付けます（簡潔なプロンプトを 1 回表示します。--pages-list が指定されている場合は省略します）。該当ページがない枠はスキップし、サンプルを無理に選ばないでください。Firecrawl が停止している場合は、playwright によるリンク検出（run-code で [...document.links].map(a=>a.href) を返す）にフォールバックします。references/edge-cases.md を参照してください。

Stage 2 — グローバルトークンを抽出する（コア）

ホームページを開き、ページが安定するまで待ってから、同梱の抽出スクリプトを実行します。抽出スクリプト （scripts/extract-tokens.js）は、ノイズを除外した :root 変数を読み込み、メインコンテンツ内で表示されている要素の計算済みスタイルをモードごとにサンプリングし、 目立つ CTA と最初の入力欄にタグを付け、ホバー／フォーカス状態を強制します。返される内容とその理由については、 references/extraction.md を参照してください。

中間生成物は <out>/raw/ に保存し、2 つの成果物がフォルダーのルートを散らかさないようにします。出力レイアウトを参照してください。フォルダーは一度だけ作成します。

S=designmd
mkdir -p "<out>/raw/tokens" "<out>/raw/components" "<out>/raw/copy" "<out>/raw/logs" "<out>/screenshots"
playwright-cli -s=$S open "<homepage-url>"
sleep 2                                              # let CSS/fonts settle (FR-ROB.1)
playwright-cli -s=$S run-code "$(cat "$SKILL/scripts/extract-tokens.js")" \
  | bash "$SKILL/scripts/slice-result.sh" > "<out>/raw/tokens/tokens.home.json"

slice-result.sh は playwright-cli の Markdown ラッパーを取り除き、整形済みの JSON を出力します。 読み戻して、varsTotal／vars の数を確認します。vars が少ない場合（サイトが Tailwind 風でない場合）は、varsExtra を使ってフィルターを緩めてください — references/edge-cases.md（EC-FW.1 / デザインシステムなし）を参照してください。

テーマの検出（decision 8）

JSON の themeSignal を確認します。ライト／ダーク切り替え機能（<html> の .dark クラスまたは data-theme、あるいは prefers-color-scheme への応答）があるサイトは、デュアルテーマです。2 つのテーマがあり、--theme が auto／both の場合は、テーマごとに 1 回ずつ抽出します。切り替え、再度安定するまで待機し、抽出スクリプトを再実行して 2 つ目のファイル（raw/tokens/tokens.home.dark.json）に出力します。切り替え方法の優先順位は次のとおりです。

1. サイト独自のテーマ切り替えボタンをクリックします。それがない場合は、
2. クラス／属性を直接設定します。例：run-code で document.documentElement.classList.add('dark')（または setAttribute('data-theme','dark')）を実行します。それができない場合は、
3. prefers-color-scheme をエミュレートします。

切り替え後に、もう一度 sleep 2 します。もう一方のテーマを確実に呼び出せない場合は、読み込まれたテーマのみを取得し、DESIGN.md を 1 つ作成して、その旨をレポートに記載します。 --theme light|dark を指定すると、デュアルテーマのサイトでもテーマを 1 つに固定できます。詳細は references/edge-cases.md（EC-TH）を参照してください。

Stage 3 — コンポーネントと状態を収集する（ページ 2〜N）

ページを追加するたびに、グローバル変数を再度ダンプしないでください（変数は共有されます）。そのページで有用なコンポーネントをサンプリングします（認証ページでは入力欄、料金ページではカード／トグル、ブログでは本文など）。同じ抽出スクリプトを再利用し、各ページの JSON を保存します。

playwright-cli -s=$S goto "<page-2-url>"
sleep 2
playwright-cli -s=$S run-code "$(cat "$SKILL/scripts/extract-tokens.js")" \
  | bash "$SKILL/scripts/slice-result.sh" > "<out>/raw/tokens/tokens.<slug>.json"

ページ固有のコンポーネントキャプチャ（カード／ピル候補など）は <out>/raw/components/ に、スクレイプしたコピーは <out>/raw/copy/ に、手順ごとのログは <out>/raw/logs/ に保存します。

抽出スクリプトは CTA に hover、最初の入力欄に focus をすでに強制し、その差分を states に返します。合成時には、ベースから異なる状態のみ（FR-ST.3）を残してください。ページ間で統合するときは、CSS 変数をまとめ（コアパレットにはホームページの値を採用し、競合にはフラグを付ける）、コンポーネントを蓄積して、スタイルが同一のものをまとめます。

Stage 4 — 見た目の雰囲気をキャプチャする（任意、デフォルトで ON）

サンプリングしたページごとに、全ページではなく ビューポートのスクリーンショットを 1 枚、screenshots/ に保存します。

playwright-cli -s=$S screenshot --filename="<out>/screenshots/<slug>.png"

必要に応じて、ホームページとブランドページを firecrawl scrape --only-main-content "<url>" でスクレイプし、コピー／タグラインを <out>/raw/copy/ に保存します。スクリーンショットは <out>/screenshots/ に残します（文章作成に使用し、ユーザーが参照する場合もあります）。スクリーンショットとコピーは文章作成のみ（Overview、Do's & Don'ts）に使用します — トークンの値をスクリーンショットから読み取らないでください。--no-screenshots を指定すると、このステージをスキップします。

ステージ 5 — DESIGN ファイルを作成する

マージ済みの raw/tokens/*.json を読み込み、DESIGN.md のスキーマにマッピングします。スキーマ全体、 トークン→DESIGN のマッピング表、標準の文章セクション順は references/design-md-schema.md にあります。ファイルを書き始める前に読んでください。 主なルール：

• プライマリパレットの色は、計算済みの rgb(...) 値から hex に変換します。フォールバックとして 元の CSS 変数（lab()／color-mix() など）を残します。色をでっち上げてはいけません。
• 色には意味的な役割に基づいた名前を付けます（--color-accent → primary／accent）。長い グレーの色調を代表的な neutral セットにまとめ、すべての色合いではなくシステムを捉えます。
• components 内では {path.to.token} 参照を使い、値を DRY に保ち、リンターで検証できるようにします。 primary カラーが存在しない場合、リンターでエラーになります。
• ページ上で実際に確認できるコンポーネントのみを記録します（判断 10）。存在しない card／chip を でっち上げてはいけません。レポートには、一般的なセット（button、input、card、link、chip）のうち 見つかったものと見つからなかったものを記録します。
• 実際の根拠がある場合にのみ文章セクションを出力し、必ず標準の順序に従います。また、同じ ## 見出しを 重複させてはいけません。

デュアルテーマ出力（判断 8）

2 つのテーマを取得した場合は、DESIGN.light.md と DESIGN.dark.md を出力します。それぞれ完全な リンター検証済みファイルにしてください。typography、rounded、spacing は共通で、 colors と色に依存する components はテーマごとにします。単一テーマのサイトでは DESIGN.md を 1 つ 出力します。文章では、もう一方のテーマファイルが存在することに触れてもかまいません。

ステージ 6 — 検証（品質ゲート）

生成したすべてのファイルを lint します。

npx -y @google/design.md lint "<out>/DESIGN.md"

• 構造上のエラーのみを自動修正します：セクションの順序違い、壊れた {refs}、primary／必須フィールドの 欠落。
• 値レベルの問題（色域外の色、不自然な寸法）はレポートに警告として記載します。リンターを通すために、 取得したトークンを黙って削除してはいけません（判断 12）。警告された値への対応はユーザーが決めます。
• 致命的でない警告（例：WCAG AA のコントラスト）を、処理を止めずに提示します。
• 修正後に再度 lint し、最終ファイルにエラーがない状態にします。npx／リンターが利用できない場合も ファイルを作成し、レポートに「lint をスキップ」と記載します。

---

出力構成

2 つの成果物はフォルダーのルートに置き、中間生成物はすべて raw/ の下にまとめます。こうすることで、 出力をひと目で確認できます。

.design_mds/<domain>-YYYYMMDD/        # <domain> = host with dots→hyphens
├── DESIGN.md                         # single-theme   (or DESIGN.light.md + DESIGN.dark.md)
├── screenshots/<slug>.png            # 1 desktop-viewport PNG per page (if enabled)
└── raw/                              # intermediate artifacts (audit trail + re-runs)
    ├── tokens/tokens.<slug>.json     # raw extracted token/computed-style data per page/theme
    ├── components/                   # any bespoke per-page component captures
    ├── copy/                         # scraped page copy (if screenshots stage ran)
    ├── logs/                         # per-step playwright/firecrawl logs
    └── map.json                      # firecrawl page-discovery result

raw/tokens/*.json は（判断 9 に従い）必ず保持します。再クロールせずに文章を再生成でき、各値の 出所も追跡できるためです。競合防止： 今日のドメイン用のフォルダーがすでに存在する場合は、 （上書き／-2 を付ける／中止）のいずれかを確認します。黙って上書きしてはいけません。

最終レポート

簡潔かつ正確にまとめます。取得した内容、見つかったコンポーネントと見つからなかったコンポーネント、 テーマの数、リンターの出力を具体的に記載します。どこかのステージで劣化があった場合（デザインシステムが ない、Firecrawl が停止中、lint をスキップしたなど）は、そのことを明記します。完全な忠実度が得られたかのように 示してはいけません。

DESIGN.light.md + DESIGN.dark.md → .design_mds/cursor-com-20260630/

Sampled 4 pages: home, pricing, sign-in, blog
Themes: light + dark (detected via .dark on <html>)
Captured: 9 colors/theme, 6 type roles, 7 radius, full spacing
Components found: button-primary (+hover), input-field (+focus), card · missing: chip
Lint: ✓ both files clean (1 contrast warning on dark: text-muted on bg — AA borderline)
Screenshots: screenshots/ (4, desktop viewport)

まず確認するルール（常時適用）

マッピングや曖昧な選択について95% 未満の確信しか持てない場合は（どちらの色が「primary」か、サイトに 実際のデザインシステムがあるか、同日出力の競合をどう解決するかなど）、推測せず、推奨案を添えて確認 します。最低限、曖昧さをレポートに記載します。起動するサブエージェントは並列ではなく必ず順番に実行し、 上記の Firecrawl およびサンドボックスのルールを適用する必要があります。

同梱ファイル

• scripts/extract-tokens.js — run-code 用のブラウザー内抽出ツール（ノイズフィルター、 モードのサンプリング、CTA／入力の検出、ホバー／フォーカス）。実績ある中核機能を本番向けにしたものです。
• scripts/slice-result.sh — playwright-cli の Markdown ラッパーを取り除き、JSON のみにします。
• references/extraction.md — 抽出ツールが返す内容のフィールドごとの説明と、フィルターを緩和するための varsExtra の使い方。
• references/design-md-schema.md — DESIGN.md の YAML スキーマ、トークン→DESIGN のマッピング表、 標準の文章順。ステージ 5 の前に読んでください。
• references/edge-cases.md — デザインシステムがない場合、非 Tailwind の場合、デュアルテーマの切り替え、 マージの競合、クロール／読み込みの失敗、結果が空の場合。