stitch::extract-design-md

フロントエンドコードからデザインシステムを抽出する

フロントエンドのソースコードを分析し、ビルドやアプリケーションのレンダリングを行わずに、色、タイポグラフィ、余白、コンポーネントのパターン、レイアウトの原則など、プロジェクトのビジュアル言語をまとめた包括的なデザインシステム文書（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/     ← Component-level styles
├── styles/         ← Global stylesheets
├── theme/          ← Theme definitions, tokens
├── assets/         ← Fonts, images
├── app.css         ← Root styles
└── index.css       ← Entry 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-* と --cool-* など）	色温度の意図
テーマファイル内のコメント	開発者自身の言葉で記されたデザインの意図

2. カラーパレットと役割

コードベース内のすべての固有色を抽出し、機能上の役割を割り当てます。次のすべてのレイヤーを確認します。

色の検索場所：

レイヤー	検索対象
CSS カスタムプロパティ	--color-*、--primary、--bg-*
Tailwind の設定	theme.extend.colors
テーマ／トークンファイル	色のオブジェクト、パレット
コンポーネントのスタイル	background-color、color、border-color
インライン／スコープ付きスタイル	テンプレート内の bg-*、text-* クラス
CSS-in-JS のテーマオブジェクト	colors、palette キー

**整理方法：**色相ではなく機能ごとに色を分類します。

1. プライマリ基盤 — 背景色とサーフェスカラー
2. アクセントとインタラクティブ要素 — CTA ボタン、アクティブ状態、リンク
3. タイポグラフィとテキスト階層 — プライマリ、セカンダリ、ターシャリのテキスト
4. 機能状態 — 成功、エラー、警告、情報

色ごとに、16進数の値そのものではなく、色の特徴を感じさせる説明的な名前を付けます。

• ❌ #294056 → 「青」
• ✅ #294056 → 「深みのある落ち着いたティールネイビー」 — プライマリ CTA、アクティブなナビゲーション

**重複の統合が重要です。**コードベースには、よく似た色（例：#333 と #2C2C2C）が含まれていることがよくあります。意図された色を最もよく表す名前に統合します。

3. タイポグラフィのルール

タイポグラフィシステム全体を抽出します。

フォントファミリー：

• CSS の font-family、Tailwind の fontFamily、Google Fonts のリンク、ローカルの @font-face 宣言を確認します。
• 各フォントの特性を記録します。幾何学的かヒューマニストか、セリフ体かサンセリフ体か、どのような印象を与えるかを記します。

文字サイズのスケール（階層）：

• 見出しの各レベル（H1〜H6）と本文を確認し、次の項目を記録します。
  • font-size（rem または px）
  • font-weight（数値と説明的な名称）
  • letter-spacing（およびその理由 — 優雅さのためか、コンパクトさのためか）
  • line-height（読みやすさのためにゆったりしているか、表示用に詰まっているか）
• コンポーネントでの使い方を整理します。製品カードにはどの見出しレベルを使っていますか？ヒーローセクションではどうでしょうか？

スペーシングの原則：

• テキストの間隔は、全体的なスペーシングスケールとどのように関連していますか？
• 見出しと本文における文字間隔のパターン
• 行間の考え方（本文では読みやすさのためにゆったり／リラックスさせ、表示用では狭めるなど）

4. コンポーネントのスタイル

特に重要な UI プリミティブを 4～5 個分析します。

ボタン：

• 角の丸み（および、遊び心がある、プロフェッショナル、ミニマルなど、どのような印象を伝えるか）
• プライマリ、セカンダリ、ゴーストの各バリエーションの配色
• ホバー／フォーカス／アクティブ状態とトランジションのタイミング
• パディングの比率（横方向と縦方向）

カード／コンテナー：

• 角の丸み（ボタンとは異なる場合が多く、やや丸みが強めです）
• シャドウの方針：フラット、ホバー時のみ控えめなシャドウ、常に浮き上がって見えるスタイルのいずれか
• ボーダーの扱い：極細のボーダー、色付きのアクセント、またはなし
• 内側のパディング（ゆとりがあるか、コンパクトか）
• カード内の画像の扱い（全幅、パディングあり、角丸など）

