ui-design-system

UI デザインシステム

概要

トークンファーストのアーキテクチャで、拡張性の高いデザインシステムを構築・保守します。このスキルでは、プリミティブデザイントークンからセマンティックマッピング、テーマ対応のコンポーネントライブラリまでの全パイプラインを扱い、Tailwind CSS v4、CSS カスタムプロパティ、レスポンシブデザインパターンに関する深い専門知識を活用します。

フェーズ 1：トークンの基盤

1. 既存のデザインアセット（色、フォント、間隔、シャドウ）を監査します
2. プリミティブトークン（セマンティックな意味を持たない生の値）を定義します
3. セマンティックトークンレイヤーを作成します（プリミティブを意図に対応付けます）
4. コンポーネントトークンレイヤーを構築します（セマンティクスをコンポーネントの各部分に対応付けます）

STOP — コンポーネントの構築前に、トークン階層をユーザーに提示してレビューを受けてください。

トークンレイヤーの選択表

レイヤー	目的	命名規則	例
プリミティブ	生の値、信頼できる唯一の情報源	--color-blue-500、--space-4	oklch(0.55 0.18 250)
セマンティック	目的や意図に対応付ける	--action-primary、--text-secondary	var(--color-blue-600)
コンポーネント	特定のコンポーネントにスコープを限定	--button-height-md、--card-radius	var(--space-4)

各レイヤーを作成するタイミング

状況	必要なレイヤー
新規プロジェクト	3 つすべて（プリミティブ + セマンティック + コンポーネント）
既存プロジェクトにダークモードを追加	セマンティック + コンポーネント（プリミティブを再マッピング）
ブランドカラーを更新	プリミティブのみ（セマンティック／コンポーネントは自動更新）
新しいコンポーネントを追加	コンポーネントのみ（既存のセマンティックを参照）
@theme を使った Tailwind プロジェクト	@theme でプリミティブ、CSS 変数でセマンティック

フェーズ 2：トークンの実装

レベル 1：プリミティブトークン

体系的な命名による生の値です。すべての値の信頼できる唯一の情報源です。

/* Colors — using OKLCH for perceptual uniformity */
--color-blue-50: oklch(0.97 0.01 250);
--color-blue-100: oklch(0.93 0.03 250);
--color-blue-500: oklch(0.55 0.18 250);
--color-blue-900: oklch(0.25 0.10 250);

/* Spacing — 4px base unit */
--space-1: 0.25rem;   /* 4px */
--space-2: 0.5rem;    /* 8px */
--space-3: 0.75rem;   /* 12px */
--space-4: 1rem;      /* 16px */
--space-6: 1.5rem;    /* 24px */
--space-8: 2rem;      /* 32px */
--space-12: 3rem;     /* 48px */
--space-16: 4rem;     /* 64px */

/* Typography */
--font-sans: 'Inter', system-ui, sans-serif;
--font-mono: 'Geist Mono', monospace;
--font-size-xs: 0.75rem;
--font-size-sm: 0.875rem;
--font-size-base: 1rem;
--font-size-lg: 1.125rem;
--font-size-xl: 1.25rem;
--font-size-2xl: 1.5rem;
--font-size-3xl: 1.875rem;
--font-size-4xl: 2.25rem;

/* Line Heights */
--leading-tight: 1.25;
--leading-normal: 1.5;
--leading-relaxed: 1.75;

/* Border Radius */
--radius-sm: 0.25rem;
--radius-md: 0.375rem;
--radius-lg: 0.5rem;
--radius-xl: 0.75rem;
--radius-2xl: 1rem;
--radius-full: 9999px;

/* Shadows */
--shadow-sm: 0 1px 2px 0 oklch(0 0 0 / 0.05);
--shadow-md: 0 4px 6px -1px oklch(0 0 0 / 0.1);
--shadow-lg: 0 10px 15px -3px oklch(0 0 0 / 0.1);

レベル 2：セマンティックトークン

プリミティブを目的に対応付けます。コンポーネントはこれらを参照します。

/* Surface */
--surface-primary: var(--color-white);
--surface-secondary: var(--color-gray-50);
--surface-elevated: var(--color-white);
--surface-overlay: oklch(0 0 0 / 0.5);

