design-system-architecture

デザインシステムのアーキテクチャ

適切なトークンアーキテクチャ、コンポーネント API、ドキュメント戦略を備えた、スケーラブルなデザインシステムを構築するための包括的なガイドです。

このスキルを使用する場面

• デザインシステムをゼロから作成する
• 既存のコンポーネントライブラリを進化させる
• トークンアーキテクチャを定義する
• コンポーネント API のパターンを確立する
• デザインシステムのドキュメントを整備する

トークンアーキテクチャ

3 層トークンシステム

┌─────────────────────────────────────┐
│       Component Tokens              │  → button-primary-bg
│     (Specific to components)        │
├─────────────────────────────────────┤
│       Semantic Tokens               │  → color-action-primary
│     (Purpose-based naming)          │
├─────────────────────────────────────┤
│       Primitive Tokens              │  → blue-500
│     (Raw values)                    │
└─────────────────────────────────────┘

トークンのカテゴリ

/* Primitive Tokens */
--color-blue-500: #3b82f6;
--spacing-4: 1rem;
--font-size-base: 16px;
--radius-md: 8px;

/* Semantic Tokens */
--color-action-primary: var(--color-blue-500);
--color-text-primary: var(--color-gray-900);
--spacing-component-gap: var(--spacing-4);

/* Component Tokens */
--button-bg: var(--color-action-primary);
--button-padding-x: var(--spacing-4);
--card-radius: var(--radius-md);

テーマのサポート

// tokens/themes.ts
export const lightTheme = {
  'color-bg-primary': 'var(--color-white)',
  'color-text-primary': 'var(--color-gray-900)',
  'color-border': 'var(--color-gray-200)',
}

export const darkTheme = {
  'color-bg-primary': 'var(--color-gray-900)',
  'color-text-primary': 'var(--color-gray-100)',
  'color-border': 'var(--color-gray-700)',
}

コンポーネント API のパターン

Prop API の設計

// ✅ Good: Clear, typed, with sensible defaults
interface ButtonProps {
  variant?: 'primary' | 'secondary' | 'ghost';
  size?: 'sm' | 'md' | 'lg';
  isLoading?: boolean;
  isDisabled?: boolean;
  leftIcon?: React.ReactNode;
  children: React.ReactNode;
  onClick?: () => void;
}

// ✅ With defaults
const Button = ({
  variant = 'primary',
  size = 'md',
  isLoading = false,
  isDisabled = false,
  ...props
}: ButtonProps) => { ... }

複合コンポーネントパターン

// Compound components for complex UIs
const Tabs = ({ children, defaultValue }) => { ... }
Tabs.List = ({ children }) => { ... }
Tabs.Tab = ({ value, children }) => { ... }
Tabs.Panel = ({ value, children }) => { ... }

// Usage
<Tabs defaultValue="tab1">
  <Tabs.List>
    <Tabs.Tab value="tab1">First</Tabs.Tab>
    <Tabs.Tab value="tab2">Second</Tabs.Tab>
  </Tabs.List>
  <Tabs.Panel value="tab1">Content 1</Tabs.Panel>
  <Tabs.Panel value="tab2">Content 2</Tabs.Panel>
</Tabs>

ポリモーフィックコンポーネント

// Component that can render as different elements
interface BoxProps<C extends React.ElementType> {
  as?: C;
  children?: React.ReactNode;
}

type PolymorphicProps<C extends React.ElementType> =
  BoxProps<C> & Omit<React.ComponentPropsWithoutRef<C>, keyof BoxProps<C>>;

const Box = <C extends React.ElementType = 'div'>({
  as,
  ...props
}: PolymorphicProps<C>) => {
  const Component = as || 'div';
  return <Component {...props} />;
};

// Usage
<Box as="section" className="...">Content</Box>
<Box as="button" onClick={...}>Click me</Box>

コンポーネントのカテゴリ（アトミックデザイン）

アトム（プリミティブ）

• Button、Input、Label、Icon
• タイポグラフィ（Text、Heading）
• Box、Flex、Grid（レイアウトのプリミティブ）

モレキュール（組み合わせ）

• FormField（Label + Input + Error）
• SearchInput（Input + Icon + Button）
• Card（Box + パディング + ボーダー）

オーガニズム（機能）

• Header（Logo + Nav + UserMenu）
• DataTable（Table + Pagination + Filters）
• Modal（Overlay + Card + Actions）

ドキュメント戦略

コンポーネントのドキュメント

# Button

Buttons trigger actions or navigate users.

## Usage

\`\`\`jsx
import { Button } from '@/components/ui'

<Button variant="primary" size="md">
  Click me
</Button>
\`\`\`

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| variant | 'primary' \| 'secondary' \| 'ghost' | 'primary' | Visual style |
| size | 'sm' \| 'md' \| 'lg' | 'md' | Size preset |

## Examples

### Variants
[Interactive examples]

### With Icons
[Interactive examples]

## Accessibility

- Uses `<button>` element by default
- Supports keyboard activation
- Loading state announced to screen readers

ベストプラクティス

デザイン原則

1. 設定よりもコンポジションを優先：小さく組み合わせ可能な要素を使います
2. 適切なデフォルト設定：すぐに使えます
3. デフォルトでアクセシブル：a11y は必須です
4. 型安全な API：TypeScript が使い方をガイドします
5. 最小限の API サーフェス：必要なものだけを公開します

メンテナンス

• 破壊的変更にはセマンティックバージョニングを適用します
• 削除前に非推奨の警告を表示します
• メジャーバージョン向けの移行ガイドを用意します
• ビジュアルリグレッションテストを自動化します

リソース

• Radix UI プリミティブ
• Chakra UI コンポーネントのパターン
• Design Tokens Community Group