ui-design-system

UI デザインシステム

デザイントークンを生成し、カラーパレットを作成し、タイポグラフィスケールを計算し、コンポーネントシステムを構築して、開発者向けの引き継ぎドキュメントを準備します。

---

目次

• トリガーとなる用語
• ワークフロー
  • ワークフロー 1：デザイントークンを生成する
  • ワークフロー 2：コンポーネントシステムを作成する
  • ワークフロー 3：レスポンシブデザイン
  • ワークフロー 4：開発者向けの引き継ぎ
• ツールのリファレンス
• クイックリファレンステーブル
• ナレッジベース

---

トリガーとなる用語

次のことが必要な場合に、このスキルを使用します。

• 「デザイントークンを生成」
• 「カラーパレットを作成」
• 「タイポグラフィスケールを構築」
• 「スペーシングシステムを計算」
• 「デザインシステムを作成」
• 「CSS 変数を生成」
• 「SCSS トークンをエクスポート」
• 「コンポーネントアーキテクチャを設定」
• 「コンポーネントライブラリを文書化」
• 「レスポンシブブレークポイントを計算」
• 「開発者向けの引き継ぎを準備」
• 「ブランドカラーをパレットに変換」
• 「WCAG コントラストを確認」
• 「8pt グリッドシステムを構築」

---

最初に確認すること

トークンやシステムを生成する前に、次の入力を確認してください。不明または曖昧な項目があれば、推測せずに質問してください。

• ブランドのプライマリカラー（hex） — パレット全体の基準となる色です（カラースケールと WCAG コントラストチェックに影響します）
• スタイルプリセット — modern、classic、または playful（フォント、角丸、シャドウのスタイルを決定します）
• 出力形式とフレームワーク — Tailwind/styled-components/Figma 向けの CSS、SCSS、または JSON（エクスポートと開発者向けの引き継ぎに影響します）

中断ルール：出力に最も大きく影響する 2～3 項目だけを質問してください。ユーザーが「とりあえず下書きを作って」と言った場合は作業を進め、成果物の冒頭に前提を列挙してください。

ワークフロー

ワークフロー 1：デザイントークンを生成する

状況： ブランドカラーがあり、完全なデザイントークンシステムが必要です。

手順：

1. ブランドカラーとスタイルを特定する

   • ブランドのプライマリカラー（hex 形式）
   • スタイルの希望：modern | classic | playful

2. スクリプトを使ってトークンを生成する

   python scripts/design_token_generator.py "#0066CC" modern json
   

3. 生成されたカテゴリを確認する

   • カラー：プライマリ、セカンダリ、ニュートラル、セマンティック、サーフェス
   • タイポグラフィ：fontFamily、fontSize、fontWeight、lineHeight
   • スペーシング：8pt グリッドベースのスケール（0～64）
   • ボーダー：radius、width
   • シャドウ：なしから 2xl まで
   • アニメーション：duration、easing
   • ブレークポイント：xs から 2xl まで

4. 対象の形式でエクスポートする

   # CSS custom properties
   python scripts/design_token_generator.py "#0066CC" modern css > design-tokens.css
   
   # SCSS variables
   python scripts/design_token_generator.py "#0066CC" modern scss > _design-tokens.scss
   
   # JSON for Figma/tooling
   python scripts/design_token_generator.py "#0066CC" modern json > design-tokens.json
   

5. アクセシビリティを検証する

   • 色のコントラストが WCAG AA（通常のテキストで 4.5:1、大きなテキストで 3:1）を満たしているか確認する
   • セマンティックカラーにコントラストカラーが定義されているか確認する

---

ワークフロー 2：コンポーネントシステムを作成する

状況： デザイントークンを使ってコンポーネントライブラリを構成する必要があります。

手順：

1. コンポーネントの階層を定義する

   • アトム：Button、Input、Icon、Label、Badge
   • モレキュール：FormField、SearchBar、Card、ListItem
   • オーガニズム：Header、Footer、DataTable、Modal
   • テンプレート：DashboardLayout、AuthLayout

