stitch-design-system

Stitch → デザインシステムのコードアーティファクト

あなたはデザインシステムエンジニアです。Stitch のデザインを分析し、ドキュメントだけでなく、コードアーティファクトを生成します。design-md スキルが人間向けの Markdown ファイルを生成するのに対し、このスキルでは、コードベースに実際にインポートできるファイルを生成します。ダークモード対応の CSS カスタムプロパティ、Tailwind v4 の設定、タイポグラフィトークンが含まれます。

stitch-nextjs-components や stitch-svelte-components を実行する前に、まずこのスキルを使用してください。 生成されるトークンは、以降のすべてのコンポーネント生成の基盤になります。

このスキルを使用するタイミング

次の場合にこのスキルを使用します。

• Stitch のデザインをもとに新しいプロジェクトを開始するとき
• ユーザーが「デザイントークン」、「CSS 変数」、「ダークモードトークン」、「Tailwind 設定」に言及したとき
• デザインの一貫性を確保するため、フレームワーク変換スキルの前に実行するとき
• Stitch のデザイン更新後に、既存プロジェクトのデザインシステムを更新するとき

このスキルが生成するもの

3 つの出力ファイル：

ファイル	目的
design-tokens.css	CSS カスタムプロパティ。フレームワークのグローバル CSS にインポートします
tailwind-theme.css	Tailwind v4 の @theme ブロック。globals.css に貼り付けます
DESIGN.md	拡張デザインドキュメント（design-md より詳細で、ダークモードとアニメーショントークンを含みます）

ステップ 1：Stitch のデザインを取得する

1. ネームスペースの特定 — list_tools を実行して、Stitch MCP のプレフィックスを確認します。
2. 画面の取得 — projectId と screenId を指定して [prefix]:get_screen を呼び出します。
3. HTML のダウンロード — 以下を実行します：

   bash scripts/fetch-stitch.sh "[htmlCode.downloadUrl]" "temp/source.html"
   

4. ビジュアルリファレンス — screenshot.downloadUrl を確認して、デザインの全体像を把握します。

画面が複数ある場合は、すべて取得します。[prefix]:list_screens を実行し、各画面を取得して、トークンセットがデザインのあらゆるパターンを網羅するようにします。

ステップ 1.5：プロジェクトの DesignTheme を確認する（信頼できる情報源）

HTML を解析する前に、Stitch API から正式なデザインデータを取得します。これにより推測を排除できます。API は正確なプライマリカラー、フォント、完全なセマンティックカラーマップを把握しています。

1. projects/[projectId] を指定して get_project を呼び出します
2. designMd を確認する — 存在する場合、Stitch が自動生成した完全な Markdown 形式のデザインシステムドキュメントです。タイポグラフィのルール、色の考え方、コンポーネントのパターン、間隔のガイドライン、推奨事項と禁止事項を読み取ります。これは最も価値の高い単一フィールドです。
3. namedColors を抽出する — 40 個以上のトークンを含むセマンティックカラーマップです。これにより、システム全体の色が事前に計算された状態で取得できます。
   • プライマリ：primary、on_primary、primary_container、on_primary_container、primary_fixed、primary_fixed_dim
   • セカンダリ：secondary、on_secondary、secondary_container、on_secondary_container
   • ターシャリ：同じパターン
   • サーフェス：surface、surface_dim、surface_bright、surface_container_lowest、surface_container_low、surface_container、surface_container_high、surface_container_highest、surface_tint、surface_variant
   • ユーティリティ：background、on_background、on_surface、on_surface_variant、outline、outline_variant
   • 状態：error、on_error、error_container、on_error_container
   • インバース：inverse_surface、inverse_on_surface、inverse_primary
