デザインシステム スターター

視覚的な一貫性と優れたユーザー体験を確保する、堅牢でスケーラブルなデザインシステムを構築します。

---

クイックスタート

必要なことを説明するだけです：

Create a design system for my React app with dark mode support

これで完了です。このスキルはトークン、コンポーネント、アクセシビリティガイドラインを提供します。

---

トリガー

トリガー	例
デザインシステムを作成	"Create a design system for my app"
デザイントークン	"Set up design tokens for colors and spacing"
コンポーネントアーキテクチャ	"Design component structure using atomic design"
アクセシビリティ	"Ensure WCAG 2.1 compliance for my components"
ダークモード	"Implement theming with dark mode support"

---

クイックリファレンス

タスク	出力
デザイントークン	カラー、タイポグラフィ、スペーシング、シャドウ JSON
コンポーネント構造	アトミックデザイン階層 (atoms, molecules, organisms)
テーミング	CSS変数またはThemeProviderセットアップ
アクセシビリティ	WCAG 2.1 AA準拠パターン
ドキュメント	プロップ、例、a11yノート付きコンポーネント文書

---

バンドルリソース

• references/component-examples.md - 完全なコンポーネント実装
• templates/design-tokens-template.json - W3C デザイントークン形式
• templates/component-template.tsx - React コンポーネントテンプレート
• checklists/design-system-checklist.md - デザインシステム監査チェックリスト

---

デザインシステムの哲学

デザインシステムとは？

デザインシステムはコンポーネントライブラリ以上のものです。以下の集合です：

1. デザイントークン：基本的なデザイン決定 (カラー、スペーシング、タイポグラフィ)
2. コンポーネント：再利用可能なUIビルディングブロック
3. パターン：一般的なUXソリューションと構成
4. ガイドライン：ルール、原則、ベストプラクティス
5. ドキュメント：すべてを効果的に使用する方法

コア原則

1. 創造性より一貫性

• 予測可能なパターンは認知負荷を軽減
• ユーザーは一度学べば、どこでも適用可能
• デザイナーと開発者が同じ言語を話す

2. デフォルトでアクセシブル

• WCAG 2.1 Level AA準拠が最小要件
• キーボード操作がビルトイン
• スクリーンリーダーサポートから開始

3. スケーラブルで保守可能

• デザイントークンはグローバル変更を可能に
• コンポーネント構成は重複を削減
• バージョニングと廃止戦略

4. 開発者にやさしい

• 明確なAPIコントラクト
• 包括的なドキュメント
• 統合とカスタマイズが簡単

---

デザイントークン

デザイントークンはシステムのビジュアル言語を定義する、アトミックなデザイン決定です。

トークンカテゴリ

1. カラートークン

プリミティブカラー (生の値)：

{
  "color": {
    "primitive": {
      "blue": {
        "50": "#eff6ff",
        "100": "#dbeafe",
        "200": "#bfdbfe",
        "300": "#93c5fd",
        "400": "#60a5fa",
        "500": "#3b82f6",
        "600": "#2563eb",
        "700": "#1d4ed8",
        "800": "#1e40af",
        "900": "#1e3a8a",
        "950": "#172554"
      }
    }
  }
}

セマンティックカラー (文脈的な意味)：

{
  "color": {
    "semantic": {
      "brand": {
        "primary": "{color.primitive.blue.600}",
        "primary-hover": "{color.primitive.blue.700}",
        "primary-active": "{color.primitive.blue.800}"
      },
      "text": {
        "primary": "{color.primitive.gray.900}",
        "secondary": "{color.primitive.gray.600}",
        "tertiary": "{color.primitive.gray.500}",
        "disabled": "{color.primitive.gray.400}",
        "inverse": "{color.primitive.white}"
      },
      "background": {
        "primary": "{color.primitive.white}",
        "secondary": "{color.primitive.gray.50}",
        "tertiary": "{color.primitive.gray.100}"
      },
      "feedback": {
        "success": "{color.primitive.green.600}",
        "warning": "{color.primitive.yellow.600}",
        "error": "{color.primitive.red.600}",
        "info": "{color.primitive.blue.600}"
      }
    }
  }
}

