---

name: design-system-builder description: デザインシステムをゼロから構築するスキル。トークン定義→CSS/Tailwind生成→コンポーネントスキャフォールド→Storybook→ドキュメント→変更管理までをワンストップで実行 user_invocable: true

Design System Builder

プロジェクトのデザインシステムをゼロから構築し、運用可能な状態まで立ち上げるスキル。

トリガー

「デザインシステムを作って」「デザイントークンを定義して」「コンポーネントライブラリを構築して」「UIの一貫性を確保したい」

ワークフロー概要

Phase 1: Discovery（現状把握）
Phase 2: Token Definition（トークン定義）
Phase 3: Token Export（CSS/Tailwind/JSON出力）
Phase 4: Component Scaffold（コンポーネント生成）
Phase 5: Storybook Integration（カタログ化）
Phase 6: Documentation（ドキュメント生成）
Phase 7: Governance（変更管理・lint）

ユーザーと対話しながら各フェーズを進める。フェーズはスキップ可能。

---

Phase 1: Discovery（現状把握）

プロジェクトの技術スタックと既存のデザイン状態を自動検出する。

1.1 スタック検出

以下を自動調査:

• package.json → React / Vue / Svelte / Angular / Next.js / Nuxt 等
• tailwind.config.* → Tailwind CSS バージョン・既存テーマ
• postcss.config.* → PostCSS プラグイン
• tsconfig.json → TypeScript 有無
• .storybook/ → Storybook 既存設定
• src/components/ or components/ → 既存コンポーネント構成
• CSS/SCSS ファイルのカラーコード・spacing値をスキャン

1.2 現状レポート生成

検出結果をユーザーに提示:

## プロジェクト分析結果

- **フレームワーク**: Next.js 15 + React 19
- **スタイリング**: Tailwind CSS v4
- **UI ライブラリ**: shadcn/ui (部分導入)
- **TypeScript**: あり
- **Storybook**: 未導入
- **既存カラー**: 12色がハードコード（#3B82F6 が 47箇所で使用）
- **既存spacing**: rem/px 混在（統一されていない）

### 推奨アプローチ
1. 既存ハードコード値をトークン化
2. Tailwind テーマとして統合
3. shadcn/ui のテーマ変数と接続

ユーザーに方針を確認してから次のフェーズへ進む。

---

Phase 2: Token Definition（トークン定義）

2.1 トークン設計の3層アーキテクチャ

Primitive Tokens（生の値）
  └→ Semantic Tokens（意味ベース）
       └→ Component Tokens（コンポーネント固有）

2.2 対話的トークン定義

ユーザーに質問して定義を進める:

カラー:

• ブランドカラー（primary）は何色か？（HEXまたは参考URL）
• ダークモード対応は必要か？
• ステータスカラー（success/warning/error/info）のカスタマイズは必要か？

タイポグラフィ:

• 見出し用フォント / 本文用フォント
• フォントサイズスケール: modular scale か custom か
• 行間・字間のこだわり

スペーシング:

• ベースユニット: 4px or 8px
• スケール方式: linear (4, 8, 12, 16...) or geometric

その他:

• 角丸（border-radius）のスタイル
• シャドウ（elevation）の段階数
• ブレイクポイント定義
• モーション・アニメーション方針

2.3 トークンファイル生成

定義内容を JSON (W3C Design Token Format) で出力:

design-tokens/
  primitive/
    colors.json       # 生の色値
    typography.json    # フォント・サイズ
    spacing.json       # スペーシング値
    radii.json         # 角丸
    shadows.json       # シャドウ
  semantic/
    colors.json        # brand, surface, text, status
    typography.json    # heading, body, caption
    spacing.json       # gap, padding, margin
  component/
    button.json        # ボタン固有トークン
    input.json         # 入力フィールド固有
    card.json          # カード固有

---

Phase 3: Token Export（CSS/Tailwind/JSON出力）

検出したスタックに応じて適切なフォーマットで出力。

3.1 CSS Custom Properties（全プロジェクト共通）

CSS カスタムプロパティのテンプレート: references/template-css-tokens.css

Primitive → Semantic → dark mode の3層でトークンを CSS 変数として定義する。

3.2 Tailwind CSS テーマ統合 / shadcn/ui マッピング

Tailwind v3/v4 および shadcn/ui への統合テンプレート: references/template-tailwind-integration.md

• Tailwind v4: @theme ディレクティブを使用
• Tailwind v3: tailwind.config.ts の extend を使用
• shadcn/ui: トークンを shadcn の CSS 変数にマッピング

---

Phase 4: Component Scaffold（コンポーネント生成）

4.1 コアコンポーネント一覧

ユーザーに必要なコンポーネントを確認。デフォルト推奨セット:

Primitives（基本要素）:

• Button（variants: primary, secondary, outline, ghost, destructive; sizes: sm, md, lg）
• Input（text, password, search + states: default, focus, error, disabled）
• Label
• Badge / Tag
• Avatar
• Icon wrapper

Composites（複合要素）:

• Card（header, body, footer）
• Dialog / Modal
• Dropdown / Select
• Toast / Notification
• Tooltip
• Tabs

Layout:

• Stack（vertical/horizontal with gap token）
• Container
• Grid

4.2 コンポーネント生成テンプレート

各コンポーネントは以下の構成で生成:

components/
  ui/
    button/
      button.tsx          # コンポーネント本体
      button.variants.ts  # cva() によるバリアント定義
      button.test.tsx     # ユニットテスト
      index.ts            # re-export

バリアント定義は class-variance-authority (cva) を使用。テンプレート: references/template-button-variants.ts

4.3 アクセシビリティ要件

全コンポーネントに必須:

• 適切な ARIA ロール・属性
• キーボードナビゲーション（Tab, Enter, Escape, Arrow keys）
• フォーカスリング（:focus-visible で制御、:focus は使わない）
• コントラスト比 WCAG AA 以上（通常テキスト 4.5:1、大テキスト 3:1）
• prefers-reduced-motion 対応

---

Phase 5: Storybook Integration（カタログ化）

5.1 Storybook セットアップ

未導入の場合:

npx storybook@latest init

5.2 ストーリー自動生成

各コンポーネントに対応する .stories.tsx を生成。テンプレート: references/template-button-story.tsx

5.3 トークンドキュメントページ

Storybook 内にデザイントークンの可視化ページを生成:

• カラーパレット一覧（スウォッチ表示）
• タイポグラフィスケール（実際のフォントサイズで表示）
• スペーシングスケール（ビジュアル表示）
• シャドウ・角丸のプレビュー

---

Phase 6: Documentation（ドキュメント生成）

6.1 デザインシステムドキュメント構成

docs/design-system/
  README.md              # 概要・導入ガイド
  tokens.md              # トークン一覧・命名規則
  components.md          # コンポーネントカタログ（使い方・Do/Don't）
  patterns.md            # UIパターン集（フォーム、ナビゲーション等）
  contributing.md        # コントリビューションガイド
  changelog.md           # 変更履歴

6.2 コンポーネントドキュメントテンプレート

各コ