フロントエンドコードからデザインシステムを抽出する
フロントエンドのソースコードを分析し、アプリケーションをビルドしたりレンダリングしたりすることなく、ソースファイルから直接、プロジェクトのビジュアル言語（色、タイポグラフィ、スペーシング、コンポーネントパターン、レイアウト原則）を網羅したデザインシステム文書（DESIGN.md）を抽出します。
存在理由
design-md スキルはレンダリングされたHTMLから機能します。しかし、多くの場合、コードベースはあっても、アプリを実行する前にそのデザインシステムを理解したいことがあります。依存関係が不足していたり、ビルドが壊れていたり、あるいは単に簡単に監査したい場合です。このスキルは、スタイルシート、コンポーネントファイル、テーマ設定、Tailwind設定など、ソースファイル自体を読み取ります。より高速で、どこでも動作します。
使用するタイミング
- ユーザーがフロントエンドのコードベースを持っていて、そのデザインシステムを抽出または文書化したい場合
- ユーザーがプロジェクトのビジュアルアイデンティティをStitchに移行したい場合
- ユーザーがリポジトリの「スタイリングの監査」や「デザイン言語の理解」を依頼した場合
- ユーザーが既存のソースコードからDESIGN.mdを作成したい場合
- アプリをビルド/レンダリングできないが、ソースは利用可能な場合
- ユーザーがコードベース全体で一貫性のないスタイルを統一または調整したい場合
前提条件
- フロントエンドプロジェクトのソースディレクトリにアクセスできること
- ビルドやランタイムの依存関係は不要です。このスキルはソースファイルのみを読み取ります
ワークフロー
フェーズ1: プロジェクトの発見
まず、何を扱っているのかを理解します。これにより、使用する抽出パターンが決まります。
1. フレームワークとスタックを検出する
プロジェクトルートで目印となるファイルをスキャンします:
| シグナルファイル | フレームワーク / ツール |
|---|---|
react を含む package.json | React / Next.js |
vue を含む package.json | Vue / Nuxt |
svelte を含む package.json | Svelte / SvelteKit |
@angular/core を含む package.json | Angular |
tailwind.config.js/ts | Tailwind CSS |
postcss.config.js | PostCSS パイプライン |
依存関係に styled-components または @emotion | CSS-in-JS |
.css / .scss / .less ファイルのみ | プレーンCSS / SASS |
theme.js / theme.ts / tokens.js | デザイントークンファイル |
最初に package.json を読んでください。フレームワーク、CSSツール、およびデザイントークンライブラリ（例: style-dictionary、@chakra-ui/react、@mui/material、ant-design）が明らかになります。このコンテキストから、スタイリング情報をどこに探しに行くべきかがわかります。
2. ソースツリーをマッピングする
分析する主要なディレクトリとファイルを特定します:
src/
├── components/ ← コンポーネントレベルのスタイル
├── styles/ ← グローバルスタイルシート
├── theme/ ← テーマ定義、トークン
├── assets/ ← フォント、画像
├── app.css ← ルートスタイル
└── index.css ← エントリーCSS
さらに以下も確認します:
tailwind.config.js/tailwind.config.ts— カスタム色、フォント、スペーシングglobals.css/global.css— CSSカスタムプロパティ（変数）theme.*またはtokens.*ファイル- コンポーネントライブラリの設定（例:
chakra-theme.ts、vuetify.config.ts）
3. フレームワーク固有のガイダンスを読む
抽出パターンについて、適切なリファレンスを参照してください:
- React / Next.js / Tailwind → references/react-tailwind.md
- Vue / Nuxt → references/vue.md
- Svelte / SvelteKit → references/svelte.md
- Angular → references/angular.md
- プレーンCSS / SASS / Less → references/plain-css.md
これらのリファレンスには、色、タイポグラフィ、スペーシング、コンポーネントスタイルを見つけるためのフレームワーク固有のパターンが含まれています。先に進む前に、該当するものを読んでください。
フェーズ2: 詳細な抽出
各デザインの次元を体系的に精査します。それぞれについて、ソースファイルから生データを収集し、それを説明的な言葉に合成します。
目標は、すべてのCSSプロパティをダンプすることではありません。スタイリングの選択の背後にある意図を理解し、人間の編集的な言葉で説明して、別のデザイナー（またはStitch）が同じビジュアルフィールを再現できるようにすることです。
1. ビジュアルテーマと雰囲気
まず最も広範なスタイリングを読み、全体的なムードを理解します:
- ルートの背景:
bodyまたはルート要素の背景は何ですか？ ライトクリーム（#fレンジ）は風通しが良く清潔感を示し、ダーク（#0-#2レンジ）はムーディーで劇的です。 - ホワイトスペースの哲学: スペーシングの値は寛大（32px+）ですか、それともタイトですか？ ルートコンテナ、セクションラッパー、カードコンポーネントのパディング/マージン値を確認します。
- 密度: ページ/セクションごとのコンポーネント数を数えます。スペースがあるものが少なければミニマル、多く密集していれば情報密度が高いです。
- 色温度: ニュートラルは暖色系（クリーム、タン）ですか、寒色系（ブルーグレー、スレート）ですか？
- 全体的な感触: ムードを捉えた1〜2の豊かな文章に合成します。
ソース内でこれらのシグナルを探します:
| ソースの場所 | 示す内容 |
|---|---|
ルート background-color またはレイアウトのTailwind bg-* | 全体的な明るさ/暗さ |
| Tailwind設定またはCSS変数のスペーシングスケール | ホワイトスペースの哲学 |
| コンポーネント数とラッパーのパディング | 密度 |
カスタムプロパティの命名（--warm-* vs --cool-*） | 色温度の意図 |
| テーマファイルのコメント | 開発者自身の言葉によるデザイン意図 |
2. カラーパレットと役割
コードベースからすべてのユニークな色を抽出し、機能的な役割を割り当てます。すべてのレイヤーを検索します:
色を見つける場所:
| レイヤー | 検索対象 |
|---|---|
| CSSカスタムプロパティ | --color-*、--primary、--bg-* |
| Tailwind設定 | theme.extend.colors |
| テーマ/トークンファイル | 色オブジェクト、パレット |
| コンポーネントスタイル | background-color、color、border-color |
| インライン/スコープ付きスタイル | テンプレート内の bg-*、text-* クラス |
| CSS-in-JSテーマオブジェクト | colors、palette キー |
整理方法: 色相ではなく機能でグループ化します:
- プライマリファンデーション — 背景とサーフェスの色
- アクセントとインタラクティブ — CTAボタン、アクティブ状態、リンク
- タイポグラフィとテキスト階層 — 一次、二次、三次テキスト
- 機能状態 — 成功、エラー、警告、情報
各色について、生の16進数値ではなく、色の特性を想起させる説明名を作成します:
- ❌
#294056→ 「ブルー」 - ✅
#294056→ 「ディープミューテッドティールネイビー」 — プライマリCTA、アクティブナビゲーション
重複排除は重要です。 コードベースには、よく似た色（例: #333 と #2C2C2C）が存在することがよくあります。意図された色を最もよく表す1つの名前に統合します。
3. タイポグラフィルール
完全なタイポグラフィシステムを抽出します:
フォントファミリー:
- CSS
font-family、TailwindfontFamily、Google Fontsリンク、またはローカルの@font-face宣言を確認します。 - 各フォントの特徴に注目します: 幾何学的 vs ヒューマニスト、セリフ vs サンセリフ、それが呼び起こす感触。
タイプスケール（階層）:
- すべての見出しレベル（H1-H6）と本文テキストを見つけ、以下を記録します:
font-size（remまたはpx）font-weight（数値 + 説明的な名前）letter-spacing（そしてその理由 — 優雅さ？ コンパクトさ？）line-height（読みやすさのために寛大？ ディスプレイ用にタイト？）
- コンポーネントの使用法をマッピングします: プロダクトカードではどの見出しレベルを使用しますか？ ヒーローセクションではどうですか？
スペーシングの原則:
- テキストのスペーシングは、全体的なスペーシングスケールとどのように関連していますか？
- 見出しと本文でのレタースペーシングのパターン
- 行間の哲学（本文は寛大/リラックス、ディスプレイはタイト）
4. コンポーネントスタイリング
最も重要な4〜5つのUIプリミティブを分析します:
ボタン:
- 角の半径（そしてそれが何を伝えるか — 遊び心？ プロフェッショナル？ ミニマル？）
- プライマリ、セカンダリ、ゴーストバリアントの配色
- ホバー/フォーカス/アクティブ状態とトランジションのタイミング
- パディング比率（水平 vs 垂直）
カード / コンテナ:
- 角の半径（多くの場合ボタンとは異なり、やや丸みを帯びています）
- シャドウ戦略: フラット、微妙なホバーシャドウ、または常に浮き上がった状態？
- ボーダーの処理: ヘアラインボーダー、カラーアクセント、またはなし？
- 内部パディング（寛大？ それともコンパクト？）
- カード内の画像処理（フルブリード、パディング、丸み？）
ナビゲーション:
- レイアウトパターン（水平バー、垂直サイドバー、ドロワー）
- タイポグラフィの処理（大文字、レタースペーシング、太さ）
- アクティブ/ホバー状態のインジケーター（下線、色、背景）
- モバイルでの動作（ハンバーガー、ボトムナビ、ドロワー）
入力とフォーム:
- ボーダースタイルとフォーカス状態の動作
- ボタンとのコーナースタイルの一貫性
- パディングとタッチターゲットのサイズ設定
ドメイン固有コンポーネント:
- このプロジェクトに固有の1〜2のコンポーネント（例: プロダクトカード、ダッシュボードウィジェット、チャットバブル）を特定し、そのスタイリングパターンを説明します。
5. レイアウト原則
構造システムを抽出します:
グリッドと構造:
- 最大コンテンツ幅（コンテナの
max-widthから） - カラムシステム（CSS Grid、Flexboxパターン、定義されたブレークポイント）
- レスポンシブブレークポイント（メディアクエリまたはTailwind設定から）
ホワイトスペース戦略:
- 基本スペーシング単位（8pxグリッド？ 4px？ カスタム？）
- セクションマージン（主要セクション間のスペースの量）
- エッジパディング（異なるブレークポイントでのページマージン）
配置と視覚的バランス:
- テキスト配置パターン（中央寄せのヒーロー、左寄せの本文）
- 画像とテキストの比率
- 視覚的な重みの分布
レスポンシブ動作:
- モバイルファーストかデスクトップファーストか？
- グリッドはどのように折りたたまれますか？ パディングスケール？
- タッチターゲットのサイズ設定
6. Stitch生成のためのメモ
抽出結果をStitchのための実用的なプロンプトにまとめます:
- 雰囲気の言葉: ムードを自然な記述子に変換します
- 色の参照: 説明的な名前 + 16進数で色をリストアップします
- コンポーネントプロンプト: Stitchで主要コンポーネントを再現する2〜3のプロンプト例を書きます
- 反復ガイダンス: このデザインシステムで画面を洗練するためのヒント
フェーズ3: DESIGN.mdを書く
すべてを標準的なDESIGN.md形式にまとめます。プロジェクトディレクトリの .stitch/DESIGN.md に配置します（.stitch/ ディレクトリが存在しない場合は作成します）。
[!重要] examples/DESIGN.md の例に示されているように、ファイルの先頭に
nameとcolorsマッピングを含むYAMLフロントマターを必ず含める必要があります。この構造化データは、他のスキルがデザインシステムを解析するために必要です。少なくともコアなカラートークンを含むこのYAMLブロックを含めないことは、このスキルを正しく使用できていないことになります。
examples/DESIGN.md の例の形式をテンプレートとして使用してください。ファイルはYAMLブロックで始まり、その後にマークダウンセクションが続く必要があります:
# デザインシステム: [プロジェクト名]
**プロジェクトID:** [既知の場合は記入、それ以外は省略]
## 1. ビジュアルテーマと雰囲気
[ムード、哲学、主要な特徴のリッチな2段落の説明]
## 2. カラーパレットと役割
### プライマリファンデーション
### アクセントとインタラクティブ
### タイポグラフィとテキスト階層
### 機能状態
## 3. タイポグラフィルール
### 階層とウェイト
### スペーシングの原則
## 4. コンポーネントスタイリング
### ボタン
### カードと[ドメイン固有コンテナ]
### ナビゲーション
### 入力とフォーム
### [ドメイン固有コンポーネント]
## 5. レイアウト原則
### グリッドと構造
### ホワイトスペース戦略
### 配置と視覚的バランス
### レスポンシブ動作とタッチ
## 6. Stitch生成のためのデザインシステムメモ
### 使用する言葉
### 色の参照
### コンポーネントプロンプト
### 段階的な反復
フェーズ4: 統合（任意）
ユーザーがデザインシステムをStitchにプッシュしたい場合:
- MCPの作成/更新呼び出しのために
manage-design-systemスキルに引き継ぎます - あなたが書いたDESIGN.mdが入力となり、
manage-design-systemスキルがStitch API統合を処理します
ユーザーが文書だけを希望する場合は、フェーズ3の後で完了です。
品質チェックリスト
DESIGN.mdを提供する前に、以下を確認してください:
- すべての色に説明的な名前、16進コード、機能的な役割がある
- タイポグラフィにフォントファミリー、特徴の説明、完全な階層が含まれている
- コンポーネントスタイルが形状、色、状態、トランジションを説明している
- レイアウトに最大幅、グリッド、ブレークポイント、スペーシング戦略が含まれている
- Stitch生成メモがCSS構文ではなく自然言語を使用している
- 雰囲気のセクションが技術文書ではなく編集的なコピーのように読める
- 類似した色が統合されている
- 文書が生の値だけでなく、スタイリングの背後にある意図を捉えている
より良い抽出のためのヒント
- コメントとコミットメッセージを読むこと。 開発者はしばしばコードコメント（
/* ヒーローセクション — 余裕を持たせる */）やコミットメッセージにデザインの意図を文書化します。これらはなぜを理解するための宝の山です。 - デザイントークンライブラリを確認すること。 プロジェクトが
style-dictionary、@tokens-studioなどを使用している場合、これらのファイルはデザイン値の最も信頼できる情報源です。 - テーマファイルはコンポーネントスタイルよりもシグナルが強いです。 パレットを定義する
theme.tsは意図されたデザインシステムを示します。コンポーネントに散在するインラインスタイルは、実際に出荷されたものを示します。両方とも重要ですが、テーマから始めてください。 - Tailwind設定はデザインシステムです。 プロジェクトにカスタマイズされた
tailwind.config.jsがある場合、それはそのままデザインシステムです。最初にそこから抽出し、その後コンポーネントのオーバーライドをスポットチェックしてください。 - CSSカスタムプロパティは意図的です。 開発者が
--brand-primaryを定義した場合、これはデザイントークンであると伝えています。それを尊重してください。