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

デザインシステムアーキテクチャをマスターして、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 プロパティ）
• バリアントとサイズシステム
• スロットベースの構成
• ヘッドレス UI パターン
• スタイルプロパティと応答性バリアント

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

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

クイックスタート

// CSS カスタムプロパティを使用したデザイントークン
const tokens = {
  colors: {
    // プリミティブトークン
    gray: {
      50: "#fafafa",
      100: "#f5f5f5",
      900: "#171717",
    },
    blue: {
      500: "#3b82f6",
      600: "#2563eb",
    },
  },
  // セマンティックトークン（プリミティブを参照）
  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)",
    },
  },
};

キーパターン

パターン 1：トークン階層

/* レイヤー 1：プリミティブトークン（生の値） */
:root {
  --color-blue-500: #3b82f6;
  --color-blue-600: #2563eb;
  --color-gray-50: #fafafa;
  --color-gray-900: #171717;

  --space-1: 0.25rem;
  --space-2: 0.5rem;
  --space-4: 1rem;

  --font-size-sm: 0.875rem;
  --font-size-base: 1rem;
  --font-size-lg: 1.125rem;

  --radius-sm: 0.25rem;
  --radius-md: 0.5rem;
  --radius-lg: 1rem;
}

/* レイヤー 2：セマンティックトークン（意味） */
:root {
  --text-primary: var(--color-gray-900);
  --text-secondary: var(--color-gray-600);
  --surface-default: white;
  --interactive-primary: var(--color-blue-500);
  --interactive-primary-hover: var(--color-blue-600);
}

/* レイヤー 3：コンポーネントトークン（具体的な使用法） */
:root {
  --button-bg: var(--interactive-primary);
  --button-bg-hover: var(--interactive-primary-hover);
  --button-text: white;
  --button-radius: var(--radius-md);
  --button-padding-x: var(--space-4);
  --button-padding-y: var(--space-2);
}

パターン 2：React でのテーマ切り替え

import { createContext, useContext, useEffect, useState } from "react";

type Theme = "light" | "dark" | "system";

interface ThemeContextValue {
  theme: Theme;
  resolvedTheme: "light" | "dark";
  setTheme: (theme: Theme) => void;
}

const ThemeContext = createContext<ThemeContextValue | null>(null);

export function ThemeProvider({ children }: { children: React.ReactNode }) {
  const [theme, setTheme] = useState<Theme>(() => {
    if (typeof window !== "undefined") {
      return (localStorage.getItem("theme") as Theme) || "system";
    }
    return "system";
  });

  const [resolvedTheme, setResolvedTheme] = useState<"light" | "dark">("light");

  useEffect(() => {
    const root = document.documentElement;

    const applyTheme = (isDark: boolean) => {
      root.classList.remove("light", "dark");
      root.classList.add(isDark ? "dark" : "light");
      setResolvedTheme(isDark ? "dark" : "light");
    };

    if (theme === "system") {
      const mediaQuery = window.matchMedia("(prefers-color-scheme: dark)");
      applyTheme(mediaQuery.matches);

      const handler = (e: MediaQueryListEvent) => applyTheme(e.matches);
      mediaQuery.addEventListener("change", handler);
      return () => mediaQuery.removeEventListener("change", handler);
    } else {
      applyTheme(theme === "dark");
    }
  }, [theme]);

  useEffect(() => {
    localStorage.setItem("theme", theme);
  }, [theme]);

  return (
    <ThemeContext.Provider value={{ theme, resolvedTheme, setTheme }}>
      {children}
    </ThemeContext.Provider>
  );
}

export const useTheme = () => {
  const context = useContext(ThemeContext);
  if (!context) throw new Error("useTheme must be used within ThemeProvider");
  return context;
};

パターン 3：CVA を使用したバリアントシステム

import { cva, type VariantProps } from "class-variance-authority";
import { cn } from "@/lib/utils";

const buttonVariants = cva(
  // ベーススタイル
  "inline-flex items-center justify-center rounded-md font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 disabled:pointer-events-none disabled:opacity-50",
  {
    variants: {
      variant: {
        default: "bg-primary text-primary-foreground hover:bg-primary/90",
        destructive:
          "bg-destructive text-destructive-foreground hover:bg-destructive/90",
        outline:
          "border border-input bg-background hover:bg-accent hover:text-accent-foreground",
        secondary:
          "bg-secondary text-secondary-foreground hover:bg-secondary/80",
        ghost: "hover:bg-accent hover:text-accent-foreground",
        link: "text-primary underline-offset-4 hover:underline",
      },
      size: {
        sm: "h-9 px-3 text-sm",
        md: "h-10 px-4 text-sm",
        lg: "h-11 px-8 text-base",
        icon: "h-10 w-10",
      },
    },
    defaultVariants: {
      variant: "default",
      size: "md",
    },
  },
);

interface ButtonProps
  extends
    React.ButtonHTMLAttributes<HTMLButtonElement>,
    VariantProps<typeof buttonVariants> {
  asChild?: boolean;
}

export function Button({ className, variant, size, ...props }: ButtonProps) {
  return (
    <button
      className={cn(buttonVariants({ variant, size, className }))}
      {...props}
    />
  );
}

パターン 4：Style Dictionary 設定

// style-dictionary.config.js
module.exports = {
  source: ["tokens/**/*.json"],
  platforms: {
    css: {
      transformGroup: "css",
      buildPath: "dist/css/",
      files: [
        {
          destination: "variables.css",
          format: "css/variables",
          options: {
            outputReferences: true, // トークン参照を保持
          },
        },
      ],
    },
    scss: {
      transformGroup: "scss",
      buildPath: "dist/scss/",
      files: [
        {
          destination: "_variables.scss",
          format: "scss/variables",
        },
      ],
    },
    ios: {
      transformGroup: "ios-swift",
      buildPath: "dist/ios/",
      files: [
        {
          destination: "DesignTokens.swift",
          format: "ios-swift/class.swift",
          className: "DesignTokens",
        },
      ],
    },
    android: {
      transformGroup: "android",
      buildPath: "dist/android/",
      files: [
        {
          destination: "colors.xml",
          format: "android/colors",
          filter: { attributes: { category: "color" } },
        },
      ],
    },
  },
};

ベストプラクティス

1. 目的でトークンに名前を付ける：ビジュアルな説明（dark-gray）ではなくセマンティック名（text-primary）を使用する
2. トークン階層を維持する：プリミティブ > セマンティック > コンポーネントトークン
3. トークン使用法を記述する：トークン定義に使用ガイドラインを含める
4. トークンをバージョン管理する：トークン変更を semver を使用した API 変更として扱う
5. テーマの組み合わせをテストする：すべてのテーマがすべてのコンポーネントで機能することを確認する
6. トークンパイプラインを自動化する：Figma からコードへの同期用の CI/CD
7. 移行パスを提供する：明確な代替案を示してトークンを段階的に廃止する

一般的な問題

• トークンの拡散：明確な階層がない多すぎるトークン
• 命名の不一貫性：混合された命名規則（camelCase vs kebab-case）
• ダークモードの欠落：テーマ変更に対応しないトークン
• ハードコードされた値：トークンの代わりに生の値を使用する
• 循環参照：トークンがループで相互に参照している
• プラットフォーム間のギャップ：一部のプラットフォーム（Web だけでなくモバイルも）でトークンが欠落している