style-extractor

スタイル抽出（Web スタイル＋モーション）

Web UIから再利用可能なデザインシステムを抽出します。色、タイポグラフィ、間隔、コンポーネント、状態、および該当する場合はモーション（タイミング、キーフレーム、遅延チェーン、JS による動作）が対象です。

基本原則：

• 抽出するのは、元の製品の情報アーキテクチャではなく、ビジュアル言語とインタラクションのルールです。
• 再利用可能な要素を残します。トークン、コンポーネントのパターン、状態の変化、レイアウトの傾向、モーションのリズムが該当します。
• 製品固有の要素は取り除きます。ビジネス向けの文言、アプリのロジック、ナビゲーションツリー、機能の分類、マーケティング上の主張が該当します。

出力先（必須）

• 生成したすべての成果物を %USERPROFILE%\\style-extractor\\ 以下に保存します。
• 生成物をスキルフォルダー（.codex/skills/...）以下に書き込んではいけません。
• スクリーンショット、CSS、JS、Markdown を出力ルートディレクトリに混在させてはいけません。

抽出ごとに、専用のプロジェクトフォルダーを作成します。

%USERPROFILE%\style-extractor\
  <project>-<style>\
    guides\
      style-guide.md
      motion-guide.md
      evidence-manifest.md
    evidence\
      screenshots\
      assets\
      notes\

抽出ごとに必須の成果物：

• %USERPROFILE%\\style-extractor\\<project>-<style>\\guides\\style-guide.md
• %USERPROFILE%\\style-extractor\\<project>-<style>\\guides\\evidence-manifest.md
• %USERPROFILE%\\style-extractor\\<project>-<style>\\evidence\\

モーションが重要な場合に必須：

• %USERPROFILE%\\style-extractor\\<project>-<style>\\guides\\motion-guide.md

サブディレクトリのルール：

• guides/ には最終版の Markdown 成果物のみを格納します。
• evidence/screenshots/ には PNG/JPG/WebP のキャプチャのみを格納します。
• evidence/assets/ にはダウンロードした CSS/JS/SVG/フォントのスタイルシートのみを格納します。
• evidence/notes/ には生のダンプ、実行時メモ、トレース、補助テキストファイルのみを格納します。
• プロジェクトのルートフォルダーにはフォルダーのみを置きます。単独のスクリーンショットやガイドファイルを置いてはいけません。

次の参考ファイルを使用します。

• references/output-contract.md — 必須の出力構成とアンチパターン
• references/style-guide-template.md — スタイルガイドに必須のセクション
• references/motion-guide-template.md — モーション付録に必須のセクション
• references/evidence-manifest-template.md — エビデンスマニフェストに必須のセクション

参考資料（品質基準）

• references/9nine-visual-novel/ — スタイルとモーションのベストプラクティスを示す参考パッケージ
• references/motherduck-design-system-reference/ — 静的スタイルの優れた参考パッケージ

これらの参考資料から学ぶこと：

• 実用的なリファレンスマニュアルとして使える、十分な密度のドキュメントにします。
• 代表的な実測値を含む、意味づけされたトークンテーブルを維持します。
• 具体的に観測された値を含む、コンポーネントの状態マトリクスを維持します。
• 再利用に大きく役立つ場合は、コピーして使える例や実践的な実装メモを残します。

そのままコピーしないこと：

• 汎用的な説明の繰り返しや、製品紹介の長文
• 意味ごとに整理されていない実測値の羅列
• 製品固有のブランディングや情報アーキテクチャの詳細の過剰な記載
• 再利用価値を加えることなく、ドキュメントを長く見せるためだけのセクション

参考資料の必須精読（必須）

抽出を開始する前に、次の順序で読みます。

1. references/output-contract.md
2. references/style-guide-template.md
3. references/motion-guide-template.md
4. references/evidence-manifest-template.md
5. references/9nine-visual-novel/guides/ 以下のすべてのファイル
6. references/motherduck-design-system-reference/guides/ 以下のすべてのファイル

参考パッケージの選択ルール：

• モーション主体、メディア主体、またはセクション遷移主体のソース → references/9nine-visual-novel/ を主な品質基準として使用します。
• 静的構造主体のソース → references/motherduck-design-system-reference/ を読みます。

