extract-saas-design

SaaS デザインの抽出

実装済みの SaaS ダッシュボード、管理パネル、または内部ツールのビジュアルシステムを詳細に調査し、構造化された Markdown として記録します。出力するのはドキュメントと確定済みのトークンであり、生成された UI コードではありません。

このスキルを使用する場面

以下のような意図に合致するリクエストで使用します。

• 「このダッシュボード URL からデザインシステムを抽出して」 — 稼働中の SaaS アプリ、管理パネル、または内部ツール。
• コードベース、リポジトリ、または HTML スナップショットから、「デザイントークンをドキュメント化して」／「ビジュアルシステムを取り出して」／「ビジュアルの特徴を抽出して」。
• globals.css、@theme、tailwind.config.*、またはトークンファイルから、「カラー、タイポグラフィ、間隔、角丸、シャドウのトークンをドキュメント化して」。
• 「サイドバー／テーブル／コマンドパレット／フォームのレイアウトをドキュメント化して」 — 実装済みの名前付きコンポーネント。
• 実装されたシステムを根拠に、「カラー、間隔、アクセシビリティの一貫性を監査して」。
• 稼働中のダッシュボードから、「ダークモードのトークンを記録して」／「モード切り替えをドキュメント化して」。
• 既存の見た目を別のチームやコードベースで再現できるよう、「デザインシステムを引き継いで」。
• 「ダッシュボードのチャートパレット／密度ゾーン／サイドバーのオーバーライドを抽出して」。

以下の場合は、このスキルを使用しないでください。

• ユーザーが動作する UI の構築、移植、複製、復元、変換、またはリリースを依頼している場合。convert-url-to-nextjs に引き継いでください。
• ユーザーが再デザイン、スタイル変更、「改善して」、または推測に基づく UX アドバイスを求めている場合。このスキルでは変更を推奨せず、存在するものだけを記録します。
• ソースがFigma のみ、スクリーンショットのみ、またはビジュアルの参考資料のみで、調査可能な実装（DOM、CSS、コード）が存在しない場合。
• 対象が SaaS／ダッシュボード／管理製品ではなく、マーケティング／パンフレットサイトの場合。

厳守事項（重要）

ルール	重要な理由
再構築ではなく、記録する。 .md ドキュメントのみを .design-soul/ に出力します。	生成された UI コードに踏み込むのは、別のスキルの役割です。
すべてのトークンチェーンを最終値まで解決する。 bg-primary → var(--primary) → oklch(0.205 0 0)。リテラル値で止めます。	クラス名やエイリアスは、再現する側には役立ちません。
範囲を守る。 ユーザーがサイドバーを依頼した場合、アプリ全体をドキュメント化しないでください。	範囲の逸脱は成果物の品質を損ないます。
存在しないことも根拠になる。 Hover: not implemented、Loading: not implemented、Dark mode: not implemented と記載します。	状態を捏造するより、情報の不足を認める方が適切です。
標準とノイズを分ける。 支配的なパターンを記録し、その後にファイル参照とともに不一致を列挙します。	不一致を取り繕うと、バグが隠れてしまいます。
スクリーンショットよりソースを優先する。 コンポーネントのソースと CSS トークンを主要な根拠とし、DOM／計算済みスタイルは補助的に扱います。スクリーンショットはレイアウトの検証にのみ使用します。	スクリーンショットでは疑似状態を正確に把握できません。

出力仕様

すべての成果物は、対象コードベースのルートにある .design-soul/（このスキルのリポジトリ内ではありません）に保存します。範囲に応じた標準の成果物は次のとおりです。

範囲	ファイル
全体の抽出／「ビジュアルの特徴」	system.md、番号付きの基礎ドキュメント、コンポーネントごとの番号付きドキュメント、INDEX.md、_summary.md
基礎／トークンのみ	system.md と基礎ドキュメントのみ
特定のコンポーネント	最小限の基礎情報と、指定されたコンポーネントごとの番号付きドキュメント
一貫性／アクセシビリティ監査	抽出したトークンに基づく、根拠を明示した調査結果ドキュメント。再デザインは含めません

標準形式は、CSS の再現用ブロックを含む Markdown です。明示的に依頼されない限り、.tokens.json、Style Dictionary、Tokens Studio のファイルは生成しないでください。

正確なテンプレートとフォルダー構成については、references/documentation/output-format.md、references/system-template.md、references/component-template.md を参照してください。