4. 構造的な値を抽出する： | DesignTheme フィールド | → CSS トークン | マッピング | |---|---|---| | customColor | --color-primary | 16 進数のシードカラーですが、利用可能な場合は namedColors.primary を優先します | | overridePrimaryColor | --color-primary | customColor より優先されます | | overrideSecondaryColor | --color-secondary | 16 進数で指定する正確な上書き値 | | overrideTertiaryColor | --color-tertiary | 16 進数で指定する正確な上書き値 | | overrideNeutralColor | --color-neutral | サーフェス階層のベース | | backgroundLight | --color-background（ライト） | ライトモードのページ背景 | | backgroundDark | --color-background（ダーク） | ダークモードのページ背景 | | headlineFont | --font-sans / 見出し | 列挙値をフォントファミリーのスタックにマッピングします（下の表を参照） | | bodyFont | --font-body | 列挙値をフォントファミリーのスタックにマッピングします | | labelFont | --font-label | 列挙値をフォントファミリーのスタックにマッピングします | | roundness | --radius-md の基準値 | ROUND_FOUR=4px、ROUND_EIGHT=8px、ROUND_TWELVE=12px、ROUND_FULL=9999px（ROUND_TWO も存在しますが、非推奨／未使用です） | | spacingScale | スペーシング倍率 | 0=タイト（基準 2px）、1=コンパクト（基準 4px）、2=標準（基準 4px）、3=ゆったり（基準 8px） | | spacing | --space-* の上書き | スペーシングトークン名 → CSS 値の任意のマップ（例：{"sm": "8px"}）。存在する場合は spacingScale の代わりに使用します | | typography | --text-* / --font-* の上書き | レベル名（h1、body など）→ Typography トークン（fontFamily、fontSize、fontWeight、letterSpacing、lineHeight）の任意のマップ | | colorVariant | パレットのアプローチを決定 | 例：FIDELITY はブランドカラーを維持し、VIBRANT は彩度を高めます |

フォントの列挙値 → CSS のフォントファミリーマッピング：

Stitch の列挙型	CSS のフォントファミリー
INTER	'Inter', system-ui, sans-serif
DM_SANS	'DM Sans', system-ui, sans-serif
GEIST	'Geist', system-ui, sans-serif
SPACE_GROTESK	'Space Grotesk', system-ui, sans-serif
MANROPE	'Manrope', system-ui, sans-serif
PLUS_JAKARTA_SANS	'Plus Jakarta Sans', system-ui, sans-serif
WORK_SANS	'Work Sans', system-ui, sans-serif
IBM_PLEX_SANS	'IBM Plex Sans', system-ui, sans-serif
RUBIK	'Rubik', system-ui, sans-serif
SORA	'Sora', system-ui, sans-serif
EPILOGUE	'Epilogue', system-ui, sans-serif
NUNITO_SANS	'Nunito Sans', system-ui, sans-serif
LEXEND	'Lexend', system-ui, sans-serif
PUBLIC_SANS	'Public Sans', system-ui, sans-serif
SOURCE_SANS_3	'Source Sans 3', system-ui, sans-serif
SOURCE_SANS_THREE	'Source Sans 3', system-ui, sans-serif — 非推奨のエイリアスです。SOURCE_SANS_3 を推奨します
MONTSERRAT	'Montserrat', system-ui, sans-serif
HANKEN_GROTESK	'Hanken Grotesk', system-ui, sans-serif
ARIMO	'Arimo', system-ui, sans-serif
BE_VIETNAM_PRO	'Be Vietnam Pro', system-ui, sans-serif
SPLINE_SANS	'Spline Sans', system-ui, sans-serif
METROPOLIS	'Metropolis', system-ui, sans-serif — 非推奨です。直接の後継はありません
JETBRAINS_MONO	'JetBrains Mono', ui-monospace, monospace
GOOGLE_SANS_CODE	'Google Sans Code', ui-monospace, monospace
SPACE_MONO	'Space Mono', ui-monospace, monospace
BEBAS_NEUE	'Bebas Neue', system-ui, sans-serif — 見出し向けのコンデンス書体
ANTON	'Anton', system-ui, sans-serif — 見出し向けのコンデンス書体
ARCHIVO_NARROW	'Archivo Narrow', system-ui, sans-serif — コンデンス書体
EB_GARAMOND	'EB Garamond', Georgia, serif
LITERATA	'Literata', Georgia, serif
SOURCE_SERIF_4	'Source Serif 4', Georgia, serif
SOURCE_SERIF_FOUR	'Source Serif 4', Georgia, serif — 非推奨のエイリアスです。SOURCE_SERIF_4 を推奨します
LIBRE_CASLON_TEXT	'Libre Caslon Text', Georgia, serif
NEWSREADER	'Newsreader', Georgia, serif
DOMINE	'Domine', Georgia, serif
NOTO_SERIF	'Noto Serif', Georgia, serif
PLAYFAIR_DISPLAY	'Playfair Display', Georgia, serif — エディトリアル向けの見出し書体
BODONI_MODA	'Bodoni Moda', Georgia, serif — エディトリアル向けの見出し書体