両方の参考パッケージを確認するまで、エビデンスの収集、スクリーンショットの撮影、スクリプトの実行、ドキュメントの下書きを開始してはいけません。 最終成果物には、次の内容が明記されていなければ抽出は未完了です。

• 抽出を始める前に両方の参考パッケージを確認したこと
• 対象に対して主な品質基準として使用したパッケージ

---

ワークフロー

Phase 0 — 入力

1. プロジェクト名 + スタイル／バリアント名
2. ソース：URL／Web リポジトリ／両方
3. モーションの評価：サイトに意味のあるモーションがあるか（Phase 1B が必要かどうかを決定します）
4. 再利用先：Web アプリ／マーケティングサイト／デスクトップアプリ／デザインの参考のみ
5. 選択した主要リファレンスパッケージ：9nine／MotherDuck

証拠を収集する前に、ソースの特徴のうち、再利用可能なスタイルに含めるものと除外するものを決めます。次の簡単な基準を使ってください。

• 残す：トークン、間隔のリズム、タイポグラフィの階層、密度、コンポーネントの表現、状態の扱い、モーションのテンポ
• 慎重に調整する：レイアウトの基本要素、パネル構成、ナビゲーションパターン、コンテンツ密度
• 除外する：製品のコピー、機能固有のフロー、ブランドストーリー、アプリ固有の情報アーキテクチャ、ドメイン固有のラベル

Phase 0.5 — リファレンスパッケージを読む（必須）

Phase 1A の前に、以下をすべて完了してください。

• references/output-contract.md を読む
• references/style-guide-template.md を読む
• references/motion-guide-template.md を読む
• references/evidence-manifest-template.md を読む
• references/9nine-visual-novel/guides/style-guide.md を読む
• references/9nine-visual-novel/guides/motion-guide.md を読む
• references/9nine-visual-novel/guides/evidence-manifest.md を読む
• references/motherduck-design-system-reference/guides/style-guide.md を読む
• references/motherduck-design-system-reference/guides/motion-guide.md を読む
• references/motherduck-design-system-reference/guides/evidence-manifest.md を読む
• 現在の抽出作業における主要な品質基準として、2 つのパッケージのいずれかを選ぶ

両方のパッケージを先に読んでいない場合、抽出結果は無効です。

Phase 1A — 静的証拠の収集

Step 1 — ページを開いてスクリーンショットを撮る

Chrome MCP ツールを使用します。

• new_page / select_page / navigate_page
• take_screenshot（役立つ場合は fullPage）

最低限必要なスクリーンショット：

1. ベースライン（ページ全体／セクション全体）
2. ナビゲーションが表示された状態 + アクティブ状態
3. 主要な CTA：デフォルト + ホバー + 押下（可能な場合）
4. フォームコントロール：デフォルト + フォーカス可視状態（無効状態があればそれも）
5. モーダル／ダイアログを開いた状態（ある場合）

Step 2 — 計算済みスタイルを抽出する

evaluate_script を使って、次の情報を取得します。

• CSS 変数（:root およびスコープ付き）
• getComputedStyle から色、タイポグラフィ、間隔
• コンポーネントの状態マトリクス（デフォルト／ホバー／アクティブ／フォーカス可視／無効）

Step 3 — CSS／JS の本体を取得する

• list_network_requests / get_network_request を使って CSS ファイルをダウンロードします
• オフラインでの @keyframes、CSS 変数、メディアクエリの抽出に役立ちます

...\\evidence\\ に保存する静的証拠の最低限：

• evidence/screenshots/ にスクリーンショット
• evidence/assets/ にダウンロードした CSS／JS
• evidence/notes/ にメモとセレクター一覧

---

Phase 1B — モーションの証拠を収集する（サイトに意味のあるモーションがある場合）

静的証拠の収集とモーションの証拠収集は独立した手順です。サイトに意味のあるアニメーションがなければ、このフェーズをスキップしてください。

以下の手順を優先順位順に実行します。各レベルで取得できる情報が増えるため、十分な証拠が得られた時点で停止してください。

Level 1 — @keyframes の抽出（操作不要）

scripts/transition-scanner.js を貼り付けてから、次を呼び出します。

__seTransition.keyframes()

スタイルシートからすべての @keyframes 定義を返します。決定的かつ完全で、タイミングに関する問題はありません。

Level 2 — CSS transition のスキャン（操作不要）

同じスクリプトで、次を呼び出します。

__seTransition.scan()            // scan entire page
__seTransition.scan('.my-section') // scan specific section

