distill

stardust:distill

ユーザーが提供したデザインサンプルのディレクトリを読み込みます。対象は、ユーザーが samples/static/ 配下に配置した静的 HTML ファイルと、取得対象のライブ URL を記載した samples/live/urls.json マニフェストです。そして、stardust パイプラインの基盤となる次の 2 つの成果物を作成します。

1. samples/trait-matrix.json — サンプルごと、およびサンプル間の特性データを構造化したもの（タイプシステム、カラー、間隔、モーション、コンポーネントパターン、トーン、アセット）。
2. samples/SAMPLES.md — 物語形式でまとめた語彙のブリーフです。stardust:direct が Mode B で、解決済みのアンカーセットとして読み込みます。

このスキルは記述的であり、事前抽出を行います。オリジンをクロールすることはありません（それは extract の役割です）。デザイン上の意見を独自に作り出すこともありません（それは direct の役割です）。特定のビジュアル言語に stardust を従わせたい場合に、ユーザーが Mode B のアンカー参照として direct に渡すブリーフを作成します。このビジュアル言語はサンプルから取り込まれたもので、サンプルがない状態から方向性を決める必要がなくなります。

サンプルがないユーザーは distill を省略して、extract に進めます。ブランドチーム、デザイナー、アートディレクターから、既存サイトとは異なる特定のリファレンス素材を尊重するよう指示された場合、distill は重要な役割を果たします（よくあるケースは、デザイン責任者がビジュアルの方向性を事前に決めており、HTML とスクリーンショットのフォルダーが渡されるリフレッシュです）。

入力

• <samples-dir> — 省略可能な位置引数です。デフォルトは samples/ です。
• --from-static — 静的サンプルのみを distill し、ライブ取得をスキップします。ライブ URL が記載されていない場合や、ライブの処理を後回しにしたい場合に使用します。
• --from-live — ライブサンプルのみを distill し、静的解析をスキップします。静的処理がすでに実行されており、ライブスナップショットのみを更新する必要がある場合に使用します。
• --cap <N> — 取得するライブ URL の上限です（デフォルトは 8）。extract の少数サンプル方針に沿っており、ほぼ重複するサンプルに予算を費やすことなく、ビジュアル言語を見極めるには 8 件の参照 URL で十分です。
• --refresh — samples/live/snapshots/ 配下にキャッシュ済みのスナップショットがある場合も、すべてのサンプルを再取得して再解析します。デフォルトではキャッシュ済みのスナップショットを再利用し、未取得の URL のみを取得します。

セットアップ

最初に、マスタースキルのセットアップ手順を実行します （skills/stardust/SKILL.md § Setup）：依存関係の厳密なチェック、コンテキストローダー、状態の読み込み。

このサブコマンドでは、さらに次のチェックを行います。

1. Playwright の利用可否 — extract と同じ依存関係チェックです。ライブ処理には実際のブラウザーが必要です。次の順に Playwright を検出します。まず Playwright MCP サーバー、次に npx playwright。どちらも利用できず、--from-static も指定されていない場合は停止し、Playwright のインストール方法をユーザーに伝えます。
2. サンプルディレクトリの構造 — 入力ディレクトリが存在し、static/<sample>/ または live/urls.json のいずれかが少なくとも 1 つ含まれていることを確認します。どちらもない場合は停止し、期待されるディレクトリ構成を説明します。

   samples/
     static/
       <sample-1>/
         index.html         (or any .html file)
         assets/            (optional; reused if present)
       <sample-2>/
         ...
     live/
       urls.json            (array of { url, slug?, role? } objects)
   

3. 状態の優先順位 — stardust/state.json に samples.distilledAt のタイムスタンプがすでに記録されており、--refresh が指定されていない場合は、上書きして再度 distill するか、スキップするかをユーザーに確認します。distill は冪等です。再実行すると、以前のブリーフと特性マトリックスが上書きされます。

手順

フェーズ 1 — 静的サンプルの一覧作成

samples/static/ の各サブディレクトリについて、次の手順を実行します。

