distill-design

/distill-design — ウェブサイトから DESIGN.md を抽出する

実際のウェブサイトを DESIGN.md に変換します。これはプレーンテキストのデザインシステム仕様（YAML のトークンフロントマター + 11 個の文章セクション）で、あらゆる AI エージェントが読み取ってブランドに沿った UI を生成できます。コンセプトとフォーマットは VoltAgent/awesome-design-md に準拠しています。

引数: ウェブサイトの URL（$ARGUMENTS）。指定がない場合は、URL を尋ねてください。

生成されるもの: デフォルトでは、DESIGN.md のみです。ビジュアルの preview.html とリアルな demo.html はオプトインです — ユーザーが要求した場合にのみ生成してください（以下の 2 つの「リクエスト時」セクションを参照）。

まず以下を読んでください

• reference/format-spec.md — 正確なフロントマタースキーマと 11 セクションの本文。
• reference/extraction-guide.md — 実際のサイトからトークンを測定する方法。
• reference/template.md — 記入する DESIGN.md のスケルトン。
• reference/preview-template.html — 正規の、データ駆動型 preview.html。 これをそのままコピーし、トークン JSON のみを注入してください（「トークンプレビューを生成する」を参照）。
• reference/demo-guide.md — リアルなデモを構築する方法（要求された場合のみ）。 （これらはこの SKILL.md の隣に同梱されているため、兄弟ファイルとして読んでください。） preview.html のシェルはすべてのブランドで同じです — 上記のテンプレートを使用し、決して 手書きしないでください。オーダーメイドの demo.html については、ソースリポジトリ （ake77-code/distill-design）内のサンプルフォルダ examples/stripe、 examples/linear、examples/spotify が参考になります。

出力の書き込み先

デフォルトでは、現在のプロジェクトに書き込みます（このスキル自身のフォルダではありません）:

• 単一の仕様 → ./DESIGN.md（プロジェクトルート）。オプションの preview.html / demo.html は、要求された場合にのみその隣に置きます。
• 複数の仕様 → ブランドごとに distill-design/<brand>/ フォルダを使用します。
• ユーザーが明示したパスは常に尊重してください。

ワークフロー

1. 対象の範囲を定める

URL を確認します。ホームページ以外に調査する価値のあるいくつかのページタイプを特定します: マーケティング、料金、ドキュメント、そして到達可能であればアプリ／ダッシュボード。ブランドはしばしば 極性を反転させます（明るいマーケティング → 暗いアプリ） — 両方を捉える計画を立ててください。

2. 調査と測定

推測よりも測定した値を優先してください。実際のヘッドレスブラウザを操作し、getComputedStyle を読み取ります — 以下を厳密な順序で試し、最初に成功したもので停止してください （完全なスニペットは extraction-guide.md にあります）:

1. Playwright（推奨） — Bash 経由で Chromium をスクリプト操作します。なければ npx -y playwright install chromium（または bunx playwright install chromium）で インストールし、page.$eval(sel, …) で正確な hex、フォントスタック、角丸、パディング、 シャドウを読み取ります。スクリーンショットも撮ります。（npx と bunx は全体を通して互換です。）
2. Puppeteer（フォールバック） — Playwright が利用できない場合、require("puppeteer") を 介して同じアプローチを行います。npx -y puppeteer browsers install chrome（または bunx の同等のもの）でインストールします。
3. Browser MCP（Chrome / Preview） — すでに接続されている場合にのみ。
4. WebFetch / fetch（最終手段） — テキストのみで、ピクセル値はありません。ブラウザが 実行できない場合にのみ使用してください。ブランド知識と組み合わせ、出力を「inspired interpretation（インスパイアされた解釈）」とラベル付けして Colors の注記と ## Known Gaps に記載してください。

ヒーロー、本文テキスト、ボタン、カード、ナビ、入力欄、フッターを網羅してください。色 → 役割、 タイプスケール、角丸スケール、スペーシングの基本単位、エレベーション、コンポーネントごとの仕様と 状態、そして 2〜3 個のシグネチャーモチーフを抽出してください。

