design-system-patterns

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

Web アプリケーションとモバイルアプリケーション全体で、一貫性があり、保守しやすく、スケーラブルな UI の基盤を作り上げるためのデザインシステムアーキテクチャを習得します。

このスキルを使う場面

• 色、タイポグラフィ、余白、シャドウのデザイントークンを作成するとき
• CSS カスタムプロパティを使ってライト/ダークテーマの切り替えを実装するとき
• マルチブランドのテーマシステムを構築するとき
• 一貫した API を持つコンポーネントライブラリを設計するとき
• Figma トークンを使ったデザインからコードへのワークフローを確立するとき
• セマンティックトークンの階層（プリミティブ、セマンティック、コンポーネント）を作成するとき
• デザインシステムのドキュメントとガイドラインを整備するとき

主な機能

1. デザイントークン

• プリミティブトークン（生の値: 色、サイズ、フォント）
• セマンティックトークン（文脈上の意味: text-primary、surface-elevated）
• コンポーネントトークン（特定の用途: button-bg、card-border）
• トークンの命名規則と構成
• マルチプラットフォーム向けのトークン生成（CSS、iOS、Android）

2. テーマ基盤

• CSS カスタムプロパティのアーキテクチャ
• React におけるテーマコンテキストプロバイダー
• 動的なテーマ切り替え
• システム設定の検出（prefers-color-scheme）
• テーマ設定の永続化
• モーション低減モードとハイコントラストモード

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

• 複合コンポーネントパターン
• ポリモーフィックコンポーネント（as prop）
• バリアントとサイズのシステム
• スロットベースのコンポジション
• ヘッドレス UI パターン
• スタイルプロパティとレスポンシブバリアント

4. トークンパイプライン

• Figma からコードへの同期
• Style Dictionary の設定
• トークンの変換とフォーマット
• トークン更新のための CI/CD 統合

クイックスタート

// Design tokens with CSS custom properties
const tokens = {
  colors: {
    // Primitive tokens
    gray: {
      50: "#fafafa",
      100: "#f5f5f5",
      900: "#171717",
    },
    blue: {
      500: "#3b82f6",
      600: "#2563eb",
    },
  },
  // Semantic tokens (reference primitives)
  semantic: {
    light: {
      "text-primary": "var(--color-gray-900)",
      "text-secondary": "var(--color-gray-600)",
      "surface-default": "var(--color-white)",
      "surface-elevated": "var(--color-gray-50)",
      "border-default": "var(--color-gray-200)",
      "interactive-primary": "var(--color-blue-500)",
    },
    dark: {
      "text-primary": "var(--color-gray-50)",
      "text-secondary": "var(--color-gray-400)",
      "surface-default": "var(--color-gray-900)",
      "surface-elevated": "var(--color-gray-800)",
      "border-default": "var(--color-gray-700)",
      "interactive-primary": "var(--color-blue-400)",
    },
  },
};

詳細なパターンと実例

詳細なパターンのドキュメントは references/details.md にあります。上記のナビゲーション階層では不十分な場合は、そのファイルを参照してください。

ベストプラクティス

1. トークンは目的で命名する: 視覚的な説明（dark-gray）ではなく、セマンティックな名前（text-primary）を使用します
2. トークンの階層を維持する: プリミティブ > セマンティック > コンポーネントトークン
3. トークンの使用方法を文書化する: トークン定義とともに使用ガイドラインを含めます
4. トークンをバージョン管理する: トークンの変更を semver を用いた API の変更として扱います
5. テーマの組み合わせをテストする: すべてのテーマがすべてのコンポーネントで機能することを確認します
6. トークンパイプラインを自動化する: Figma からコードへの同期のための CI/CD
7. 移行パスを提供する: 明確な代替手段とともにトークンを段階的に非推奨にします

よくある問題

• トークンの乱立: 明確な階層のないトークンが多すぎる
• 一貫性のない命名: 規約の混在（camelCase と kebab-case）
• ダークモードの欠如: テーマの変更に適応しないトークン
• ハードコードされた値: トークンではなく生の値を使用している
• 循環参照: トークンがループ状に互いを参照している
• プラットフォームの不足: 一部のプラットフォーム向けのトークンが欠けている（Web にはあるがモバイルにはない）