1. エントリー HTML ファイルを特定します（index.html があればそれを使用し、なければサイズが最大の .html ファイルを使用します）。
2. ファイルと、参照されているスタイルシートを読み込みます（インラインの <style> と、サンプルディレクトリを基準に解決したリンク先の <link rel="stylesheet"> の両方を対象とします。対象には samples/static/<sample>/... と、同階層の assets/ ディレクトリが含まれます）。
3. スクリーンショットまたは PDF がサンプルディレクトリ内にある場合は、そのパスを記録します。レビュー担当者が解析された特性と比較するときに使用できます。
4. メモリ内の一覧に次のエントリーを記録します。 { slug, kind: "static", entryHtml, stylesheets[], screenshot?, role? }。role は、存在する場合、ディレクトリ名から推定します（bizpro-hub-prototype → business、plan-page → pricing など）。推定結果を保存し、ユーザーに提示して修正してもらいます。

フェーズ 2 — ライブサンプルを取得する

live/urls.json が存在し、--from-static が渡されていない場合：

1. マニフェストを読み込みます。各エントリーは { url, slug?, role? } です。slug がない場合は、URL のホスト名とパスから自動生成します。
2. 各 URL について（--cap による上限あり）：
   • キャッシュを確認します。live/snapshots/<slug>.html と .png が存在し、--refresh が渡されていない場合は、取得をスキップしてキャッシュされたペアを使用します。
   • それ以外の場合は、extract の playwright-recipe.md に従って Playwright でレンダリングします。ビューポートは 1440 × 900 @ 2× DPR、待機モードは medium、モーションの低減を有効にし、ページ最下部までスクロールしてから、DOM 全体とページ全体のスクリーンショットをキャプチャします。
   • 次を保存します：
     • live/snapshots/<slug>.html（レンダリング済み DOM）
     • live/snapshots/<slug>.png（ページ全体のスクリーンショット）
     • live/snapshots/<slug>.log（出所を示す 1 行の情報： { url, fetchedAt, waitMs, status }）
3. インベントリに次のエントリーを記録します： { slug, kind: "live", url, snapshotHtml, snapshotPng, snapshotLog, role? }。

フェーズ 3 — サンプルごとの特性抽出

インベントリ内の各エントリーについて、HTML と計算済みスタイルを解析します（代表的な要素に対して getComputedStyle() を使用するヘッドレスブラウザーの処理を実行します。extract のセクションごとのスタイル要約と同じ手法です）。 サンプルごとに次を抽出します：

• タイポグラフィシステム — --*font-*、--*type-* に一致する名前付き CSS 変数すべてと、すべての見出し、本文の段落、ボタン、アイブロウ、リンクの計算済みスタイル。次の形式に集約します： { headingFamily, bodyFamily, labelFamily, weights[], scale: { title-1, title-2, ..., body-lg, body-sm, eyebrow, label }, rules[] }。extract/reference/brand-surface.md § Modular-scale audit に従ってモジュラースケールを検出します。
• 色 — --*color-*、--*bg-*、--*surface-*、--*text-* に一致する名前付き CSS 変数すべてと、代表的な要素の計算済み background-color および color。次の形式に集約します： { palette: { neutrals[], brand: {}, surfaces: {} }, reservations: [{ color, reservedFor[] }], rules[] }。 reservedFor リストは、クラス名と CSS セレクターから推定します（例：.brand-mnemonic ⇒ reservedFor: ["brand-mnemonic"]）。
• スペーシング — --*space-*、--*spacing-*、--*pad-*、--*gap-* に一致する名前付き CSS 変数すべて。intent-dimensions.md § 4 に従って、セクションのパディング値をクラスタリングし、密度の段階（compact / balanced / packed）を検出します。
• 角丸／シャドウ／モーションのトークン — --*radius-*、--*shadow-*、--*ease-*、--*duration-*、--*motion-* に一致する名前付き CSS 変数すべて。
• モーションスタック — <script src=> の検査によって読み込まれたライブラリを検出します：GSAP、ScrollTrigger、Lenis、Locomotive、Three.js、Splide、Swiper。URL からバージョンを読み取れる場合は記録します。animation-timeline:、@keyframes、transition: を検索し、CSS のみで実装されたモーションパターンを検出します。次を記録します：

  {
    libraries: [{ name, version?, role }],
    cssOnlyPatterns: ["animation-timeline: view(block)", ...],
    choreographies: [{ name, surface, mechanism, capturedFrom }]
  }
  