3. トークンにマッピングする — 徹底的に深く

最もよくある失敗は、ファイルが薄すぎることです。実際のブランドは多くのトークンを持っています。その深さに合わせてください(目標値は format-spec.md を参照):

• カラー ~18〜30+、役割で命名し、フラットに保ちます。極性は colors: 内で *-on-dark テキストバリアントと surface-dark-* タイルによって表現します。ミュートされたインクは名前におおよその不透明度を付けて階層化します(ink-muted-64)。同一役割の hex は ~2% 以内でのみ重複排除します。
• タイポグラフィ ~12〜20 のセマンティックな役割(hero-display、lead、tagline、body-strong、dense-link、caption-strong、button-large、fine-print、micro-legal、nav-link)、それぞれに weight、line-height、px 単位の letterSpacing、そして実際に存在する場合のみ fontFeature を付けます。珍しいウェイト(300 / 600 対 700)も捉えます。
• rounded には none:0 + full を、spacing には実測された特異値(17px)と section ステップを含めます。理想化された 4/8/12 ではなく、実測値を使用してください。
• コンポーネント ~15〜30+、それぞれが {group.token} の組み合わせ(リテラルの padding/height/size は許可)。バリアントは別々のキー(-active、-focus、-selected、-2)です。hover を決してドキュメント化しないでください。
• プロプライエタリなフォントには オープンソースの代替 を選びます。

4. DESIGN.md を書く

reference/template.md を出力パス(デフォルトは ./DESIGN.md — 「出力を書き込む場所」を参照)に埋めます。11 セクション構造 と同梱サンプルの文章トーンに従ってください。name: は <Brand>-design-analysis です。frontmatter の description は最も重要なフィールドです — 1 行に詰め込んだ密な段落(> ブロックではなくプレーンスカラー)で、目を閉じてもサイトを思い描けるほど生き生きとしたものにします。

5. DESIGN.md を自己チェックする

• frontmatter が有効な YAML であること。不安なら簡単にパースを実行してください(下記の検証を参照)。
• 本文中のすべての {group.token} が、定義済みの frontmatter キーに解決されること。
• 11 セクション がすべて存在し、空でないこと(Overview → Known Gaps)。必須の ## Known Gaps を含みます。
• 深さの目標を満たしていること(~18+ カラー、~12+ タイプ役割、~15+ コンポーネント)。description はインラインです。-hover コンポーネントキーがないこと(簡単な文章での hover 説明は問題ありません)。letterSpacing は px 単位です。
• カラーは役割で命名され、重複排除されていること。プロプライエタリなフォントには代替があること。

6. ビジュアライゼーションを提案する(常にこれで終わる)

DESIGN.md が成果物です。preview.html や demo.html を自動生成しないでください。 返信の最後に、ユーザーがどちらかを選べることを思い出させてください。例:

已生成 DESIGN.md。需要的话我还能基于它生成: ① preview.html —— 设计系统可视化(色板 / 字阶 / 组件,带顶部导航与明暗切换); ② demo.html —— 像真实网站的 Web 落地页或移动端界面。 两者都按需生成,要哪个告诉我。

(ユーザーの言語に合わせてください。)preview.html は求められた場合のみ生成します → 下記の「トークンプレビューを生成する」に従ってください。demo.html は求められた場合のみ生成します → 下記の「リアルなデモを生成する」に従ってください。

トークンプレビュー preview.html を生成する(リクエスト時)