5. これらをベースラインとして使用します。 そのうえで、API から取得できない値（モーション／トランジションの時間、正確なピクセル単位の間隔、シャドウの定義）に限り、HTML の解析（ステップ 2）を使用します。

namedColors が利用可能な場合は、 ステップ 2 の色の抽出を完全にスキップします。API のカラーマップが完全かつ正式な情報源です。HTML から補足するのは、モーション、ピクセル単位の間隔、シャドウのみです。

designMd が利用可能な場合は、 DESIGN.md の出力（ステップ 5）の基礎として使用します。書き換えずに、CSS 変数名、Tailwind のマッピング、実装上の注意点を追加します。

ステップ 2：HTML から補足値を抽出する

ステップ 1.5 で namedColors と designMd が提供されている場合、HTML が必要なのは以下のみです。

モーション

• 使用されているトランジション時間（または、マイクロインタラクションは 150ms、パネルは 300ms と推定します）
• イージングのスタイル（linear、ease-out、spring-like）

ピクセル単位の間隔

• デザインで使用されている正確な gap／padding 値
• シャドウの定義

追加の色（まれ）

デザインで namedColors に含まれない色が使われている場合のみ、グラデーション、オーバーレイ、カスタムアクセントカラーを確認します。

ステップ 1.5 で namedColors が提供されなかった場合（designMd のない古いプロジェクト）は、HTML 全体の抽出に切り替えます。

色（フォールバック）

<head> 内の Tailwind 設定から、またはスクリーンショットから推定して、異なる色をすべて特定します。それぞれの意味的な役割と使用頻度を判断します。意味的なトークンは 8〜12 個を目安にします。

タイポグラフィ（フォールバック）

• フォントファミリー（見出し、本文、等幅 — 存在する場合）
• 文字サイズのスケール（デザインで使われている実際の px または rem の値）
• 使用されているフォントの太さ
• 行の高さ

間隔と形状（フォールバック）

• 基本の間隔単位（通常は 4px または 8px）
• 角丸の値
• シャドウの定義

ステップ 3：design-tokens.css を生成する

ライトモードとダークモードの完全なトークンセットを含む design-tokens.css を作成します。

命名規則：

• --color-* — 色のトークン
• --font-* — タイポグラフィ
• --spacing-* — 間隔のスケール
• --radius-* — 角丸
• --shadow-* — エレベーション
• --motion-* — アニメーションのタイミング

テンプレート（API から namedColors を取得できる場合 — 推奨）：

/* =============================================================
   Design Tokens — extracted from Stitch project: [Project Name]
   Generated by stitch-design-system skill
   Source: DesignTheme API (namedColors) + HTML supplementary
   ============================================================= */

