ui-design-system

UI デザインシステム

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

---

目次

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

---

トリガー用語

次のような場合にこのスキルを使用します。

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

---

ワークフロー

ワークフロー 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
   • シャドウ：none から 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 以上

スタイルプリセット

項目	Modern	Classic	Playful
サンセリフフォント	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 要素を使用

開発者への引き継ぎ

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