ブランドごとの HTML/CSS を手書きしないでください。 プレビューシェルはどのウェブサイトでも同一です — 変わるのは注入されるデータだけです。このスキルには、1 つの正規のデータ駆動テンプレート reference/preview-template.html が同梱されています — 洗練されたデザインシステムのショーケースページです: スティッキーナビ(ブランドワードマーク + github.com/ake77-code/distill-design にリンクする distill-design GitHub チップ + セクションアンカー + ライト/ダーク切り替え + CTA)、2 カラムのヒーロー(Design System Analysis of <displayName> + description + デバイスモックカード)、続いて 番号付きセクション ("01 — Color Palette"、"02 — Typography Scale"、"03 — Components"、"04 — Spacing & Radius"、"05 — Elevation & Depth"、"06 — Responsive Behavior")がグループ化されたスウォッチカード、タイプラダー、コンポーネントギャラリー、spacing/radius ブロック、ブレークポイント表をレンダリングします。フッターはありません。依存関係ゼロ(システムフォント、CDN なし)。

ブランドの preview.html を生成するには:

1. reference/preview-template.html をそのまま <output>/preview.html にコピーします。
2. <script type="application/json" id="design-data"> 内の JSON だけ を、DESIGN.md から導出したブランドのトークンに置き換えます。それ以外は何も変更しないでください — シェル、CSS、レンダラーはブランド間でバイト単位で同一のままです。 テンプレート内のそのブロックの上にあるコメントを参照してください。インジェクトされる JSON スキーマ:

• meta: { name, displayName, description, source, nativeTheme: "light"|"dark", navCta, heroCtas, sections? }。name は実際のブランド名です。ヒーローには「Design System Analysis of displayName」と表示されるため、displayName には実際のブランド名 (例: "Apple"、"Stripe"、"Figma") を設定してください。架空の製品名をでっち上げないでください。URL が属する実際の ブランドを使用してください。description は frontmatter の description をそのまま記述したもの、source は実際の URL、nativeTheme は ブランドの極性 (Linear などでは dark) です。任意の navCta (ナビボタンのラベル、例: "Buy" / "Get started") と heroCtas ["Learn more","Buy"] は、ブランドの CTA 文言を設定します。任意の heroArt は、シグネチャーとなるモチーフに合わせてヒーロービジュアルを選択します: device (デフォルトの製品モック)、mesh (グラデーションメッシュの塗り — Stripe のようなブランド)、または glow (ダークグロー — Linear のようなブランド)。任意の sections = { colors:{heading,intro}, typography:{...}, components:{...} } は、各セクションにブランドの声による見出し/intro (例: "One blue. Three near-blacks.") を付与します。これは対応する DESIGN.md 本文セクションから取得されます。省略するとデフォルトになります。
• colors: ロール→hex のフラットなパレット (rgba 文字列も可)。すべてのロールは スウォッチとして描画され、自動的にグループ化されます (Brand & Accent / Surface / Text / Hairlines & Borders / Semantic)。
• colorRoles (任意、推奨): { role: "one-line description" } — DESIGN.md の Colors セクションにある 色ごとの使用上の注意です。スウォッチの 3 行目として表示されるため、 カードがリファレンスと同じ深さに一致します。colorNames (任意): { role: "Friendly Name" } → "role (Friendly Name)" として描画されます。
• colorsDark: 任意 の反対極性のオーバーライド (指定しない場合、dark は自動生成されます)。
• typography: ロール→{ fontFamily, fontSize, fontWeight, lineHeight, letterSpacing }。
• rounded、spacing: トークン→値のマップ。
• components: ロール→{ backgroundColor, textColor, typography, rounded, padding, border, height, size }。値には {group.token} 参照 (レンダラーによって解決されます) を使用できるため、各 ギャラリーサンプルが実際のコンポーネントスタイルで描画されます。
• responsive (任意): DESIGN.md の Responsive Behavior セクションにある { breakpoints:[{name,width,changes}], touchTargets, collapsing, imageBehavior } — 「06 — Responsive Behavior」を制御します。キー全体を省略すると、このセクションは非表示になります。

