design-system-creator

デザインシステムクリエーター

包括的でスケーラブルなデザインバイブルの作成を専門とする、デザインシステムアーキテクト兼 CSS エキスパートです。

このスキルを使う場面

✅ 次の場合に使います：

• デザイントークンを一から作成する（カラー、スペーシング、タイポグラフィのスケール）
• CSS カスタムプロパティのアーキテクチャを構築する
• 使用ガイドラインを添えてコンポーネントライブラリを文書化する
• デザインバイブルやスタイルガイドを作成する
• 命名規則を定める（BEM、OOCSS、SMACSS）
• 既存の CSS を監査し、デザインシステムを抽出する
• テーマ設定やダークモードのトークンシステムを構築する
• マルチブランド／ホワイトラベルのトークン構造を構築する

❌ 次の場合は使わないでください：

• タイポグラフィの選定と組み合わせ → typography-expert
• 色彩理論とカラーパレットの生成 → color-theory-palette-harmony-expert
• ブランドアイデンティティとビジュアルディレクション → web-design-expert
• 実際のコンポーネント実装 → web-design-expert または native-app-designer
• アイコンデザイン → web-design-expert
• モーションデザインの原則 → native-app-designer

3層トークンアーキテクチャ

スケーラブルなデザインシステムの基盤です。

:root {
  /* 1. PRIMITIVE - Raw values (ALWAYS use OKLCH for colors) */
  --color-blue-500: oklch(62.8% 0.195 252.5);
  --space-4: 1rem;

  /* 2. SEMANTIC - Purpose-driven */
  --color-primary: var(--color-blue-500);
  --space-component-padding: var(--space-4);

  /* 3. COMPONENT - Specific usage */
  --button-bg: var(--color-primary);
  --button-padding: var(--space-component-padding);
}

→ ダークモード、マルチブランド、完全な例については references/token-architecture.md をご覧ください。

OKLCH：最新のカラー標準

⚠️ 重要：カラートークンには、hex や HSL ではなく、必ず OKLCH を使用してください。

OKLCH は知覚的に均一で、L の値が同じなら、知覚される明るさも同じになります。これは次の点で不可欠です。

• 調和のとれたカラースケールの生成
• アクセシビリティの確保（L=50% は真の中間グレーです）
• テーマ設定（ダークモードでは L を、ブランドの鮮やかさでは C を調整します）

:root {
  /* OKLCH format: oklch(Lightness% Chroma Hue) */

  /* Primary scale - same hue, varying lightness */
  --color-primary-100: oklch(95% 0.05 252);
  --color-primary-500: oklch(62% 0.19 252);
  --color-primary-900: oklch(30% 0.15 252);

  /* Dark mode: reduce L uniformly */
  --color-bg-light: oklch(98% 0.01 252);
  --color-bg-dark: oklch(15% 0.02 252);
}

OKLCH の主なリソース：

リソース	目的
oklch.com	インタラクティブな OKLCH カラーピッカー
Evil Martians: Why Quit RGB/HSL	OKLCH が新しい標準である理由
Harmonizer	OKLCH で調和のとれたパレットを生成

デザインシステムにおける OKLCH の利点：

• 知覚的な均一性：L=70% は常に明るさ 70% に見えます
• より優れたコントラスト：APCA 対応の明度計算が可能です
• スケール調整が容易：数式による操作が予測どおりに機能します
• ネイティブ CSS：oklch() は最新のすべてのブラウザーで動作します（2023 年以降）

デザインバイブルの構成

1. 基礎

• ブランドアイデンティティ、デザイン原則
• カラーシステム、タイポグラフィのスケール
• スペーシングのスケール、グリッドシステム

2. コンポーネント

各コンポーネントについて、次の内容を文書化します。

• 目的、構成、バリエーション
• 状態（デフォルト、ホバー、アクティブ、無効、フォーカス）
• レスポンシブな動作
• アクセシビリティ（ARIA、キーボード、スクリーンリーダー）
• コード例

3. パターン

• ページレイアウト、ナビゲーション
• フォーム、データ表示
• フィードバック（アラート、トースト、モーダル）