/* Text */
--text-primary: var(--color-gray-900);
--text-secondary: var(--color-gray-600);
--text-tertiary: var(--color-gray-400);
--text-inverse: var(--color-white);
--text-link: var(--color-blue-600);

/* Action */
--action-primary: var(--color-blue-600);
--action-primary-hover: var(--color-blue-700);
--action-secondary: var(--color-gray-100);
--action-danger: var(--color-red-600);

/* Border */
--border-default: var(--color-gray-200);
--border-strong: var(--color-gray-300);
--border-focus: var(--color-blue-500);

/* Status */
--status-success: var(--color-green-600);
--status-warning: var(--color-amber-500);
--status-error: var(--color-red-600);
--status-info: var(--color-blue-600);

レベル 3：コンポーネントトークン

特定のコンポーネントにスコープを限定します。

/* Button */
--button-height-sm: 2rem;
--button-height-md: 2.5rem;
--button-height-lg: 3rem;
--button-padding-x: var(--space-4);
--button-radius: var(--radius-md);
--button-font-weight: 500;

/* Input */
--input-height: 2.5rem;
--input-padding-x: var(--space-3);
--input-border: var(--border-default);
--input-border-focus: var(--border-focus);
--input-radius: var(--radius-md);

/* Card */
--card-padding: var(--space-6);
--card-radius: var(--radius-xl);
--card-shadow: var(--shadow-sm);
--card-border: var(--border-default);

フェーズ 3：コンポーネントアーキテクチャ

1. アトミックコンポーネント（Button、Input、Badge、Avatar）を特定します
2. モレキュールコンポーネント（FormField、SearchBar、Card）を定義します
3. オーガニズムコンポーネント（Header、Sidebar、DataTable）を構築します
4. コンポジションパターン（レイアウト、ページテンプレート）を確立します

STOP — バリアントの構築前に、コンポーネント一覧を提示してレビューを受けてください。

コンポーネントの複雑さに関する選択表

レベル	コンポーネント	構成
アトム	Button、Input、Badge、Avatar、Icon	子要素のない単一要素
モレキュール	FormField、SearchBar、Card、Tooltip	2～3 個のアトムを組み合わせる
オーガニズム	Header、Sidebar、DataTable、Modal	複数のモレキュール
テンプレート	DashboardLayout、AuthLayout	ページレベルの構成

バリアントパターン（CVA または Tailwind Variants を使用）

const buttonVariants = cva("inline-flex items-center justify-center rounded-md font-medium", {
  variants: {
    variant: {
      primary: "bg-action-primary text-white hover:bg-action-primary-hover",
      secondary: "bg-action-secondary text-text-primary hover:bg-gray-200",
      ghost: "hover:bg-action-secondary",
      danger: "bg-action-danger text-white hover:bg-red-700",
    },
    size: {
      sm: "h-8 px-3 text-sm",
      md: "h-10 px-4 text-sm",
      lg: "h-12 px-6 text-base",
    },
  },
  defaultVariants: {
    variant: "primary",
    size: "md",
  },
});

コンポジションパターン

• 複雑な UI（Tabs、Accordion、Combobox）には複合コンポーネントを使用します
• 柔軟なレイアウトにはスロットベースのコンポジションを使用します
• 最大限にカスタマイズできるよう、レンダープロップを使用します
• DOM にアクセスできるよう、ref をフォワードします

フェーズ 4：テーマ設定とレスポンシブ対応

1. トークンの切り替えによってライト／ダークテーマを実装します
2. コンテナクエリを使ったブレークポイントシステムを定義します
3. レスポンシブなコンポーネントバリアントを構築します
4. さまざまなビューポートとカラースキームでテストします

STOP — 完了を宣言する前に、テーマの切り替えが正しく動作することを確認してください。

Tailwind CSS v4 の設定

/* app.css — Tailwind v4 uses CSS-based config */
@import "tailwindcss";

@theme {
  --color-primary-50: oklch(0.97 0.01 250);
  --color-primary-500: oklch(0.55 0.18 250);
  --color-primary-600: oklch(0.48 0.18 250);
  --color-primary-700: oklch(0.40 0.18 250);

  --font-sans: 'Inter', system-ui, sans-serif;
  --font-mono: 'Geist Mono', monospace;

  --breakpoint-sm: 40rem;
  --breakpoint-md: 48rem;
  --breakpoint-lg: 64rem;
  --breakpoint-xl: 80rem;
}

