Design System Builder
デザインシステムとは、一度だけ決定を下し、すべての画面で再決定を行わないようにするためのものです。トークンが決定を保持し、コンポーネントがそれを適用し、ドキュメントが説明します。プロジェクトに合わせて規模を調整してください。週末アプリなら40行のトークンファイルとDESIGN.mdで十分です。複数チームのプロダクトでは、パイプラインとガバナンスが必要になります。小さく始めて、必要に応じて拡張していきます。
プロセス
0. 既存のものを確認する
次のものを探します：tokens/themeファイル、tailwind 設定または @theme ブロック、components.json、CSS変数、theme/ モジュール、Figmaリンク（Figma MCPが接続されている場合は get_variable_defs/search_design_system を使用）、DESIGN.md/.interface-design/system.md。既存のコードベースでは、発明する前に抽出します：実際に使用されている色、フォントサイズ、余白、角丸をgrepで取得し、クラスタリングして、統合されたスケールを提案します。ユーザーに変更前→変更後のマッピングを表示します。
1. 方向性を定義する（1段落）
誰が使うのか、どのような印象を与えるべきか（具体的な言葉で。「トレーディング端末のように密集している」「読書アプリのように落ち着いている」など）、プラットフォーム、ブランドの制約、密度、ライト/ダーク。これらの各選択が以下のすべてのスケールの選択を決定します。interface-design または frontend-design スキルが使用されている場合、これらのスキルがこの美的ステップを担当します。このスキルは方向性をシステムに変換します。
2. 基礎（トークン）
この順序で構築します。各トークンは前のトークンに依存します。
- カラー →
color-theoryスキルのツールを実行します：python3 <skills-dir>/color-theory/scripts/palette.py system <brand-hex> --format tailwind|css|json（color-theoryはこのスキルのディレクトリの兄弟です）。プリミティブランプと検証済みのライト/ダークセマンティックロールを生成します。 - タイポグラフィ → フォントファミリー（≤2、およびmono）、名前付きロールを持つタイプスケール、行高、ウェイト、トラッキング。
references/scales.mdを参照。 - スペース → 4pxベースグリッド。Tシャツサイズまたは数値スケール。レイアウトスペーシングとコンポーネントパディングを分離します。
- シェイプ → 半径スケール（ネストのルール：内側の半径 = 外側の半径 − パディング）、境界線の幅。
- エレベーション → シャドウスケール（ライト）とサーフェスの明度の段階（ダーク）、z-indexレイヤー。
- モーション → 持続時間＋イージングをトークンとして（および reduced-motion の動作）。
- レイアウト → ブレイクポイント、コンテナー幅、グリッドカラム、セーフエリア（モバイル）。
- サイジング → コントロールの高さ（sm/md/lg）、アイコンサイズ、最小タッチターゲット。
3. トークンアーキテクチャ
3つの階層。コンポーネントはセマンティック（またはコンポーネント）階層のみを消費する必要があります。
プリミティブ --blue-600, --space-4, --radius-2 生の値、WHAT（何か）で命名
セマンティック --color-accent, --space-inset-md, --radius-control JOB（役割）で命名、プリミティブをエイリアス、テーマごとに切り替え
コンポーネント --button-bg, --card-padding オプション。実際にテーマ設定が必要なコンポーネントのみ
テーマの切り替え（ダークモード、ブランド、密度、ハイコントラスト）＝セマンティックトークンの再ポイント。コンポーネントは決して変更しません。完全な命名規則、DTCGフォーマット、モード：references/token-architecture.md。
4. プラットフォームにデプロイする
- 単一のWebアプリ：手書きのCSS変数＋Tailwind v4
@themeで十分です。 - Web＋モバイル、または複数のアプリ：トークンをDTCG JSON（1つのソース）で作成し、Style Dictionary v5 または Terrazzo を使用してCSS、Tailwind、TS、Swift、Kotlin/Compose、Flutter、RNにビルドします。
プラットフォームごとのレシピと出力例：
references/platform-outputs.md。スターターDTCGファイル：assets/tokens.example.json。
5. コンポーネント
アクセシブルなプリミティブ上に構築します（ui-stack-advisor を参照）。一貫したAPI：variant（視覚的な意図）、size、必要に応じて tone/color、data属性による状態、構成よりもコンポジション。すべてのコンポーネントはすべての状態をドキュメント化します：デフォルト、ホバー、アクティブ、focus-visible、無効、ロード中、エラー、空、選択済み、読み取り専用。規約とチェックリスト：references/components.md。
6. ドキュメント化とガバナンス
プロジェクトルートに assets/DESIGN.template.md から DESIGN.md を作成します。方向性、トークンテーブル、コンポーネントインベントリ、Do/Don't、そして決定の理由を含めます。このファイルは将来のセッションが一貫性を保つために読み込むものです。短く、最新の状態に保ちます。大規模なシステムでは、Storybook（またはLadle/Histoire）、ビジュアルリグレッションテスト、セマンティックバージョニングによる変更ログ、コントリビューションプロセスを追加します（references/components.md#governance）。
デフォルト値（ユーザーに好みがない場合に機能する）
| 基礎 | デフォルト値 |
|---|---|
| 基本単位 | 4px。スペーシングスケール：0, 1, 2, 4, 6, 8, 12, 16, 20, 24, 32, 40, 48, 64, 80, 96 px |
| タイプスケール | 12, 14, 16 (本文), 18, 20, 24, 30, 36, 48, 60 px（≈1.2–1.25比率）。プロダクトUIは14px本文を使用可 |
| 行高 | 本文1.5、見出し1.2–1.3、ディスプレイ1.1。大きなサイズではトラッキングを詰める (-0.01～-0.03em) |
| 半径 | 0, 4, 6, 8, 12, 16, 24, full — 個性を選ぶ：シャープ (2–4)、ソフト (8–12)、ラウンド (16+) で一貫して適用 |
| コントロール | 高さ32 / 36–40 / 44–48 px。タッチターゲット ≥ 44pt (iOS) / 48dp (Android) / 24px min WCAG 2.2 (44を目標) |
| モーション | 100 / 150 / 200 / 300 / 500 ms。イーズアウト cubic-bezier(0.23,1,0.32,1) を出現に、イーズインアウトを動きに、スプリングはモバイルで |
| ブレイクポイント | 640, 768, 1024, 1280, 1536 (Tailwind)。コンポーネントにはコンテナクエリを優先 |
| エレベーション | 4〜5段階のシャドウ。ダークモードでは代わりに明るいサーフェス＋微妙な境界線を使用 |
| Z-index | base 0, ドロップダウン 1000, スティッキー 1100, オーバーレイ 1300, モーダル 1400, ポップオーバー 1500, トースト 1600, ツールチップ 1700 |
デフォルト値は下限であり、スタイルではありません。差別化は、変化する選択肢（書体、アクセント色、ニュートラルカラーの温度、半径の個性、密度、モーションの特性）から生まれます。
品質基準（完了とみなす前にチェックすること）
- コンポーネント内に生の値（16進数、pxフォントサイズ、任意のスペーシング）がないこと — grepで確認
- セマンティック名は値や色相ではなく、役割を説明していること
- ライト＋ダークの両方が設計され、コントラストが検証されていること（WCAG 2.2 AA）
- すべてのインタラクティブコンポーネントに、visible focus、disabled、loading、errorの各状態があること
- タイプスケールに名前付きロール（display, h1–h3, body, label, caption, code）があり、単なるサイズではないこと
- スペーシングが一貫していること：同じ関係 → 同じトークン
- モーショントークンにreduced-motionバリアントがあること
- DESIGN.mdが作成されており、正確であること
- モバイル：Dynamic Type / フォントスケーリングが尊重され、セーフエリアがトークン化され、タッチターゲットが ≥ 44/48であること
リファレンス
references/token-architecture.md— 階層、命名文法、DTCG 2025.10フォーマット、モード/テーマ、エイリアスルールreferences/scales.md— タイポグラフィ（スケール、可変タイプ、ペアリング）、スペーシング、半径、エレベーション、モーション、密度、ブレイクポイントreferences/platform-outputs.md— CSS、Tailwind v4、shadcnテーマ設定、React Native (NativeWind/Unistyles/Tamagui)、Flutter、SwiftUI、Compose、Style Dictionary/Terrazzoパイプラインreferences/components.md— コンポーネントAPI規約、アナトミー、状態マトリックス、コンポジション、ドキュメント、テスト、ガバナンスassets/tokens.example.json— スターターDTCGトークンファイルassets/DESIGN.template.md— DESIGN.mdテンプレート