2. トークンをコンポーネントに割り当てる

   コンポーネント	使用するトークン
   Button	カラー、サイズ、ボーダー、シャドウ、タイポグラフィ
   Input	カラー、サイズ、ボーダー、スペーシング
   Card	カラー、ボーダー、シャドウ、スペーシング
   Modal	カラー、シャドウ、スペーシング、z-index、アニメーション

3. バリアントのパターンを定義する

   サイズバリアント：

   sm: height 32px, paddingX 12px, fontSize 14px
   md: height 40px, paddingX 16px, fontSize 16px
   lg: height 48px, paddingX 20px, fontSize 18px
   

   カラーバリアント：

   primary: background primary-500, text white
   secondary: background neutral-100, text neutral-900
   ghost: background transparent, text neutral-700
   

4. コンポーネント API を文書化する

   • 型を含む Props インターフェース
   • バリアントのオプション
   • 状態の処理（ホバー、アクティブ、フォーカス、無効）
   • アクセシビリティ要件

5. 参照： references/component-architecture.md を参照してください

---

ワークフロー 3：レスポンシブデザイン

状況： ブレークポイント、可変フォントサイズ、またはレスポンシブな余白が必要です。

手順：

1. ブレークポイントを定義する

   名前	幅	対象
   xs	0	小型スマートフォン
   sm	480px	大型スマートフォン
   md	640px	タブレット
   lg	768px	小型ノートパソコン
   xl	1024px	デスクトップ
   2xl	1280px	大型画面

2. 可変フォントサイズを計算する

   数式：clamp(min, preferred, max)

   /* 16px to 24px between 320px and 1200px viewport */
   font-size: clamp(1rem, 0.5rem + 2vw, 1.5rem);
   

   事前計算済みのスケール：

   --fluid-h1: clamp(2rem, 1rem + 3.6vw, 4rem);
   --fluid-h2: clamp(1.75rem, 1rem + 2.3vw, 3rem);
   --fluid-h3: clamp(1.5rem, 1rem + 1.4vw, 2.25rem);
   --fluid-body: clamp(1rem, 0.95rem + 0.2vw, 1.125rem);
   

3. レスポンシブな余白を設定する

   トークン	モバイル	タブレット	デスクトップ
   --space-md	12px	16px	16px
   --space-lg	16px	24px	32px
   --space-xl	24px	32px	48px
   --space-section	48px	80px	120px

4. 参考： references/responsive-calculations.md を参照してください。

---

ワークフロー 4：開発チームへの引き継ぎ

状況： デザイントークンを開発チームに引き継ぐ必要があります。

手順：

1. 必要な形式でトークンをエクスポートする

   # For CSS projects
   python scripts/design_token_generator.py "#0066CC" modern css
   
   # For SCSS projects
   python scripts/design_token_generator.py "#0066CC" modern scss
   
   # For JavaScript/TypeScript
   python scripts/design_token_generator.py "#0066CC" modern json
   

2. フレームワークとの連携を準備する

   React + CSS Variables：

   import './design-tokens.css';
   
   <button className="btn btn-primary">Click</button>
   

   Tailwind Config：

   const tokens = require('./design-tokens.json');
   
   module.exports = {
     theme: {
       colors: tokens.colors,
       fontFamily: tokens.typography.fontFamily
     }
   };
   

   styled-components：

   import tokens from './design-tokens.json';
   
   const Button = styled.button`
     background: ${tokens.colors.primary['500']};
     padding: ${tokens.spacing['2']} ${tokens.spacing['4']};
   `;
   

3. Figma と同期する

   • Tokens Studio プラグインをインストールする
   • design-tokens.json をインポートする
   • トークンは Figma のスタイルと自動的に同期されます

4. 引き継ぎチェックリスト

   • トークンファイルをプロジェクトに追加済み
   • ビルドパイプラインを設定済み
   • テーマ／CSS 変数をインポート済み
   • コンポーネントライブラリを整合済み
   • ドキュメントを生成済み

5. 参考： references/developer-handoff.md を参照してください。

---

ツールのリファレンス

design_token_generator.py

ブランドカラーから完全なデザイントークンシステムを生成します。

引数	値	デフォルト	説明
brand_color	Hex color	#0066CC	ブランドのメインカラー
style	modern, classic, playful	modern	デザインスタイルのプリセット
format	json, css, scss, summary	json	出力形式