アクセシビリティ：カラーコントラスト比がWCAG 2.1 Level AAを満たしていることを確認：

• 通常テキスト：最小 4.5:1
• 大きいテキスト (18pt 以上または 14pt 以上の太字)：最小 3:1
• UI コンポーネントとグラフィック：最小 3:1

2. タイポグラフィトークン

{
  "typography": {
    "fontFamily": {
      "sans": "'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif",
      "serif": "'Georgia', 'Times New Roman', serif",
      "mono": "'Fira Code', 'Courier New', monospace"
    },
    "fontSize": {
      "xs": "0.75rem",     // 12px
      "sm": "0.875rem",    // 14px
      "base": "1rem",      // 16px
      "lg": "1.125rem",    // 18px
      "xl": "1.25rem",     // 20px
      "2xl": "1.5rem",     // 24px
      "3xl": "1.875rem",   // 30px
      "4xl": "2.25rem",    // 36px
      "5xl": "3rem"        // 48px
    },
    "fontWeight": {
      "normal": 400,
      "medium": 500,
      "semibold": 600,
      "bold": 700
    },
    "lineHeight": {
      "tight": 1.25,
      "normal": 1.5,
      "relaxed": 1.75,
      "loose": 2
    },
    "letterSpacing": {
      "tight": "-0.025em",
      "normal": "0",
      "wide": "0.025em"
    }
  }
}

3. スペーシングトークン

スケール：一貫したスペーシングスケール (一般的に 4px または 8px ベース) を使用

{
  "spacing": {
    "0": "0",
    "1": "0.25rem",   // 4px
    "2": "0.5rem",    // 8px
    "3": "0.75rem",   // 12px
    "4": "1rem",      // 16px
    "5": "1.25rem",   // 20px
    "6": "1.5rem",    // 24px
    "8": "2rem",      // 32px
    "10": "2.5rem",   // 40px
    "12": "3rem",     // 48px
    "16": "4rem",     // 64px
    "20": "5rem",     // 80px
    "24": "6rem"      // 96px
  }
}

コンポーネント固有のスペーシング：

{
  "component": {
    "button": {
      "padding-x": "{spacing.4}",
      "padding-y": "{spacing.2}",
      "gap": "{spacing.2}"
    },
    "card": {
      "padding": "{spacing.6}",
      "gap": "{spacing.4}"
    }
  }
}

4. ボーダーラジウストークン

{
  "borderRadius": {
    "none": "0",
    "sm": "0.125rem",   // 2px
    "base": "0.25rem",  // 4px
    "md": "0.375rem",   // 6px
    "lg": "0.5rem",     // 8px
    "xl": "0.75rem",    // 12px
    "2xl": "1rem",      // 16px
    "full": "9999px"
  }
}

5. シャドウトークン

{
  "shadow": {
    "xs": "0 1px 2px 0 rgba(0, 0, 0, 0.05)",
    "sm": "0 1px 3px 0 rgba(0, 0, 0, 0.1), 0 1px 2px -1px rgba(0, 0, 0, 0.1)",
    "base": "0 4px 6px -1px rgba(0, 0, 0, 0.1), 0 2px 4px -2px rgba(0, 0, 0, 0.1)",
    "md": "0 10px 15px -3px rgba(0, 0, 0, 0.1), 0 4px 6px -4px rgba(0, 0, 0, 0.1)",
    "lg": "0 20px 25px -5px rgba(0, 0, 0, 0.1), 0 8px 10px -6px rgba(0, 0, 0, 0.1)",
    "xl": "0 25px 50px -12px rgba(0, 0, 0, 0.25)"
  }
}

---

コンポーネントアーキテクチャ

アトミックデザイン手法

Atoms → Molecules → Organisms → Templates → Pages

Atoms (プリミティブコンポーネント)

これ以上細分化できない基本的なビルディングブロック。

例：

• Button
• Input
• Label
• Icon
• Badge
• Avatar

Button コンポーネント：

interface ButtonProps {
  variant?: 'primary' | 'secondary' | 'outline' | 'ghost';
  size?: 'sm' | 'md' | 'lg';
  disabled?: boolean;
  loading?: boolean;
  icon?: React.ReactNode;
  children: React.ReactNode;
}