/* ---- Light mode (default) ---- */
:root {
  /* Colors: Direct mapping from Stitch namedColors API response */
  --color-primary:          [namedColors.primary];
  --color-on-primary:       [namedColors.on_primary];
  --color-primary-container: [namedColors.primary_container];
  --color-secondary:        [namedColors.secondary];
  --color-on-secondary:     [namedColors.on_secondary];
  --color-tertiary:         [namedColors.tertiary];
  --color-on-tertiary:      [namedColors.on_tertiary];
  --color-error:            [namedColors.error];
  --color-on-error:         [namedColors.on_error];
  --color-background:       [namedColors.background];
  --color-on-background:    [namedColors.on_background];
  --color-surface:          [namedColors.surface];
  --color-on-surface:       [namedColors.on_surface];
  --color-surface-variant:  [namedColors.surface_variant];
  --color-on-surface-variant: [namedColors.on_surface_variant];
  --color-surface-container: [namedColors.surface_container];
  --color-surface-container-low: [namedColors.surface_container_low];
  --color-surface-container-high: [namedColors.surface_container_high];
  --color-surface-container-highest: [namedColors.surface_container_highest];
  --color-outline:          [namedColors.outline];
  --color-outline-variant:  [namedColors.outline_variant];
  --color-inverse-surface:  [namedColors.inverse_surface];
  --color-inverse-on-surface: [namedColors.inverse_on_surface];
  --color-inverse-primary:  [namedColors.inverse_primary];
  --color-surface-tint:     [namedColors.surface_tint];

  /* Typography */
  --font-sans:    [font-family-stack];   /* Heading and UI font */
  --font-body:    [font-family-stack];   /* Body text font (may equal --font-sans) */
  --font-mono:    [monospace-stack];     /* Code, technical content */

  /* Type scale */
  --text-xs:   0.75rem;   /* 12px */
  --text-sm:   0.875rem;  /* 14px */
  --text-base: 1rem;      /* 16px */
  --text-lg:   1.125rem;  /* 18px */
  --text-xl:   1.25rem;   /* 20px */
  --text-2xl:  1.5rem;    /* 24px */
  --text-3xl:  1.875rem;  /* 30px */
  --text-4xl:  2.25rem;   /* 36px */

  /* Spacing scale (base 4px) */
  --space-1:  0.25rem;   /* 4px */
  --space-2:  0.5rem;    /* 8px */
  --space-3:  0.75rem;   /* 12px */
  --space-4:  1rem;      /* 16px */
  --space-6:  1.5rem;    /* 24px */
  --space-8:  2rem;      /* 32px */
  --space-12: 3rem;      /* 48px */
  --space-16: 4rem;      /* 64px */

  /* Geometry */
  --radius-sm: [value];  /* Small elements: badges, chips */
  --radius-md: [value];  /* Buttons, inputs */
  --radius-lg: [value];  /* Cards, panels */
  --radius-xl: [value];  /* Modals, drawers */
  --radius-full: 9999px; /* Pills, avatars */

  /* Shadows */
  --shadow-sm: [value];  /* Subtle card lift */
  --shadow-md: [value];  /* Dropdown, tooltip */
  --shadow-lg: [value];  /* Modal, sheet */

  /* Motion tokens */
  --motion-duration-fast:   150ms;   /* Hover states, micro interactions */
  --motion-duration-base:   250ms;   /* Typical UI transitions */
  --motion-duration-slow:   400ms;   /* Page-level, large panel */
  --motion-ease-default:    cubic-bezier(0.4, 0, 0.2, 1);  /* Material ease */
  --motion-ease-out:        cubic-bezier(0, 0, 0.2, 1);    /* Entries */
  --motion-ease-in:         cubic-bezier(0.4, 0, 1, 1);    /* Exits */
  --motion-ease-spring:     cubic-bezier(0.34, 1.56, 0.64, 1); /* Bouncy open */
}

/* ---- Dark mode ---- */
/* Applied via .dark class (Next.js + next-themes) or [data-theme="dark"] (Svelte) */
.dark,
[data-theme="dark"] {
  --color-background:       [dark-hex];
  --color-surface:          [dark-hex];
  --color-surface-elevated: [dark-hex];
  --color-primary:          [dark-hex];  /* Same hue, lighter for dark bg contrast */
  --color-primary-hover:    [dark-hex];
  --color-primary-fg:       [dark-hex];
  --color-secondary:        [dark-hex];
  --color-secondary-fg:     [dark-hex];
  --color-text:             [dark-hex];
  --color-text-muted:       [dark-hex];
  --color-text-disabled:    [dark-hex];
  --color-border:           [dark-hex];
  --color-border-focus:     [dark-hex];
  --color-error:            [dark-hex];
  --color-success:          [dark-hex];
  --color-warning:          [dark-hex];
  /* Typography, spacing, geometry, motion tokens: unchanged in dark mode */
}

ステップ 4：tailwind-theme.css を生成する

Tailwind v4（tailwind.config.js を使用しない）プロジェクトでは、@theme ブロックを生成します。

重要： Tailwind v4 では、JS の設定ファイルではなく CSS 内の @theme を使用します。トークンを Tailwind の名前空間に対応させます。

/* tailwind-theme.css — paste into your globals.css or import it */
@import "tailwindcss";