ダーク／ライトテーマ

:root {
  color-scheme: light dark;
  --surface-primary: var(--color-white);
  --text-primary: var(--color-gray-900);
}

@media (prefers-color-scheme: dark) {
  :root {
    --surface-primary: var(--color-gray-950);
    --text-primary: var(--color-gray-50);
    --surface-elevated: var(--color-gray-900);
  }
}

/* Class-based override for manual toggle */
[data-theme="dark"] {
  --surface-primary: var(--color-gray-950);
  --text-primary: var(--color-gray-50);
}

レスポンシブデザインパターン

ブレークポイントシステム

Mobile-first approach:
Default    -> 0px+     (mobile)
sm         -> 640px+   (large phone / small tablet)
md         -> 768px+   (tablet)
lg         -> 1024px+  (laptop)
xl         -> 1280px+  (desktop)
2xl        -> 1536px+  (large desktop)

コンテナクエリ（コンポーネントではこちらを優先）

.card-container {
  container-type: inline-size;
  container-name: card;
}

@container card (min-width: 400px) {
  .card-content {
    flex-direction: row;
  }
}

レスポンシブパターンの選択表

パターン	モバイルでの動作	デスクトップでの動作
縦積みから横並びへ	垂直方向の列	水平方向の行
サイドバーの折りたたみ	ドロワーオーバーレイ	常時表示されるサイドバー
テーブルからカードへ	カードリスト	完全なデータテーブル
表示／非表示	付随コンテンツを非表示	すべてのコンテンツを表示
並べ替え	優先度の高いコンテンツを先頭に	標準の順序

検証チェックリスト

• すべての生の値にプリミティブトークンが定義されている
• セマンティックトークンがプリミティブを意図に対応付けている
• コンポーネントトークンがセマンティックトークンのみを参照している
• 適切なトークンの再マッピングを行うダークモードテーマ
• ブレークポイントシステムが定義されている（モバイルファースト）
• コンポーネント単位のレスポンシブ対応にコンテナクエリを使用している
• タイポグラフィのスケールが一貫した比率に従っている
• スペーシングのスケールが 4px／8px を基本単位としている
• フォーカス状態が視認可能で、アクセシブルである
• 色のコントラスト比が WCAG AA（4.5:1）を満たしている

アンチパターン／よくある間違い

アンチパターン	問題点	代わりに行うこと
コンポーネントに16進数値をハードコードする	テーマを変更できず、ダークモードにも対応できません	セマンティックトークンを使用する
色を反転させてダークモードを作成する	見た目が悪く、コントラストも不適切です	ダークモードに適した値にトークンを再マッピングする
システムを上書きするために !important を使用する	詳細度の競合を招き、保守が困難になります	カスケードを修正するか、データ属性を使用する
スペーシングの単位（px、rem、em）を混在させる	レイアウトに一貫性がなくなり、拡大縮小にも問題が生じます	どこでも rem を使用し、トークンを参照する
既存のコンポーネントを拡張せず、単発のコンポーネントを作成する	デザインシステムが分断されます	バリアントを使って既存のコンポーネントを拡張する
セマンティックレイヤーを省略する	プリミティブに密結合します	プリミティブ -> セマンティック -> コンポーネントの順に必ず対応付ける
コンポーネントでプリミティブトークンを直接使う	書き直さずにテーマを変更できません	コンポーネントではセマンティックトークンのみを参照する
コンポーネントにコンテナクエリを使用しない	コンポーネントが異なるコンテキストで崩れます	適応型コンポーネントにはコンテナクエリを使用する

統合ポイント

スキル	統合内容
ui-ux-pro-max	スタイル、パレット、UX のガイドラインを提供します
senior-frontend	React／Next.js でデザインシステムを実装します
canvas-design	データ可視化トークンとチャートのテーマ設定
mobile-design	モバイル向けに特化したトークンの調整
artifacts-builder	デザインシステムのプレビューアーティファクト
planning	デザインシステムを機能と同様に計画します

スキルの種類

柔軟 — プロジェクトですでに採用されている規約やツールに合わせて、トークンの命名、コンポーネントの構成、テーマ設定の方法を調整してください。3層のトークン階層（プリミティブ -> セマンティック -> コンポーネント）は強く推奨されますが、小規模なプロジェクトでは簡略化できます。