references/component-examples.md で、バリアント、サイズ、スタイリングパターンを含む完全な Button 実装を参照してください。

Molecules (シンプルな構成)

一緒に機能する atoms のグループ。

例：

• SearchBar (Input + Button)
• FormField (Label + Input + ErrorMessage)
• Card (Container + Title + Content + Actions)

FormField Molecule：

interface FormFieldProps {
  label: string;
  name: string;
  error?: string;
  hint?: string;
  required?: boolean;
  children: React.ReactNode;
}

references/component-examples.md で、FormField、Card (複合コンポーネントパターン)、Input (バリアント付き)、Modal など、さらに多くの構成例を参照してください。

Organisms (複雑な構成)

molecules と atoms で作られた複雑な UI コンポーネント。

例：

• Navigation Bar
• Product Card Grid
• User Profile Section
• Modal Dialog

Templates (ページレイアウト)

コンテンツの配置を定義するページレベルの構造。

例：

• Dashboard Layout (Sidebar + Header + Main Content)
• Marketing Page Layout (Hero + Features + Footer)
• Settings Page Layout (Tabs + Content Panels)

Pages (特定のインスタンス)

実際のコンテンツを持つ実際のページ。

---

コンポーネント API デザイン

Props ベストプラクティス

1. 予測可能なプロップ名

// ✅ 良い：一貫性のある命名
<Button variant="primary" size="md" />
<Input variant="outlined" size="md" />

// ❌ 悪い：不一貫
<Button type="primary" sizeMode="md" />
<Input style="outlined" inputSize="md" />

2. 適切なデフォルト値

// ✅ 良い：デフォルト値を提供
interface ButtonProps {
  variant?: 'primary' | 'secondary';  // デフォルト: primary
  size?: 'sm' | 'md' | 'lg';          // デフォルト: md
}

// ❌ 悪い：すべてが必須
interface ButtonProps {
  variant: 'primary' | 'secondary';
  size: 'sm' | 'md' | 'lg';
  color: string;
  padding: string;
}

3. 設定より構成

// ✅ 良い：構成可能
<Card>
  <Card.Header>
    <Card.Title>Title</Card.Title>
  </Card.Header>
  <Card.Body>Content</Card.Body>
  <Card.Footer>Actions</Card.Footer>
</Card>

// ❌ 悪い：プロップが多すぎる
<Card
  title="Title"
  content="Content"
  footerContent="Actions"
  hasHeader={true}
  hasFooter={true}
/>

4. ポリモーフィックコンポーネント コンポーネントが異なる HTML 要素としてレンダリングできるようにします：

<Button as="a" href="/login">Login</Button>
<Button as="button" onClick={handleClick}>Click Me</Button>

references/component-examples.md で、完全なポリモーフィックコンポーネント TypeScript パターンを参照してください。

---

テーミングとダークモード

テーム構造

interface Theme {
  colors: {
    brand: {
      primary: string;
      secondary: string;
    };
    text: {
      primary: string;
      secondary: string;
    };
    background: {
      primary: string;
      secondary: string;
    };
    feedback: {
      success: string;
      warning: string;
      error: string;
      info: string;
    };
  };
  typography: {
    fontFamily: {
      sans: string;
      mono: string;
    };
    fontSize: Record<string, string>;
  };
  spacing: Record<string, string>;
  borderRadius: Record<string, string>;
  shadow: Record<string, string>;
}

ダークモードの実装

アプローチ 1：CSS 変数

:root {
  --color-bg-primary: #ffffff;
  --color-text-primary: #000000;
}

[data-theme="dark"] {
  --color-bg-primary: #1a1a1a;
  --color-text-primary: #ffffff;
}

アプローチ 2：Tailwind CSS ダークモード

<div className="bg-white dark:bg-gray-900 text-gray-900 dark:text-white">
  Content
</div>

アプローチ 3：Styled Components ThemeProvider

const lightTheme = { background: '#fff', text: '#000' };
const darkTheme = { background: '#000', text: '#fff' };

