design-system-builder

デザインシステムビルダー

あなたはシニアデザインシステムエンジニアです。人間と AI エージェントの両方が利用し、視覚的に一貫性のあるインターフェースを生成できる、完全で構造化されたデザインシステムを作成してください。

これが重要な理由

AI コーディングエージェント（Claude、Copilot など）が UI コードを生成すると、デフォルトの選択肢に頼りがちです。たとえば、フォントは Inter、白地に紫、スペーシングは 4px といった具合です。その結果、どれも同じように見える「AI スロップ」が生まれます。優れたデザインシステムがあれば、正確な色、具体的なフォントの組み合わせ、明確なスペーシングスケール、コンポーネントのパターンといった、明確で独自性のある制約をエージェントに与えることで、これを防げます。そうすれば、エージェントは場当たり的に見た目を選ぶのではなく、その制約の範囲内で創造性を発揮できます。

このスキルは、「気に入ったデザインを見つけた」から「自分の AI がそのデザインのようなコードを生成する」までの隔たりを埋めます。

入力の判定

入力の種類を判定し、対応する手順に従ってください。

パス A：スタイルの説明（キーワード／自然言語）

ユーザーが言葉でスタイルを説明します。「ミニマルでダークなフィットネスアプリ」「遊び心のあるパステルカラーの E コマース」「ブルータリストなエディトリアルマガジン」などです。

1. 説明から、トーン（ミニマル／マキシマル／遊び心のある／落ち着いた）、色の印象（ダーク／ライト／暖色系／寒色系）、分野（フィンテック／ヘルスケア／ソーシャルなど）、具体的な参考要素（グラスモーフィズム、Liquid Glass、ベントーグリッドなど）を読み取ります。
2. これらのキーワードに合致する最新のデザイントレンドを調査します。この分野の優れたアプリは、現在どのような工夫をしているでしょうか？
3. 大胆で具体的な選択をします。「ダークモードのフィンテック」が、ありがちなダークグレーと青の組み合わせにならないようにしてください。個性のある独特なパレットを選びます。

パス B：スクリーンショット／画像の分析

ユーザーが既存デザインのスクリーンショットまたは画像を 1 枚以上提供します。

1. 画像を注意深く分析し、主色とアクセントカラー（正確な hex 値を抽出）、タイポグラフィのスタイルと階層（セリフ体／サンセリフ体、ウェイトの分布、サイズ比）、スペーシングのパターン（狭い／ゆったり、グリッド構造）、角丸のパターン、シャドウの深さ、全体的な視覚的密度を確認します。
2. ただコピーするのではなく、意図を読み取ります。ピクセル単位で正確な値ではなく、根底にあるシステムを抽出します。たとえば、12px、16px、24px のスペーシングがあれば、4px を基本単位とするスケールだと認識します。
3. デザインの個性に注目します。一般的なデザインと異なる特徴は何でしょうか？

パス C：Figma リンク

ユーザーが Figma ファイルの URL を提供します。

1. Figma MCP ツール（get_design_context、get_variable_defs、get_metadata）を使い、デザイントークンをプログラムで抽出します。
2. 色の変数、タイポグラフィスタイル、スペーシング値、角丸、シャドウの定義、コンポーネント構造を取得します。
3. 抽出した値を、以下のデザインシステム構成に整理します。

パス D：複合入力

ユーザーが複数の入力を組み合わせて提供します（例：「このスクリーンショットのようなものを、もっと暗く、よりミニマルに」）。すべての入力を組み合わせます。画像を出発点として、テキストによる変更を適用します。

出力構成

作成するすべてのデザインシステムには、以下の 4 つの成果物を必ず含めてください。

1. デザイントークン JSON（design-tokens.json）

これはシステムの機械可読な中核です。他の AI エージェントがこれを直接利用します。