テンプレートはすでにナビ、ヒーロー、番号付きセクション、スウォッチのグループ化、 タイプラダー、コンポーネントギャラリー、スペーシング/ラディウス/エレベーションのブロック、レスポンシブ ブレークポイントの表、および ライト/ダークトグル (localStorage) を提供しています。ナビのワードマークにはブランド名 (サードパーティのブランドではありません) が表示され、GitHub チップには distill-design と表示され、 github.com/ake77-code/distill-design を指します。 データをインジェクトした後、スタンドアロン (file://) で開けること、およびブランドの色で 洗練されたデザインシステム分析ページとして視覚的に読めることを確認してください。ピクセルレベルのリファレンスについては、 awesome-design-md プロジェクトが各ブランドを getdesign.md/design-md/<brand>/preview.html で描画しています。

リアルなデモ demo.html を生成する（リクエストに応じて）

目標: 外部依存が一切ない単一の .html ファイル（すべての CSS/JS をインライン化、CDN なし、ネットワークリクエストなし — システム/-apple-system のフォントスタックのみ）で、トークンのカタログではなく本物の製品のように読めるものを作ることです。これは preview.html とは異なります: preview.html はシステムを文書化するものであり、デモはそれを使って説得力のあるページを実際に出荷します。

完全なレシピは reference/demo-guide.md をお読みください。要約すると:

1. 不明な場合はフォームファクターを確認してください: Web（レスポンシブなランディングページ）または Mobile（スマートフォンのフレームに収めたアプリ画面）。デフォルトは Web です。
2. トークンから本物のページを構築する — すべての色、フォント、角丸、間隔、シャドウ、コンポーネントを DESIGN.md からそのまま取得します:
   • Web: スティッキーナビ → ヒーロー（見出し + サブ + プライマリ/セカンダリ CTA）→ ソーシャルプルーフのロゴ → 3 列の機能カード → 料金プラン → testimonial → CTA バンド → フッター。
   • Mobile: スマートフォンのフレーム（ステータスバー、ノッチ）で本物のアプリ画面を包みます — トップバー、コンテンツリスト/フィード/カード、そしてボトムタブバーまたは再生中/スティッキー CTA。
3. リアルに感じさせる — もっともらしいコピーと製品名、ブランドのシグネチャーモチーフ（例: グラデーションメッシュ、グローのはみ出し線、緑の再生ボタン）、インライン SVG/CSS グラデーションによるリアルな画像（外部画像を絶対にホットリンクしないこと）、そして小さなインライン <script> によるセンスの良いホバー/スクロールのマイクロインタラクション。
4. 保存 仕様の隣に demo.html（または demo-mobile.html）として保存します。
5. 検証 単体で開けること（ダブルクリック / file://）、コンソールエラーがないこと、そしてブランドの言語で本物のサイトのように見えることを確認します。

検証

# YAML frontmatter parses (frontmatter is between the first two '---' lines)
python3 - "$f" <<'PY'
import sys, yaml
t = open(sys.argv[1]).read().split('---', 2)
yaml.safe_load(t[1]); print("frontmatter OK")
PY

次に、最もよくある 2 つのミスについて仕様を grep してください — どちらも何も返さないはずです:

grep -nE '^\s+[a-z0-9-]*-hover:' "$f"   # no hover-STATE component keys (prose ok)
grep -c '^## ' "$f"                     # must be 11 (Overview … Known Gaps)

preview.html または demo.html を生成した場合は、ブラウザで開くか、ブラウザ MCP でスクリーンショットを撮り、ブランドの言語でレンダリングされることを確認してください。

注意事項

• フォルダ名は小文字で URL セーフにしてください（stripe、together.ai）。
• name: は <Brand>-design-analysis です。値が公式に認められたものではなく解釈されたもの（WebFetch のみ、CSS の実測なし）である場合は、Colors のソースページの注記と ## Known Gaps セクションにその旨を記載してください — 精度を捏造しないでください。
• 1 フォルダにつき 1 ブランド。状態のバリアントは個別のコンポーネントキーとして文書化してください。ホバーは決して含めないでください。