例：

# Generate JSON tokens (default)
python scripts/design_token_generator.py "#0066CC"

# Classic style with CSS output
python scripts/design_token_generator.py "#8B4513" classic css

# Playful style summary view
python scripts/design_token_generator.py "#FF6B6B" playful summary

出力カテゴリ：

カテゴリ	説明	主な値
colors	カラーパレット	primary, secondary, neutral, semantic, surface
typography	フォントシステム	fontFamily, fontSize, fontWeight, lineHeight
spacing	8pt グリッド	0-64 スケール、セマンティック（xs-3xl）
sizing	コンポーネントのサイズ	container, button, input, icon
borders	境界線の値	radius（スタイルごと）、width
shadows	影のスタイル	none から 2xl、inner
animation	モーションのトークン	duration, easing, keyframes
breakpoints	レスポンシブ	xs, sm, md, lg, xl, 2xl
z-index	レイヤーシステム	base から notification まで

---

クイックリファレンステーブル

カラースケールの生成

ステップ	明度	彩度	使用例
50	95% 固定	30%	控えめな背景
100	95% 固定	38%	明るい背景
200	95% 固定	46%	ホバー状態
300	95% 固定	54%	境界線
400	95% 固定	62%	無効状態
500	元の値	70%	ベース／デフォルトの色
600	元の値 × 0.8	78%	ホバー（暗色）
700	元の値 × 0.6	86%	アクティブ状態
800	元の値 × 0.4	94%	テキスト
900	元の値 × 0.2	100%	見出し

タイポグラフィスケール（1.25x の比率）

サイズ	値	計算
xs	10px	16 ÷ 1.25²
sm	13px	16 ÷ 1.25¹
base	16px	ベース
lg	20px	16 × 1.25¹
xl	25px	16 × 1.25²
2xl	31px	16 × 1.25³
3xl	39px	16 × 1.25⁴
4xl	49px	16 × 1.25⁵
5xl	61px	16 × 1.25⁶

WCAG のコントラスト要件

レベル	通常のテキスト	大きなテキスト
AA	4.5:1	3:1
AAA	7:1	4.5:1

大きなテキスト：通常の太さで ≥18pt、または太字で ≥14pt

スタイルプリセット

項目	モダン	クラシック	遊び心のあるスタイル
サンセリフフォント	Inter	Helvetica	Poppins
等幅フォント	Fira Code	Courier	Source Code Pro
標準の角丸	8px	4px	16px
シャドウ	重ねた控えめな影	単層	柔らかく、はっきりとした影

---

ナレッジベース

references/ にある詳細なリファレンスガイド：

ファイル	内容
token-generation.md	カラーアルゴリズム、HSV 色空間、WCAG コントラスト、タイポグラフィスケール
component-architecture.md	アトミックデザイン、命名規則、props パターン
responsive-calculations.md	ブレークポイント、流動的なタイポグラフィ、グリッドシステム
developer-handoff.md	エクスポート形式、フレームワークのセットアップ、Figma との同期

---

検証チェックリスト

トークン生成

• ブランドカラーが 16 進数形式で指定されている
• スタイルがプロジェクト要件に合っている
• すべてのトークンカテゴリが生成されている
• セマンティックカラーにコントラスト値が含まれている

コンポーネントシステム

• すべてのサイズが実装されている（sm、md、lg）
• すべてのバリエーションが実装されている（primary、secondary、ghost）
• すべての状態が機能している（hover、active、focus、disabled）
• デザイントークンのみを使用している（ハードコードされた値は使用していない）

アクセシビリティ

• 色のコントラストが WCAG AA を満たしている
• フォーカスインジケーターが視認できる
• タッチターゲットが 44×44px 以上である
• セマンティックな HTML 要素を使用している

開発者への引き継ぎ

• トークンが必要な形式でエクスポートされている
• フレームワークとの統合方法が文書化されている
• デザインツールと同期されている
• コンポーネントのドキュメントが完成している

---

トラブルシューティング