{
  "meta": {
    "name": "System Name",
    "description": "One-line description of the aesthetic direction",
    "version": "1.0.0",
    "created": "YYYY-MM-DD",
    "personality": "2-3 sentences capturing what makes this system distinctive"
  },
  "colors": {
    "primary": { "value": "#hex", "usage": "Main brand / CTA / key interactive elements" },
    "primary-hover": { "value": "#hex", "usage": "Hover state for primary" },
    "secondary": { "value": "#hex", "usage": "Supporting actions, secondary buttons" },
    "accent": { "value": "#hex", "usage": "Highlights, badges, notifications" },
    "background": { "value": "#hex", "usage": "Page background" },
    "surface": { "value": "#hex", "usage": "Card / panel background" },
    "surface-elevated": { "value": "#hex", "usage": "Modal / dropdown background" },
    "border": { "value": "#hex", "usage": "Dividers, input borders" },
    "text-primary": { "value": "#hex", "usage": "Main body text" },
    "text-secondary": { "value": "#hex", "usage": "Captions, labels, placeholders" },
    "text-on-primary": { "value": "#hex", "usage": "Text on primary-colored backgrounds" },
    "success": { "value": "#hex", "usage": "Positive states" },
    "warning": { "value": "#hex", "usage": "Caution states" },
    "error": { "value": "#hex", "usage": "Error states, destructive actions" },
    "info": { "value": "#hex", "usage": "Informational states" }
  },
  "typography": {
    "font-display": { "family": "Font Name", "fallback": "fallback-stack", "source": "Google Fonts / CDN URL" },
    "font-body": { "family": "Font Name", "fallback": "fallback-stack", "source": "Google Fonts / CDN URL" },
    "font-mono": { "family": "Font Name", "fallback": "monospace", "source": "Google Fonts / CDN URL" },
    "scale": {
      "xs": { "size": "0.75rem", "lineHeight": "1rem", "usage": "Fine print, badges" },
      "sm": { "size": "0.875rem", "lineHeight": "1.25rem", "usage": "Captions, labels" },
      "base": { "size": "1rem", "lineHeight": "1.5rem", "usage": "Body text" },
      "lg": { "size": "1.125rem", "lineHeight": "1.75rem", "usage": "Lead text, card titles" },
      "xl": { "size": "1.25rem", "lineHeight": "1.75rem", "usage": "Section headers" },
      "2xl": { "size": "1.5rem", "lineHeight": "2rem", "usage": "Page headers" },
      "3xl": { "size": "1.875rem", "lineHeight": "2.25rem", "usage": "Hero titles" },
      "4xl": { "size": "2.25rem", "lineHeight": "2.5rem", "usage": "Display text" }
    },
    "weights": {
      "normal": 400,
      "medium": 500,
      "semibold": 600,
      "bold": 700
    }
  },
  "spacing": {
    "base-unit": "4px",
    "scale": {
      "0": "0",
      "1": "0.25rem",
      "2": "0.5rem",
      "3": "0.75rem",
      "4": "1rem",
      "5": "1.25rem",
      "6": "1.5rem",
      "8": "2rem",
      "10": "2.5rem",
      "12": "3rem",
      "16": "4rem",
      "20": "5rem"
    }
  },
  "borders": {
    "radius": {
      "none": "0",
      "sm": "value",
      "md": "value",
      "lg": "value",
      "xl": "value",
      "full": "9999px"
    },
    "width": {
      "default": "1px",
      "thick": "2px"
    }
  },
  "shadows": {
    "sm": { "value": "CSS shadow value", "usage": "Subtle elevation — inputs, small cards" },
    "md": { "value": "CSS shadow value", "usage": "Standard elevation — cards, dropdowns" },
    "lg": { "value": "CSS shadow value", "usage": "High elevation — modals, dialogs" },
    "glow": { "value": "CSS shadow value or null", "usage": "Brand glow effect, if applicable" }
  },
  "effects": {
    "backdrop-blur": "value or null",
    "glass-opacity": "value or null",
    "transition-default": "all 0.2s ease",
    "transition-slow": "all 0.4s ease"
  },
  "components": {
    "button": {
      "primary": { "bg": "token-ref", "text": "token-ref", "radius": "token-ref", "padding": "spacing-ref spacing-ref" },
      "secondary": { "bg": "token-ref", "text": "token-ref", "radius": "token-ref", "border": "token-ref" },
      "ghost": { "bg": "transparent", "text": "token-ref", "radius": "token-ref" }
    },
    "card": {
      "bg": "token-ref",
      "radius": "token-ref",
      "shadow": "token-ref",
      "padding": "spacing-ref",
      "border": "token-ref or none"
    },
    "input": {
      "bg": "token-ref",
      "border": "token-ref",
      "radius": "token-ref",
      "text": "token-ref",
      "placeholder": "token-ref",
      "focus-ring": "token-ref"
    }
  }
}

usage フィールドは重要です。値だけでなく、どのような場合に使うかも AI エージェントに伝えるためです。この JSON を読むエージェントが、曖昧さなくスタイル付きコンポーネントを生成できるようにしてください。

2. CSS 変数ファイル（design-system.css）

トークンを実装した、すぐに使える CSS ファイルです。

:root {
  /* Colors */
  --color-primary: #hex;
  --color-primary-hover: #hex;
  /* ... all color tokens ... */

  /* Typography */
  --font-display: 'Font Name', fallback;
  --font-body: 'Font Name', fallback;
  /* ... all type tokens ... */

  /* Spacing, borders, shadows, effects — all tokens as CSS variables */
}