• コンポーネントパターン — 繰り返される DOM の構造を検出します：カードグリッド、バナー、ナビゲーションの構成、ヒーローの構成。extract/reference/brand-surface.md § System components に従います。各パターンについて、{ kind, shape, instanceCount, examples[] } を記録します。examples には、キャプチャした構造を直接把握できるだけのマークアップスニペットを含めます。
• 文体サンプル — ヒーローの見出し、最初の本文段落、代表的な CTA 3 件、ナビゲーションラベル 3 件、フッターの文言。フィールドは extract の voice ブロックと同じです。異なる点は、ここでは文体をサンプルごとに記録することです（サンプルごとに文体のレジスターが異なる場合があるため、サンプル間では集約しません）。
• アセットインベントリ — フォント（@font-face 宣言とその src URL）、画像（固有の寸法を含む）、インライン SVG。サンプルごとに記録し、アクセス可能な場合はローカルにキャッシュします。

サンプルごとのデータを、特性マトリックスの samples[] 配列に保存します。

フェーズ 4 — サンプル横断の集約

サンプルごとのデータを確認し、sharedTokens ブロックを生成します。トークンが「共有」されているのは、同じ値を持つサンプルが少なくとも ceil(N/2) 件ある場合です（色については、近似重複のクラスタリング後に判定します）。それ以外は、サンプルごとの内訳とともに divergentTraits に入れます。

集約する項目：

• sharedTokens.type — 繰り返し現れるタイプファミリー、ウェイト、スケール。
• sharedTokens.color — 繰り返し現れるニュートラルカラー、ブランドカラー、サーフェストークン。予約項目は統合します（1つのサンプルで予約されていれば、その予約を尊重します）。
• sharedTokens.spacing — 繰り返し現れるセクションのパディングとグリッド。
• sharedTokens.radius / shadow / easing / duration — モーダル値。
• sharedTokens.motionStack — 1つ以上のサンプルで読み込まれたライブラリ（モーションは任意であり、多数決では決まりません）。
• divergentTraits — 多数決のしきい値に達しなかった項目。direct はこれを参照し、B/C/... バリアントでどの特性を強調するかを判断します（「captured trait amplified」の役割）。

フェーズ 5 — SAMPLES.md を作成する（ナラティブブリーフ）

SAMPLES.md は、direct が Mode B で参照する重要な成果物です。書式は reference/samples-brief-format.md に従います。

• 出典ヘッダー（HTML コメントを1行目に記載） — 他のすべての stardust 成果物の出典ブロックと同じ形式です。writtenBy、writtenAt、readArtifacts、samples、stardustRole を含めます。
• 冒頭の段落 — サンプルセットを参照ファミリーとして位置付ける段落です。共有されるデザイン言語、サンプルごとの表現、そしてこのブリーフの利用者（direct、Phase 2 Mode B）を明記します。
• § 1 タイプシステム — 共有スケールの表、ルールのブロック、検出された場合は fluid clamp() の式。
• § 2 色 — スウォッチ付きの表によるパレット、予約項目のリスト、ブランドに忠実な反転候補（direct/reference/direction-format.md の § Brand-faithful inversions に従います）。
• § 3 スペーシング＋グリッド＋密度ティア。
• § 4 モーションスタック＋振り付け — バージョン付きライブラリ一覧、名前付きの振り付け（hero scroll-grow、garage-door など）。仕組みと、どのサンプルから取得したかを記載します。
• § 5 コンポーネントパターン — カード、バナー、ナビゲーション、ヒーロー構成。各パターンにつき、形状の概要を1つ記載します。
• § 6 表現ごとの語り口 — サンプルごとの語り口ブロック（集約しません）。direct は、B/C バリアントの表現を合わせるために、サンプルごとの語り口を使用します。
• § 7 アセット一覧 — フォント（ライセンスフラグ付き）、写真とイラストの比率、特徴的なモチーフ。
• § 8 発散する特性 — direct が、B/C バリアントで強調する特性を選ぶ際に使用するリスト。

直接作成してください。蒸留には impeccable の作成手順に厳密に従う必要はありません。SAMPLES.md はデザイン上の意見ではなく、事実に基づく入力として direct に利用されます。

フェーズ 6 — 状態を更新して報告する

すべてのフェーズが正常に完了したら：