ナビゲーション：

• レイアウトパターン（横方向のバー、縦方向のサイドバー、ドロワー）
• タイポグラフィの扱い（大文字、字間、太さ）
• アクティブ／ホバー状態のインジケーター（下線、色、背景）
• モバイルでの動作（ハンバーガーメニュー、ボトムナビゲーション、ドロワー）

入力欄とフォーム：

• ボーダーのスタイルとフォーカス状態の動作
• ボタンと一貫した角のスタイル
• パディングとタッチターゲットのサイズ

ドメイン固有のコンポーネント：

• このプロジェクト固有のコンポーネントを 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 ブロックで始め、その後に以下の Markdown セクションを続けます。

# Design System: [Project Name]
**Project ID:** [If known, otherwise omit]

## 1. Visual Theme & Atmosphere
[Rich 2-paragraph description of mood, philosophy, and key characteristics]

## 2. Color Palette & Roles
### Primary Foundation
### Accent & Interactive
### Typography & Text Hierarchy
### Functional States

## 3. Typography Rules
### Hierarchy & Weights
### Spacing Principles

## 4. Component Stylings
### Buttons
### Cards & [Domain-Specific Containers]
### Navigation
### Inputs & Forms
### [Domain-Specific Components]

## 5. Layout Principles
### Grid & Structure
### Whitespace Strategy
### Alignment & Visual Balance
### Responsive Behavior & Touch

## 6. Design System Notes for Stitch Generation
### Language to Use
### Color References
### Component Prompts
### Incremental Iteration

---

フェーズ 4：統合（任意）

ユーザーがデザインシステムを Stitch に反映したい場合：

1. MCP の作成／更新呼び出しのために、manage-design-system スキルに引き継ぎます
2. 作成した DESIGN.md が入力となります。Stitch API との統合は、manage-design-system スキルが担当します

ユーザーがドキュメントだけを必要としている場合は、フェーズ 3 の完了をもって終了します。

---

品質チェックリスト

DESIGN.md を提出する前に、次の点を確認してください。

• すべての色に、わかりやすい名前、16 進コード、機能上の役割が付いている
• タイポグラフィに、フォントファミリー、文字の特徴、完全な階層が含まれている
• コンポーネントのスタイルで、形状、色、状態、遷移が説明されている
• レイアウトに、最大幅、グリッド、ブレークポイント、間隔の方針が含まれている
• Stitch 生成時の注意事項が CSS 構文ではなく、自然言語で書かれている
• 雰囲気のセクションが技術文書ではなく、編集記事のような文章になっている
• ほとんど同じ色が統合されている
• 生の値だけでなく、スタイル設定の背後にある意図が文書に反映されている

抽出の精度を高めるヒント

• コメントとコミットメッセージを読みましょう。 開発者は、コードのコメント（/* hero section — breathable */）やコミットメッセージに、デザインの意図を記していることがよくあります。これらは、その理由を理解するための貴重な手掛かりです。
• デザイントークンライブラリを確認しましょう。 プロジェクトで style-dictionary、@tokens-studio などを使っている場合、それらのファイルが最も信頼性の高いデザイン値の情報源です。
• テーマファイルはコンポーネントのスタイルよりも有力な手掛かりです。 パレットを定義する theme.ts は、意図されたデザインシステムを示しています。一方、コンポーネントに散在するインラインスタイルは、実際にリリースされた内容を示しています。どちらも重要ですが、まずテーマから確認してください。
• Tailwind の設定はデザインシステムです。 プロジェクトにカスタマイズされた tailwind.config.js がある場合、それがデザインシステムそのものです。まずそこから抽出し、その後、コンポーネントを確認して上書き設定がないかチェックしてください。
• CSS カスタムプロパティには意図があります。 開発者が --brand-primary を定義しているなら、それはデザイントークンであることを示しています。その意図を尊重してください。