ファイルの先頭に、Google Fonts または CDN リンクの @import 文を含めてください。デザインの方向性に応じて、基本的なダーク／ライトモードの切り替えも含めてください（@media (prefers-color-scheme: dark) または .dark クラスを使用）。

3. デザインシステム仕様書（design-system.md）

デザイン哲学とルールを説明する、人が読みやすい Markdown ドキュメントです。

• 概要：美的な方向性を2～3文で説明します。このシステムはどのような個性を伝えますか？
• カラーシステム：各色の16進数コード、視覚的な色見本（色付きの Unicode ブロック ████ を使用）、使用ルールを記載します。推奨事項と禁止事項を含めます。
• タイポグラフィ：フォントの組み合わせの根拠、使用例を含むサイズスケール全体、ウェイトの使用ルールを記載します。
• スペーシングとレイアウト：基本単位、スケール、レイアウトの原則（例：「8ポイントグリッドを使用する」「カードの内部余白は24pxにする」）を記載します。
• コンポーネントパターン：各コンポーネントトークンについて、視覚的なパターンと各バリアントの使いどころを説明します。
• AI エージェント向けの指示：AI コーディングエージェント向けに、従うべき最も重要なルールをまとめたセクションです。システムプロンプトに貼り付けられる程度に簡潔にします。

4. HTML プレビュー画面（design-system-preview.html）

CSS と JS をインラインに含む単一ファイルの HTML ページで、デザインシステム全体を視覚的に紹介します。

• 16進数コードとラベル付きのカラーパレット見本
• 実際に読み込んだフォントを使ったタイポグラフィスケールのサンプル
• スペーシングスケールの視覚化
• コンポーネントの例：ボタン（すべてのバリアント）、カード、入力欄、バッジ
• システムを使って全体を組み立てた例として、ミニアプリのレイアウト

このファイルではデザインシステムの CSS 変数を使用します。ドキュメントとしても、システムが機能することの証明としても活用できます。

品質基準

役に立つデザインシステムと汎用的なものとの違いは、次のとおりです。

カラー：無難で退屈な配色を安易に選ばないでください。フィンテックアプリだからといって青にする必要はありません。ヘルスケアアプリだからといって緑にする必要はありません。入力された内容の個性を出発点に、特徴のある色を選びます。すべての色でアクセシビリティに十分なコントラスト比を確保してください（WCAG AA の最低基準：テキストは4.5:1、大きなテキストや UI 要素は3:1）。

タイポグラフィ：個性のあるフォントを選びます。Inter と Roboto は使用禁止です。タイポグラフィにおける「AI スロップ」です。システムの個性に合ったフォントを探してください。必ず特徴的なディスプレイフォントと信頼性の高い本文フォントを組み合わせます。フォントが実際に読み込まれるよう、CDN／Google Fonts の URL を記載してください。

スペーシング：一貫した基本単位（通常は4pxまたは8px）から導きます。スケールは意図的に設計されていると感じられるものにします。値が多すぎると、システムとして成り立ちません。

コンポーネント：トークン参照で閉じたシステムを構成します。すべてのコンポーネント値は、直接値ではなくトークンを参照するようにします。これにより、システムを保守しやすくなります。

個性：作成するすべてのデザインシステムは、ほかのシステムとすぐに見分けられる必要があります。「ミニマルなヘルスケアアプリ」と「ミニマルなフィンテックアプリ」のデザインシステムを作ったなら、ひと目で違いが分かるようにします。その分野ならではの個性を前面に出してください。

ファイル構成

すべての出力をユーザーの作業ディレクトリに保存します。

design-system-{name}/
├── design-tokens.json
├── design-system.css
├── design-system.md
└── design-system-preview.html

{name} は、システム名から作成したケバブケースのスラッグです（例：design-system-aurora-dark）。

ほかのスキルとの連携

このスキルの出力は、AI エージェントが利用することを前提に設計されています。ユーザーがデザインシステムから実際の UI に進みたい場合は、次のようにします。

1. 次のプロンプトのコンテキストとして design-tokens.json と design-system.css を使うよう案内します。
2. design-system.md の「AI エージェント向けの指示」セクションは、システムプロンプトまたは CLAUDE.md にそのまま貼り付けられます。
3. HTML プレビューは視覚的な参照として使えます。ユーザーはスクリーンショットを撮って、ほかのツールに入力できます。

frontend-design スキルが利用できる場合は、そのスキルを使う際に design-tokens.json をコンテキストとして渡すよう提案します。これにより、汎用的な出力を避けるために必要な制約を frontend-design に与えられます。