1. stardust/state.json を更新します（存在しない場合は samples ブロックを追加します）。

   "samples": {
     "distilledAt": "<ISO-8601>",
     "samplesDir": "samples/",
     "brief": "samples/SAMPLES.md",
     "traitMatrix": "samples/trait-matrix.json",
     "inventory": [
       { "slug": "bizpro-hub", "kind": "static", "role": "business" },
       { "slug": "sr-homepage", "kind": "live", "url": "...", "role": "consumer-creative" },
       ...
     ]
   }
   

2. 1画面に収まる要約を出力します。

   Distilled 3 samples (2 static, 1 live)
   
   samples/
     SAMPLES.md             (8 sections, 4 motion choreographies named)
     trait-matrix.json      (12 shared tokens, 4 divergent traits)
     live/snapshots/        (1 file)
   
   Per-sample evidence:
     slug          kind     role                 typeFam               motion-libs
     bizpro-hub    static   business             adobe-clean-display   Lenis 1.x, GSAP 3
     plan-page     static   pricing              adobe-clean-display   Lenis 1.x
     sr-homepage   live     consumer-creative    adobe-clean-display   Lenis 1.x, GSAP 3
   
   Shared tokens: type (12), color (8), spacing (10), motion (2 libs)
   Divergent traits (amplification candidates):
     - scroll-driven choreography (bizpro-hub strongest)
     - photography-led tile vocabulary (sr-homepage strongest)
     - pricing-tier card density (plan-page strongest)
   
   Next: $stardust direct "<phrase referencing SAMPLES.md>" --variants 3
   

distill が実行される場合と実行されない場合

distill は任意です。一般的なシナリオは次の 3 つです。

1. サンプルなしで、更新のみを行う場合。 ユーザーが $stardust extract → $stardust direct を直接実行します。Mode A（ブランド忠実型）が 一般的なケースに対応します。パレットと書体はキャプチャした サイトに固定され、バリアントではキャプチャした画面の範囲内で 表現性／密度／モーションの各軸を探索します。distill は実行されません。
2. サンプルがあり、ブランド忠実型の更新を行う場合。 ユーザーはまず distill、 次に extract を実行し、その後 direct "<phrase referencing SAMPLES.md>" を 実行します。Mode B のアンカー参照の優先順位（direct/SKILL.md の § Mode B に記載）に従い、SAMPLES.md を解決済みアンカーセットとして 読み込みます。これらの軸ではキャプチャしたブランドが優先されるため、 Mode A のパレットと書体の継承も引き続き適用されます。蒸留結果は ブランド以外の軸、つまりモーションスタック、コンポーネントの形状、 密度の段階、振り付けの名称に反映されます。
3. サンプルセットからリブランドする場合。 ユーザーは distill と direct --rebrand "<phrase>" を実行します。蒸留結果によって、 パレット、書体、モーションの表現がすべて決まります。extract で キャプチャした画面は情報アーキテクチャとコンテンツにのみ 使用されます。これは最もまれなケースですが、distill はもともと この用途のために作られました。

ユーザーが用意する入力（このスキルの対象外）

distill は、ユーザーが手作業で組み立てたディレクトリを使用します。サンプルの 一般的な入手元は次のとおりです。

• デザイナーが作成した静的 HTML モック（ブラウザーで開き、ページ全体を保存）。
• ブランドチームから提供されたライブ URL。これらを samples/live/urls.json に記載すると、distill が取得します。
• HTML に変換した印刷用 PDF／Figma エクスポート（可能な範囲で対応）。

distill はユーザーに代わってサンプルを選定しません。サンプルの入手元を 考案することも、ユーザーがリストに記載していない任意の URL を 取得することもありません。サンプルに誤りがあれば、ブリーフにも誤りが 生じます。これは意図的な仕様です。distill は忠実な記述ツールであり、 選定ツールではありません。

来歴

distill が書き込むすべての成果物には、最低限、次の内容を含む来歴ブロックが 記録されます。writtenBy: stardust:distill、writtenAt: <ISO-8601>、 readArtifacts: [...]（読み込んだすべてのサンプルファイル）、 consumedBy: "stardust:direct — Mode B anchor resolution"。

参考資料

• reference/samples-brief-format.md — SAMPLES.md の出力に使用するナラティブブリーフの形式。
• reference/trait-matrix-schema.md — trait-matrix.json の出力に使用する、サンプルごとおよびサンプル横断のスキーマ。