すべての要素について、transition-property / duration / easing / delay とパターンごとのクラスターを返します。まだアニメーションが発生していない場合でも、アニメーション可能な対象がわかります。

レベル 3 — インタラクション差分（インタラクションのトリガーが必要）

現在のサイトで主流のパターンを取得します。JS がインラインスタイルを設定 → CSS トランジションが補間します。

scripts/interaction-diff.js を貼り付けてから、次を実行します。

// 1. Watch elements you care about
__seDiff.watch([
  '[class*="sectionContainer"]',
  '[class*="illustration"]',
  '[class*="navItem"]',
  'button, a[class*="cta"], a[class*="CTA"]'
])

// 2. Trigger interaction and capture diff
__seDiff.triggerAndCapture(
  () => document.querySelector('.nav-item-2').click(),
  { captureAt: 50, settleAt: 500 }
)

次の情報が返されます。

• diffs — 要素ごとの、インラインスタイルと計算済みスタイルの変更前後の差分
• duringAnimations — 50ms のトランジション期間内に取得した document.getAnimations()
• afterAnimations — 静止後も実行中のもの

重要なポイント：document.getAnimations() は、CSS トランジションの実行中にのみ結果を返します。通常、取得可能な時間は 300ms 未満です。このスクリプトはその時間内に自動的に取得します。

主要なインタラクション（セクション変更、コンポーネント切り替え、ホバー、スクロールなど）で 3 回以上繰り返します。

レベル 4 — JS ライブラリの抽出

scripts/library-detect.js を貼り付けて、サードパーティのアニメーションライブラリを検出します。

{ globals, instances, dom, fingerprints, assets } が返されます。

重要な点：現在の多くのサイトではライブラリがモジュールとしてバンドルされているため、window.Swiper などが undefined の場合があります。このスクリプトでは、次の項目も確認します。

• el.swiper — DOM 要素上の Swiper インスタンス（バンドル時も機能）
• [data-aos-*] — 要素上の AOS 属性
• [data-framer-*] — Framer Motion 属性
• アセット URL のヒント（ライブラリ名を含むスクリプト／スタイルシートの URL）

インスタンスが見つかった場合、設定を直接抽出します（Swiper のパラメーター、AOS の設定など）。

レベル 5 — rAF サンプリング（不透明な JS モーションのフォールバック）

上記のレベルで十分に取得できない場合（例：手書きの requestAnimationFrame ループ）、scripts/motion-tools.js を使用します。

__seMotion.sample('.animated-element', { durationMs: 800, include: ['transform', 'opacity'] })

フレームごとに計算済みスタイルの値を記録します。持続時間やプロパティの範囲を推定するのに役立ちますが、イージングや意図は取得できません。

レベル 6 — パフォーマンストレース（任意、複雑なモーション向け）

非常に複雑な連動アニメーションの場合：

• performance_start_trace / performance_stop_trace
• performance_analyze_insight で分析します

---

フェーズ 2 — 抽象化と製品要素の排除（必須）

ガイドを特定の製品の分析として書かないでください。得られた証拠を再利用可能なルールに変換します。

主な発見事項ごとに、次のように明示的に分類します。

• Reusable：トークン、コンポーネントのルール、状態のルール、またはモーションプリミティブとしてそのままコピーできます
• Adapted：参考になるアイデアですが、対象製品の種類に合わせて再構成する必要があります
• Discarded：コピーすべきではない、ソース固有の構成やコンテンツです

例：

• クラウドブルーのサーフェスパレット：Reusable
• ドキュメントのサイドバー＋記事レールのレイアウト：Adapted
• AI チャットアプリのプロンプトライブラリの情報設計：Discarded
• 背景動画を使ったマーケティング用ヒーロー：対象によって Adapted または Discarded

フェーズ 3 — セマンティックトークン化（必須）

生の値だけで終わらせないでください。繰り返し使われる値をセマンティックトークンに変換します。

1. 繰り返し使われる値を分類する（色／角丸／時間／イージング／シャドウ）
2. 用途を対応付ける（CTA／テキスト／境界線／オーバーレイ／アクティブ状態など）
3. 意図に基づいて命名する（例：--color-accent、--motion-300、nav.switch.iconColor）
4. トークンとともに根拠を残す（生の値＋要素／セレクター／スクリーンショット）

