design-system-starter

Design System Starter

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

---

クイックスタート

必要なものを説明するだけです:

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

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

---

トリガー

トリガー	例
デザインシステムの作成	"自分のアプリ用のデザインシステムを作成して"
デザイントークン	"色とスペーシングのデザイントークンを設定して"
コンポーネントアーキテクチャ	"アトミックデザインを使ってコンポーネント構造を設計して"
アクセシビリティ	"自分のコンポーネントがWCAG 2.1に準拠していることを確認して"
ダークモード	"ダークモード対応のテーマを実装して"

---

クイックリファレンス

タスク	出力
デザイントークン	色、タイポグラフィ、スペーシング、シャドウのJSON
コンポーネント構造	アトミックデザインの階層（atoms、molecules、organisms）
テーマ設定	CSS変数またはThemeProviderのセットアップ
アクセシビリティ	WCAG 2.1 AA準拠のパターン
ドキュメント	props、例、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 レベル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 レベル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;
}

バリエーション、サイズ、スタイリングのパターンを含む完全なButtonの実装については、references/component-examples.md を参照してください。

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;
}

FormField、Card（複合コンポーネントパターン）、バリエーション付きInput、Modalなど、さらなる組み合わせ例については、references/component-examples.md を参照してください。

Organisms（複合コンポーネント）

分子（molecules）と原子（atoms）で構成される複雑な UI コンポーネントです。

例:

• ナビゲーションバー
• 製品カードグリッド
• ユーザープロフィールセクション
• モーダルダイアログ

Templates（ページレイアウト）

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

例:

• ダッシュボードレイアウト（サイドバー + ヘッダー + メインコンテンツ）
• マーケティングページレイアウト（ヒーロー + 機能紹介 + フッター）
• 設定ページレイアウト（タブ + コンテンツパネル）

Pages（具体的なインスタンス）

実際のコンテンツを含む実ページです。

---

コンポーネント API 設計

Props のベストプラクティス

1. 予測可能な prop 名

// ✅ Good: Consistent naming
<Button variant="primary" size="md" />
<Input variant="outlined" size="md" />

// ❌ Bad: Inconsistent
<Button type="primary" sizeMode="md" />
<Input style="outlined" inputSize="md" />

2. 適切なデフォルト値

// ✅ Good: Provides defaults
interface ButtonProps {
  variant?: 'primary' | 'secondary';  // Default: primary
  size?: 'sm' | 'md' | 'lg';          // Default: md
}

// ❌ Bad: Everything required
interface ButtonProps {
  variant: 'primary' | 'secondary';
  size: 'sm' | 'md' | 'lg';
  color: string;
  padding: string;
}

3. 設定よりも合成

// ✅ Good: Composable
<Card>
  <Card.Header>
    <Card.Title>Title</Card.Title>
  </Card.Header>
  <Card.Body>Content</Card.Body>
  <Card.Footer>Actions</Card.Footer>
</Card>

// ❌ Bad: Too many props
<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>

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

---

テーマとダークモード

テーマ構造

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 レベル AA 準拠

カラーコントラスト

• 通常のテキスト（18pt 未満）: 最低 4.5:1
• 大きいテキスト（18pt 以上、または 14pt 以上の太字）: 最低 3:1
• UI コンポーネント: 最低 3:1

ツール: WebAIM Contrast Checker などのコントラストチェッカーを使用してください

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

// ✅ All interactive elements must be keyboard accessible
<button
  onClick={handleClick}
  onKeyDown={(e) => e.key === 'Enter' && handleClick()}
>
  Click me
</button>

// ✅ Focus management
<Modal>
  <FocusTrap>
    {/* Modal content */}
  </FocusTrap>
</Modal>

ARIA 属性

基本的な ARIA パターン:

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

スクリーンリーダー対応

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

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

---

ドキュメント標準

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

各コンポーネントには以下を記載してください:

• 目的: コンポーネントが何をするか
• 使用方法: import 文と基本的な例
• バリアント: 利用可能な視覚スタイル
• Props: 型、デフォルト値、説明を含む完全な prop の表
• アクセシビリティ: キーボード対応、ARIA 属性、スクリーンリーダーの動作
• 例: コード付きの一般的なユースケース

インタラクティブなドキュメントには Storybook、Docusaurus などの類似ツールを使用してください。

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

---

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

1. デザインフェーズ

• 既存パターンの監査: 不整合を特定する
• デザイントークンの定義: 色、タイポグラフィ、スペーシング
• コンポーネントインベントリの作成: 必要なすべてのコンポーネントを一覧化する
• Figma でのデザイン: コンポーネントライブラリを作成する

2. 開発フェーズ

• ツール環境の構築: Storybook、TypeScript、テスト
• トークンの実装: CSS 変数またはテーマ設定
• まず原子を構築: プリミティブから始める
• 上位へ合成: 分子、organisms を構築する
• 開発と並行してドキュメント化: コードと一緒にドキュメントを書く

3. 導入フェーズ

• 移行ガイドの作成: チームの採用を支援する
• コードモッドの提供: 可能な場合は移行を自動化する
• ワークショップの実施: チームに使い方を教育する
• フィードバックの収集: 実際の利用状況に基づいて改善する

4. 保守フェーズ

• セマンティックバージョニング: メジャー/マイナー/パッチリリース
• 非推奨化の戦略: 古いコンポーネントを段階的に廃止する
• 変更履歴: すべての変更を文書化する
• 導入状況の監視: 製品全体での利用状況を追跡する

---

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

新しいデザインシステムを作成するときは、次の項目を確認してください。

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