<ThemeProvider theme={isDark ? darkTheme : lightTheme}>
  <App />
</ThemeProvider>

---

アクセシビリティガイドライン

WCAG 2.1 Level AA 準拠

カラーコントラスト

• 通常のテキスト (< 18pt)：最小 4.5:1
• 大きいテキスト (≥ 18pt または ≥ 14pt 太字)：最小 3:1
• UI コンポーネント：最小 3:1

ツール：WebAIM Contrast Checker のようなコントラストチェッカーを使用

キーボードナビゲーション

// ✅ すべてのインタラクティブ要素はキーボードアクセス可能である必要があります
<button
  onClick={handleClick}
  onKeyDown={(e) => e.key === 'Enter' && handleClick()}
>
  Click me
</button>

// ✅ フォーカス管理
<Modal>
  <FocusTrap>
    {/* Modal content */}
  </FocusTrap>
</Modal>

ARIA 属性

必須の ARIA パターン：

• aria-label：アクセシブルな名前を提供
• aria-expanded：展開/折りたたみ状態を通知
• aria-controls：コントロールをコンテンツに関連付け
• aria-live：動的なコンテンツの変更を通知

スクリーンリーダーサポート

• セマンティック HTML 要素 (<button>、<nav>、<main>) を使用
• インタラクティブ要素に対して div/span を多用することを避ける
• すべてのコントロールに意味のあるラベルを提供

references/component-examples.md で、スキップリンク、フォーカストラップ、ARIA パターンなどを含む完全なアクセシビリティ例を参照してください。

---

ドキュメント標準

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

各コンポーネントは以下を文書化する必要があります：

• 目的：コンポーネントの役割
• 使用方法：インポートステートメントと基本的な例
• バリアント：利用可能なビジュアルスタイル
• プロップ：型、デフォルト、説明を含む完全なプロップテーブル
• アクセシビリティ：キーボードサポート、ARIA 属性、スクリーンリーダーの動作
• 例：一般的なユースケースとコード

Storybook、Docusaurus、または同様のツールを使用して、インタラクティブなドキュメントを作成します。

templates/component-template.tsx で標準的なコンポーネント構造を参照してください。

---

デザインシステムワークフロー

1. デザイン段階

• 既存パターンの監査：矛盾を特定
• デザイントークンの定義：カラー、タイポグラフィ、スペーシング
• コンポーネントインベントリの作成：必要なコンポーネントのリストアップ
• Figma でのデザイン：コンポーネントライブラリの作成

2. 開発段階

• ツーリングのセットアップ：Storybook、TypeScript、テスト
• トークンの実装：CSS 変数またはテーマ設定
• まず atoms をビルド：プリミティブから開始
• 上へ構成：molecules、organisms をビルド
• 並行してドキュメント作成：コードと一緒にドキュメントを書く

3. 採用段階

• 移行ガイドの作成：チームの採用支援
• コードモッドの提供：可能な場合は移行を自動化
• ワークショップの開催：チームを使用方法で訓練
• フィードバック収集：実際の使用に基づいて反復

4. メンテナンス段階

• セマンティックバージョニング：メジャー/マイナー/パッチリリース
• 廃止戦略：古いコンポーネントを段階的に廃止
• 変更ログ：すべての変更を文書化
• 採用の監視：複数の製品での使用を追跡

---

クイックスタートチェックリスト

新しいデザインシステムを作成する場合：

• デザイン原則と価値を定義
• デザイントークン構造を確立 (カラー、タイポグラフィ、スペーシング)
• プリミティブカラーパレットを作成 (50-950 スケール)
• セマンティックカラートークンを定義 (ブランド、テキスト、背景、フィードバック)
• タイポグラフィスケールとフォントファミリーを設定
• スペーシングスケールを確立 (4px または 8px ベース)
• アトミックコンポーネントをデザイン (Button、Input、Label など)
• テーミングシステムを実装 (ライト/ダークモード)
• WCAG 2.1 Level AA 準拠を確保
• ドキュメント設定 (Storybook または同様)
• 各コンポーネントの使用例を作成
• バージョニングとリリース戦略を確立
• 採用チーム向けの移行ガイドを作成