問題	原因	解決策
生成された色が WCAG コントラスト基準を満たさない	ブランドカラーが明るすぎる、または彩度が高すぎる	明るい背景上のテキストには、より暗い色合い（600 以上）を使用してください。コントラストツールで確認してください
トークンのエクスポートに誤った値が含まれる	書式指定の引数または色の構文が間違っている	16 進数カラーが引用符で囲まれていることを確認してください（例："#0066CC"）。形式が json、css、scss のいずれかであることを確認してください
タイポグラフィスケールが大きすぎる／小さすぎる	デフォルトの 1.25x の比率がデザインに合わない	DesignTokenGenerator クラスの type_scale_ratio を変更してください（より詰める場合は 1.125、より広げる場合は 1.333）
SCSS 変数が既存の変数と競合する	トークン名が重複している	すべてのトークンにプロジェクトの名前空間をプレフィックスとして付けてください（エクスポート関数を編集）
デザインツールで異なる色が表示される	カラースケール生成時の 16 進数の丸め	正式な値として JSON エクスポートを使用してください。Tokens Studio プラグインと同期してください
間隔の値がグリッドに合わない	独自の間隔と 8pt グリッドが混在している	生成された間隔システムの値のみを使用してください。任意のピクセル値は避けてください
ダークモードでシャドウトークンが不自然に見える	明るい背景用にシャドウが設計されている	不透明度を下げた値で、ダークモード専用のシャドウトークンを作成してください

---

成功基準

基準	目標	測定方法
トークンの一貫性	コードベース内のハードコードされた色／間隔の値がゼロである	Lint ルール違反の件数
WCAG AA 準拠	すべてのテキストカラーが 4.5:1 のコントラスト比を満たしている	自動コントラストチェッカーまたは手動監査
エクスポート形式の対応範囲	CSS、SCSS、JSON がすべて正しく生成される	各形式でジェネレーターを実行し、出力を検証する
デザインと開発の同期	トークン更新からコードのデプロイまで 24 時間未満	Figma の変更から本番環境への反映までの時間
コンポーネントのトークン適用率	コンポーネントの 100% がデザイントークンを使用している	コンポーネントのスタイルを監査し、ハードコードされた値を確認する
タイポグラフィの一貫性	すべてのテキストがデザインシステムのタイポグラフィスケールを使用している	すべてのページを目視で監査する
レスポンシブな動作	すべてのブレークポイントで流動的なタイポグラフィが機能する	xs、sm、md、lg、xl、2xl の幅でテストする

---

対象範囲と制限事項

対象範囲：

• ブランドカラーからの完全なデザイントークン生成
• カラーパレットの生成（プライマリ、セカンダリ、ニュートラル、セマンティック）
• モジュラースケールを使用したタイポグラフィシステム
• 8pt グリッドベースのスペーシングシステム
• コンポーネントのサイズ、境界線、シャドウ、アニメーションのトークン
• CSS カスタムプロパティ、SCSS 変数、JSON へのエクスポート
• レスポンシブブレークポイントの定義
• WCAG コントラスト参照テーブル

対象外：

• ダークモードのトークン生成（別途パレットのマッピングが必要です）
• アニメーション／モーションデザインライブラリ
• アイコンシステムの生成
• 実行時のテーマ切り替え実装
• Figma プラグインまたは API 連携（Tokens Studio を使用してください）
• ビジュアルリグレッションテスト
• デザインからコードへの変換（Figma Dev Mode または Locofy を使用してください）

---

連携ポイント

ツール／プラットフォーム	連携方法	用途
Figma / Tokens Studio	JSON 出力をトークンソースとしてインポート	デザインツールとコードトークンを同期
Tailwind CSS	JSON トークンを tailwind.config.js のテーマとして使用	デザインシステムから Tailwind を設定
styled-components / Emotion	JSON トークンをテーマプロバイダーにインポート	CSS-in-JS のテーマ設定
Style Dictionary	JSON 出力をソーストークンとして使用	マルチプラットフォーム向けのトークンビルド（iOS、Android、Web）
Storybook	トークンをコンポーネントストーリーと組み合わせる	コンポーネントの視覚的なバリエーションをドキュメント化
CI/CD	ビルドパイプラインでトークンを生成	ブランド変更時にトークンを自動更新