@theme {
  /* Wire Tailwind color utilities to your CSS variables */
  --color-background: var(--color-background);
  --color-surface: var(--color-surface);
  --color-primary: var(--color-primary);
  --color-primary-hover: var(--color-primary-hover);
  --color-text: var(--color-text);
  --color-text-muted: var(--color-text-muted);
  --color-border: var(--color-border);

  /* Fonts */
  --font-sans: var(--font-sans);
  --font-mono: var(--font-mono);

  /* Radius */
  --radius-sm: var(--radius-sm);
  --radius-md: var(--radius-md);
  --radius-lg: var(--radius-lg);

  /* Animation duration utilities */
  --animate-duration-fast: var(--motion-duration-fast);
  --animate-duration-base: var(--motion-duration-base);
  --animate-duration-slow: var(--motion-duration-slow);
}

Tailwind v3 プロジェクト（tailwind.config.js がある場合）では、代わりに抽出した HEX 値を直接使って tailwind.config.js のセクションを生成します。

ステップ 5：DESIGN.md を生成する

拡張版のデザインドキュメントを作成します。標準の design-md スキルのすべてのセクションに加えて、以下を含みます。

# Design System: [Project Name]

> Generated by stitch-design-system from Stitch project [ID]
> Screens analyzed: [list]

## 1. Visual Theme & Atmosphere
[Mood, density, aesthetic philosophy — 2-3 sentences]

## 2. Color Palette & Roles
| Token | Light | Dark | Role |
|-------|-------|------|------|
| --color-primary | #... | #... | Main CTA, key actions |
| --color-background | #... | #... | Page background |
| ... | | | |

## 3. Typography
- **Heading font**: [Family, weights used, where]
- **Body font**: [Family, weights used, where]
- **Type scale**: xs (12px) → sm (14px) → base (16px) → lg (18px) → ... → 4xl (36px)

## 4. Geometry & Elevation
- **Border radius**: sm [Xpx] | md [Xpx] | lg [Xpx] | xl [Xpx]
- **Shadows**: [describe the elevation system]

## 5. Motion System
- **Micro** (hovers, toggles): [duration]ms [easing]
- **Meso** (panels, drawers): [duration]ms [easing]
- **Macro** (page transitions): [duration]ms [easing]
- **Spring** (playful elements): cubicOut spring

## 6. Stitch Prompt Copy-Paste Block
Use this block in every Stitch prompt for design consistency:

[Primary color: NAME (#HEX)] — ボタンと重要なアクションに使用 [Background: #HEX] — クリーンで[雰囲気を表す形容詞] [Typography: FONT NAME] — 見出しは[太さ]、本文はレギュラー [Aesthetic: ビジュアルスタイルを表す形容詞を2～3個] [Border radius: SIZE — 角丸／鋭角／ピル型の要素]

## 7. Dark Mode Notes
[Specific notes on how the dark theme differs — any color roles that change significantly, any elements that need special treatment in dark mode]

ステップ 6：出力と統合

次の3つのファイルをプロジェクトのルート（またはユーザーが指定した場所）に書き込みます。

• design-tokens.css
• tailwind-theme.css
• DESIGN.md

次に、使い方をユーザーに伝えます。

Next.js の場合：

// app/globals.css
@import '../design-tokens.css';
@import '../tailwind-theme.css';

SvelteKit の場合：

@import '$lib/design-tokens.css';

Stitch のループの場合：

生成する画面全体でデザインの一貫性を保つため、DESIGN.md のセクション 6 をすべての Stitch プロンプトにコピーします。

トラブルシューティング

問題	解決方法
ダークモードの HEX 値を特定できない	ライトモードの色相を使い、彩度を少し下げて、明度を 30～40％上げます
フォントが読み込まれない	design-tokens.css に Google Fonts の @import を追加します
Tailwind v3 と v4 の違いが分からない	package.json を確認します — v4 では "tailwindcss": "^4" を使用し、設定ファイルはありません
トークンが適用されない	design-tokens.css がコンポーネントの CSS より前にインポートされていることを確認します

他のスキルとの統合

• stitch-nextjs-components または stitch-svelte-components の前にこのスキルを実行します
• フレームワークスキルは値をハードコードする代わりに、design-tokens.css をインポートします
• DESIGN.md のセクション 6 は、複数ページの一貫性を保つために stitch-loop で使用されます

参考資料

• resources/tokens-template.css — すべてのトークンカテゴリを含む完全なテンプレート