フェーズ 4 — 成果物を作成する

参照テンプレートを使用してください。ソースで明らかに別の構成が必要な場合を除き、最上位の構成を独自に変更しないでください。

成果物 A — スタイルガイド（必須）

references/style-guide-template.md に従ってください。

このファイルでは、次の点に答える必要があります。

• スタイルからどのような印象を受けるか
• どのトークンがスタイルを定義するか
• コンポーネントが各状態でどのように振る舞うか
• 再利用できるレイアウトの傾向は何か
• 製品そのものをコピーせずに、ビジュアル言語をどのように再構築するか

成果物 B — モーションガイド（動きがある場合は必須）

references/motion-guide-template.md に従ってください。

このファイルでは、次の点に答える必要があります。

• 何が動くか
• 何がモーションをトリガーするか
• 持続時間、遅延、イージング、キーフレーム
• モーションが CSS、トランジション、または JS／ライブラリによって制御されるか
• 別の製品でも再利用できるモーションプリミティブは何か

成果物 C — エビデンスマニフェスト (必須)

references/evidence-manifest-template.md に従ってください。

含めるもの:

• ソース URL / リポジトリ参照 / 取得日
• スクリーンショット一覧
• ダウンロードした CSS/JS ファイルまたはメモ
• 使用したスクリプト
• テストしたインタラクション
• ギャップ、ブロッカー、確信度に関するメモ
• レビューした参照パッケージと、抽出前に読み込んだパッケージファイル

コンポーネント状態マトリクスには少なくとも以下を含める必要があります:

• default / hover / active(pressed) / focus-visible / disabled
• それらの状態が存在する場合は loading / selected / invalid も含める

---

スクリプトリファレンス

スクリプト	名前空間	目的
scripts/transition-scanner.js	__seTransition	CSS トランジションをスキャン + @keyframes を抽出
scripts/interaction-diff.js	__seDiff	インラインスタイルの変更前後差分 + getAnimations の即時取得
scripts/motion-tools.js	__seMotion	getAnimations スナップショット + rAF サンプリング
scripts/library-detect.js	(直接返す)	ライブラリ検出 + インスタンス設定の抽出
scripts/extract-keyframes.py	CLI	ダウンロードした CSS ファイルからのオフライン @keyframes 抽出

---

品質チェックリスト

静的

• トークンに使用意図が含まれている (単なるリストではない)
• サンプルはコピー&ペースト可能 (HTML+CSS)
• コピー&ペースト可能なコンポーネント例が 5 つ以上
• 再利用する / 改変する / 破棄するソースの特徴が明記されている
• 製品固有の IA/コピーが最終ガイドから除去されている

モーション (動的な場合)

• すべての @keyframes がスタイルシートから抽出されている (レベル 1)
• CSS トランジションパターンが duration/easing とともに文書化されている (レベル 2)
• 変更前後の差分エビデンスを伴う主要なインタラクションが 3 つ以上 (レベル 3)
• JS ライブラリが検出され、存在する場合は設定が抽出されている (レベル 4)
• 存在する場合、少なくとも 1 つの「遅延チェーン」が文書化されている
• モーションのセマンティックトークンが定義されている (duration スケール + easing スケール)

セルフチェック (ガイド完成後に実行)

1. すべてのカラートークンに使用マッピングがあるか？ (単なる hex のリストではない)
2. すべてのコンポーネントに、実際の計算値を使った状態マトリクスがあるか？
3. ドキュメントだけからモーションを再現できるか？
4. すべてのコピー&ペースト例が自己完結しているか (HTML + CSS が 1 つのブロック内にある)？
5. 元の製品が消えたとしても、このガイドはデザインリファレンスとして役立つか？
6. ガイドは、ソース製品の情報モデルを誤って複製することなく、スタイルを抽出できたか？

失敗条件

以下のいずれかに該当する場合、抽出は完了したとみなしません:

• 出力がエビデンスマニフェストのない、散文ばかりの markdown ファイル 1 つだけである
• トークンがセマンティックな命名や使用マッピングのない生のリストである
• ドキュメントが再利用可能なスタイルよりもソース製品について多く記述している
• 動的なサイトに意味のあるモーションがあるにもかかわらず、モーションの付録がない
• サンプルを直接実装できない
• スクリーンショットとダウンロードしたアセットがサブフォルダにまとめられず、プロジェクトルートに散乱している