ワークフロー

1. 作業の範囲を定める

対象範囲、対象外、正とする情報源を一行で言い換えます。リクエストを満たす最小限の抽出を標準とします。

2. スタイリングスタックを検出する（すべての処理の前提条件）

ほかの作業を始める前に、対象ルートで次の項目を確認してください。

• Tailwind v4 — CSS に @import "tailwindcss" と @theme {} ブロックがあります。tailwind.config.* はありません。
• Tailwind v3 — theme.extend を含む tailwind.config.ts/js があります。
• shadcn/ui — components/ui/ ディレクトリがあり、@/lib/utils の cn() を使用しています。多くの場合、色には oklch() が使われています。
• CVA — class-variance-authority でバリアント／サイズの組み合わせを定義しています。cva() の呼び出しが仕様そのものです。
• CSS エントリーポイント — トークンは globals.css または app.css にあります。
• オフラインスナップショットモード — プレーンな HTML+CSS で、package.json や src/ はありません。CSS ファイルを信頼できる情報源として扱い、フレームワーク固有のシステムについては not implemented / N/A と記載してください。

対象ルートの解決方法と、スナップショット／リポジトリベースの扱いについては、references/extraction/target-modes.md を参照してください。

3. 証拠を収集する

ライブ URL またはインタラクティブなローカルアプリの場合は、run-agent-browser を使って DOM、計算済みスタイル、スクリーンショット、状態の網羅状況を取得してください。ブラウザツールは証拠の収集専用です。再構築に流用しないでください。

ブラウザの成果物は、対象コードベースのルートにある .design-soul/evidence/ に保存してください。ルートまたはページ名、ビューポート、スクリーンショットのパス、DOM／ソースのパス、観測した状態を記録します。

決定論的なトークン一覧を作成する場合は、対象ルートに対してヘルパースクリプトを実行してください。

• scripts/capture-css-tokens.md — CSS カスタムプロパティを列挙します。
• scripts/audit-spacing-scale.md — スペーシングスケールの使用状況を集計します。

4. 基盤を抽出する（対象範囲に含まれる場合）

スペーシング、色、タイポグラフィ、シャドウ／奥行き、角丸、アニメーション、共有状態の規約を網羅してください。ダッシュボードの場合は、サイドバーの上書き設定、チャートのパレット、密度ゾーン、表形式／等幅フォントの使用状況も網羅してください。

基盤	リファレンス
色（oklch() の読み取り、ダークモードの連鎖を含む）	references/extraction/color-extraction.md
タイポグラフィ（フォントスタック、スケール、行の高さ）	references/extraction/typography-extraction.md
スペーシング（スケールの検出、密度ゾーン）	references/extraction/spacing-extraction.md
アイコンとアセットの一覧	references/extraction/icons-and-assets.md
基盤抽出プロンプト（サブパス）	references/foundations-agent.md
ダッシュボード固有のパターン（サイドバーの上書き設定、チャートのパレット、密度）	references/dashboard-patterns.md
レイアウトグリッドとレスポンシブブレークポイント	references/layout/grid-and-responsive.md

5. コンポーネントとパターンを抽出する（対象範囲に含まれる場合）

各コンポーネントの構造、バリアント、サイズ、状態、状態遷移、ダークモードでの違い、構成を記録してください。サイドバー、テーブル、コマンドパレット、フォームレイアウトはメガコンポーネントです。サブパーツやモードに分解し、ひとまとめにしないでください。

オフラインスナップショットモードでは、繰り返し現れる DOM フラグメントとそれらのセレクターをコンポーネントの証拠として扱ってください。スナップショットで確認できることのみを記録し、不足している点は明示してください。

必要なもの	リファレンス
コンポーネント抽出プロンプト（サブパス）	references/components-agent.md
コンポーネント出力テンプレート	references/component-template.md

6. トークンを変換する

必要なもの	リファレンス
W3C DTCG、CSS カスタムプロパティ、oklch() 形式	references/tokens/token-formats.md
shadcn の命名パターン、セマンティック層とプリミティブ層	references/tokens/naming-conventions.md

7. 引き渡し前に検証する

完了を宣言する前に、検証チェックリストを実行してください。再現する人が値や状態を推測する必要がないことが基準です。

必要なもの	リファレンス
引き渡し前の検証チェックリスト	references/quality-checklist.md
一貫性監査チェックリスト	references/audit/consistency-checklist.md
アクセシビリティ／WCAG コントラストレビュー	references/audit/accessibility-review.md

