DesignScan

DesignScan

URL → デザイントークン → DESIGN.md。任意の Web サイトを指定すると、AI コーディングエージェントがそのサイトの外観を再現できる、仕様に準拠した DESIGN.md ファイル（YAML トークン＋説明文）を生成します。

プレビュー

実行するたびに、抽出したトークン（色の役割、書体の見本、スペーシング／角丸のスケール、コンポーネント）を表示する自己完結型の HTML 検証シートも生成できます（--preview）。結果を信頼する前に、目視で確認できます。

コーディングエージェント向けの注意事項

DESIGN.md は常にAI コーディングエージェント（Cursor、Claude Code など）によって利用されます。そのため、意味上の意図を判断するために独自の LLM を実行する代わりに、すべてのファイルの末尾にコーディングエージェント向けの注意事項セクションを設けています。これは、実際のトークンから計算される、抽出ごとの決定論的な指示です。見出しの階層と控えめな text 色との関係、本文のコントラストが AA 基準未満であること、ブランドフォントのフォールバック、プライマリボタンの仕様、形状とスペーシングのリズムなどを扱います。推論は当方で行うため、API キーは不要です。適用は、すでに使用しているエージェント内で無料で行われます。

出力には、目に見える変化があります。以下は同じ stripe.DESIGN.md を、注意事項を無視したエージェント（左）と、従ったエージェント（右）が複製した結果です。トークン、レイアウト、コピーは同一です。

ブランドコーパス

実在するブランドの仕様を厳選したライブラリを、examples/ で公開しています。それぞれに DESIGN.md、HTML プレビュー、トークンの生 JSON が含まれ、examples/README.md で一覧を確認できます（ビジュアルギャラリー： index.html）。

コミット済みの JSON から pnpm seed rebuild で再構築できます（ネットワーク不要）。また、pnpm seed add <url> でブランドを追加できます。質の低いページやボット対策が施されたページは自動的にスキップされるため、信頼できる仕様だけがコーパスに含まれます。

モノレポの構成

パス	内容
packages/extractor	抽出・生成エンジン（Playwright → トークン → DESIGN.md）。
packages/designscan	短い npm 名。エンジンを利用する薄い CLI ラッパーです（npx designscan <url>）。
examples/	ブランドコーパス。各ブランドの DESIGN.md ＋ HTML プレビュー ＋ トークン JSON と、ギャラリーのインデックスが含まれます。

インストール（CLI／ライブラリとして）

エンジンは、公開可能な @designscan/extractor パッケージとして提供されます。designscan CLI と型定義付きライブラリを含み、短い npx エイリアスとして designscan を利用できます。

# one-off, no install
npx designscan stripe.com --md --out stripe.DESIGN.md

# or install the CLI
npm i -g @designscan/extractor
npx playwright install chromium   # one-time (the engine drives headless Chromium)
designscan stripe.com --md --preview --out stripe.DESIGN.md

クイックスタート（このリポジトリから）

これは pnpm ワークスペースです（corepack enable で pnpm を利用できます）。

pnpm install
pnpm --filter @designscan/extractor exec playwright install chromium  # one-time

# token profile (JSON) for any URL
pnpm extract stripe.com

# generate a DESIGN.md (light theme by default)
pnpm extract stripe.com --md --out out/stripe.DESIGN.md

# pick a theme: light (default) | dark | both
pnpm extract vercel.com --md --theme dark --out out/vercel.dark.DESIGN.md

# both = bundle light + dark into one file (parallel *-dark tokens)
pnpm extract vercel.com --md --theme both --out out/vercel.DESIGN.md

# --preview = also write a self-contained HTML proof sheet beside the file,
# rendering every token (swatches, type specimens, scales, components) so you
# can eyeball the extraction before trusting it (--theme both adds a Light/Dark toggle)
pnpm extract stripe.com --md --preview --out out/stripe.DESIGN.md
# → out/stripe.DESIGN.md  +  out/stripe.preview.html

# --format = pick your output: json (profile) | md (DESIGN.md) | w3c | css
pnpm extract stripe.com --format w3c --out out/stripe.tokens.json  # W3C Design Tokens (Style Dictionary etc.)
pnpm extract stripe.com --format css --out out/stripe.tokens.css   # CSS custom properties, paste-ready
# (--theme both folds a genuinely distinct dark pass into every format)

# --strict = exit non-zero if the result looks degenerate (bot challenge / too
# few signals), for CI/automation that must not consume junk tokens
pnpm extract stripe.com --strict --quiet

# seed / rebuild the curated brand corpus under examples/
pnpm seed add tailwindcss.com vercel.com   # extract live + add to the corpus
pnpm seed rebuild                          # regen md/preview/gallery from JSON

スクリプト（ルート）

スクリプト	内容
pnpm extract <url> [--format json|md|w3c|css] [--theme light|dark|both] [--preview] [--strict] [--timeout ms] [--out f]	指定した形式でトークンを抽出します。プロファイル JSON、DESIGN.md（--md は短縮形）、W3C Design Tokens、CSS カスタムプロパティに対応します（--theme both = 1 ファイルにライトテーマとダークテーマを両方出力、--preview = HTML 検証シートを同じ場所に出力、--strict = 質の低い結果の場合にゼロ以外の終了コードを返す）。
pnpm seed rebuild / pnpm seed add <url…>	examples/ のブランドコーパスを構築します（md ＋ プレビュー ＋ ギャラリー。add はライブサイトから抽出します）。
pnpm build	公開可能なパッケージをコンパイルします（tsc → dist）。
pnpm typecheck	すべてのパッケージの型をチェックします。
pnpm test	テストスイートを実行します（vitest）。
pnpm check	Biome によるフォーマットとリンティングを実行します（自動修正には pnpm format を使用）。
pnpm lint:designmd	examples/*.DESIGN.md を公式仕様に照らして検証します。

これらはすべて、GitHub Actions により、プッシュ／PR のたびに実行されます。エンジンは、公開 API（packages/extractor/src/index.ts）を通じてライブラリとして利用できます。

ステータス

• ステップ 1 — 抽出エンジン（Playwright → クリーンなトークンプロファイル）
• ステップ 2 — ジェネレーター（トークンプロファイル → 仕様に準拠した DESIGN.md、リントエラーなし）
• ステップ 3 — HTML プレビュー（--preview → 自己完結型のトークン検証シート、ライト／ダーク切り替え）
• [~] ステップ 4 — エージェント向けガイダンス。各 DESIGN.md に コーディングエージェント向けのメモ セクションが含まれるようになりました。抽出ごとに生成される決定的な指示（コントラスト、見出しの階層、フォントのフォールバック）により、利用するエージェントが意図を踏まえてトークンを適用します。当方では LLM を使用しません。（LLM で文章を調整するオプションは今後対応予定です。）
• [~] ステップ 5 — ブランドシードライブラリ（pnpm seed、厳選されたコーパスとギャラリー）は完了。次は npx … add ／チェックアウト

ロードマップとエンジンの詳細については、packages/extractor/README.md を参照してください。