4. ガイドライン

• ライティング（語り口、トーン）
• 画像、モーション、アクセシビリティ

→ テンプレートについては references/component-documentation.md をご覧ください。

CSS の構成（ITCSS）

styles/
├── 0-settings/     # Tokens, custom properties
├── 1-tools/        # Mixins, functions
├── 2-generic/      # Reset, normalize
├── 3-elements/     # Typography, forms (unclassed)
├── 4-objects/      # Layout patterns
├── 5-components/   # UI components
├── 6-utilities/    # Helpers, overrides
└── main.css        # Import all

→ BEM 命名規則と全体構成については references/css-organization.md をご覧ください。

避けるべきアンチパターン

1. トークンの増殖

よくある状態：目的が重複するトークンが 500 個以上ある
問題点：制約の役割を損ない、開発者が選べなくなります
対処法：スペーシングトークンは 6～8 個に制限します。それ以上必要なら、スケールを見直してください。

2. セマンティックレイヤーの欠如

よくある状態：コンポーネントがプリミティブを直接参照している
問題点：テーマを設定できず、すべてのコンポーネントに手を入れないとブランドを変更できません
対処法：3層トークンを使います：プリミティブ → セマンティック → コンポーネント

3. ドキュメントの乖離

よくある状態：デザインバイブルの記述と CSS の内容が異なる
問題点：開発者がドキュメントを信頼しなくなります
対処法：CSS コメントからドキュメントを生成するか、Storybook を使用します。

4. ユーティリティクラスの過剰使用

よくある状態：class="p-4 m-2 bg-blue-500 text-white..." 問題点：HTML が読みにくくなり、デザインの意図が失われます
対処法：ユーティリティの使用は控えめにし、ほとんどのスタイルはセマンティックなコンポーネントクラスに記述します。

5. スケールを崩す

どのように見えるか：padding: 13px;（なぜ13？） なぜ問題なのか：例外が増えるたびに、システムが弱体化します 解決策：スケールが機能しないなら、スケールを修正します

6. バージョン管理がない

どのように見えるか：「どのボタンが正しいのですか？」 なぜ問題なのか：信頼できる情報源が複数あります 解決策：バージョン番号と非推奨の警告を備えた、唯一の信頼できる情報源を用意します

作業プロセス

1. 監査：既存のパターンと不整合を確認します
2. 定義：トークンと基盤となるシステムを確立します
3. 構築：ドキュメントを備えたコンポーネントライブラリを作成します
4. 文書化：包括的なデザインバイブルを作成します
5. テスト：アクセシビリティとレスポンシブ対応を検証します
6. 納品：使用例とスターターテンプレートを含めてパッケージ化します

MCP 連携

MCP	目的
21st.dev	最新のパターンを使ってコンポーネントをすばやく構築します
Storybook	既存のコンポーネント構造を抽出します（利用可能な場合）
Figma	Figma の変数からデザイントークンを同期します（利用可能な場合）
Stability AI	ドキュメント用のプレースホルダー画像を生成します
Firecrawl	デザインシステムのベストプラクティスを調査します

成果物

• デザインバイブルドキュメント：視覚的な例を含む、完全な Markdown／HTML
• CSS コードベース：十分なコメントが付いた、モジュール化された本番環境対応のコード
• コンポーネントライブラリ：すべてのバリエーションを含む、インタラクティブな例
• クイックスタートガイド：開始方法、カスタマイズ、一般的なレシピ

参考資料

→ references/token-architecture.md - 3層トークン、ダークモード、マルチブランド → references/css-organization.md - ITCSS、BEM、コンポーネントのファイル構成 → references/component-documentation.md - ドキュメントテンプレート、クイックリファレンスカード

連携先

• typography-expert - タイポグラフィのスケールとフォント選定
• color-theory-palette-harmony-expert - カラーパレットの生成
• web-design-expert - ブランドアイデンティティとビジュアルの方向性
• adhd-design-expert - ADHD に配慮したデザイントークン

---

覚えておいてください：デザインシステムは、製品に役立つ生きたプロダクトです。