次の項目に特に注意してください。無効状態、フォーカス可視状態、読み込み中、エラー／無効状態、空の状態、ダークモード、不透明度の意味、アニメーションの構成。

8. パッケージの出力

references/documentation/output-format.md の構成に従って、すべての成果物を対象コードベースのルートにある .design-soul/ に配置します。基盤には references/system-template.md、コンポーネントには references/component-template.md を使用します。新しい形式を独自に作らないでください。

ガードレール

これを行う	これは行わない
bg-primary、rounded-md、p-3 を実際の値に解決する	クラス名やエイリアスのままで済ませる
実装されていない場合は Hover: not implemented と記載する	「ベストプラクティス」の状態を作り出す
サイドバー／テーブル／フォームをサブパーツに分解する	巨大なコンポーネントをひとまとめにする
ファイルの根拠を示して不整合を明記する	不整合を、より整ったシステムに見えるように取り繕う
根拠に基づいて監査結果を記録する	再設計や批評に脱線する
構成とコンテキストを記録する	コンポーネントを個別にしか説明しない

復旧ルール

• 根拠が不十分な場合： グローバル CSS、テーマファイル、設定、Storybook、スクリーンショットなど、近接する正しい情報源を探します。それでも解決できない場合は、未解決であることを明記します。
• コードベースが大きすぎる場合： 基盤と、要求されたカテゴリまたはコンポーネントに分けます。対象範囲を黙って広げないでください。
• ファイル間で値が競合する場合： 主なパターンを記録し、例外には参照元を示します。
• ダークモード／状態が存在しない場合： そのことを明確に記載します。存在しないことも抽出結果の一部です。
• 実装に踏み込み始めた場合： ビルド手順の生成を中止し、ドキュメント成果物の作成に戻ります。

エージェント向けガイダンス

以下は、抽出でよくある失敗を防ぐためのものです。

Tailwind v4 の検出。 CSS ファイルで @import "tailwindcss" または @theme を検索します。見つかった場合、そのプロジェクトでは CSS ネイティブの設定を使用しており、tailwind.config.js はありません。theme.extend を含む tailwind.config.ts がある場合は v3 です。トークンを抽出する前に、必ず確認してください。検出コマンド：references/foundations-agent.md。

oklch カラースペース。 現代の shadcn/ui（2024 年以降）では oklch(L C H) を使用します。L は明度（0～1）、C は彩度（0～0.4）、H は色相（0～360）です。グレーでは C < 0.01 です。暗色と明色を区別できるよう、必ず明度を記載してください。読み取りガイド：references/extraction/color-extraction.md、references/tokens/token-formats.md。

CVA と cn()。 cva() の呼び出し自体がコンポーネントのビジュアル仕様です。すべてのバリアント／サイズのキーと値のペアを抽出してください。cn() ユーティリティは tailwind-merge を使ってクラスを統合し、最後のクラスが優先されます。CVA 抽出チェックリストと cn() の統合ガイド：references/component-template.md。

トークンチェーンの解決。 Tailwind クラスの段階で止めないでください。チェーン全体を解決します：bg-primary → var(--primary) → oklch(0.205 ...)。トークンが複数の変数を経由する場合もあります。リテラル値まで解決してください：references/extraction/color-extraction.md。

正確な情報源の優先順位

1. コンポーネントのソースと CSS トークン — 主要な情報源。
2. ライブ DOM／計算済みスタイルと Storybook — 二次的な情報源。
3. スクリーンショット — レイアウトと状態の網羅性を検証します。ソースの値より優先させないでください。
4. Figma トークン同期 — 実装済みのコードベースにトークン同期の成果物が含まれる場合に限り記録します。

convert-url-to-nextjs との境界

このスキルが作成するのはドキュメントです。convert-url-to-nextjs が作成するのは、スナップショットを基にしたビルド可能な Next.js アプリです。ユーザーが動作する UI の公開を希望する場合は、そちらに案内してください。見た目を再現するために別のチームが使う引き継ぎドキュメントを希望する場合は、このスキルを使用してください。

最後に

このスキルはオーケストレーターであり、テンプレートの寄せ集めではありません。メインの手順を簡潔に保ち、詳細は参照資料に案内し、UI を再構築したり再設計したりせず、実装済みの UI に基づいて進めてください。