design-tokens

デザイントークン

推測ではなく、計算に基づいてタイポグラフィのスケール、カラーパレット、スペーシングシステム、ダークモード用の派生色を生成します。WCAG コントラストチェック、体系的なスペーシンググリッド、本番環境ですぐに使える CSS／Tailwind の出力も含まれます。

使用するタイミング

• 新しいプロジェクトのデザインシステムを設定するとき
• タイポグラフィのスケール、カラーパレット、スペーシングシステムを求められたとき
• WCAG に準拠した色の組み合わせが必要なとき
• ライトパレットからダークモードの色を派生させたいとき
• 「デザイントークン」や「テーマ設定」を求められたとき
• Tailwind の設定や CSS カスタムプロパティを構築するとき

基本理念

• 好みより計算を重視します。 スケールは任意の値ではなく、比率に基づくべきです。
• アクセシビリティをデフォルトにします。 すべてのテキストと背景の組み合わせは WCAG AA に適合する必要があります。
• 体系的にします。 すべての値は、基準値と比率から導き出せるべきです。
• 移植性を重視します。 CSS カスタムプロパティ、Tailwind の設定、または JSON トークンとして出力します。

---

タイポグラフィスケールの生成

計算式

fontSize = baseFontSize × ratio^step

推奨比率

比率	名前	値	最適な用途
Minor Second	1.067	差が小さく控えめ	高密度の UI、ダッシュボード
Major Second	1.125	緩やかな変化	アプリ、データ量の多いインターフェース
Minor Third	1.200	バランスがよく汎用的	ほとんどのウェブサイト、SaaS
Major Third	1.250	明確な階層	マーケティングサイト、ブログ
Perfect Fourth	1.333	強いコントラスト	エディトリアル、ランディングページ
Augmented Fourth	1.414	印象的	大胆なデザイン、ポートフォリオ
Perfect Fifth	1.500	非常に印象的	ヒーロー要素を多用するデザイン

スケールの生成

基準サイズ（通常は 16px）と比率を指定します。

Step -2: 16 / ratio² = xs
Step -1: 16 / ratio  = sm
Step  0: 16          = base
Step  1: 16 × ratio  = lg
Step  2: 16 × ratio² = xl
Step  3: 16 × ratio³ = 2xl
Step  4: 16 × ratio⁴ = 3xl
Step  5: 16 × ratio⁵ = 4xl
Step  6: 16 × ratio⁶ = 5xl

最も近い 0.5px 単位に丸めるか、rem に変換します（÷ 16）。

行の高さのルール

フォントサイズ	行の高さ	用途
≤ 14px	1.6–1.7	小さなテキスト、キャプション
16–20px	1.5–1.6	本文
20–32px	1.3–1.4	小見出し
32–48px	1.1–1.2	見出し
48px+	1.0–1.1	ディスプレイ／ヒーローテキスト

目安： フォントサイズが大きくなるほど、行の高さは小さくします。

文字間隔のルール

サイズ	文字間隔	理由
小さなテキスト（≤14px）	0.01–0.02em	読みやすさのためにわずかに広げます
本文	0em（標準）	調整しません
小見出し	-0.01em	わずかに詰めます
見出し	-0.02em 〜 -0.03em	サイズが大きくなるほど詰めます
ディスプレイテキスト	-0.03em 〜 -0.05em	大きなサイズでは文字間隔を詰めます

フォントウェイトの組み合わせ

役割	ウェイト	Tailwind
本文	400（レギュラー）	font-normal
本文の強調	500（ミディアム）	font-medium
小見出し	600（セミボールド）	font-semibold
見出し	700（ボールド）	font-bold
ディスプレイ	800（エクストラボールド）	font-extrabold

出力例（CSS カスタムプロパティ）

:root {
  --font-size-xs: 0.694rem;    /* 11.1px */
  --font-size-sm: 0.833rem;    /* 13.3px */
  --font-size-base: 1rem;      /* 16px */
  --font-size-lg: 1.2rem;      /* 19.2px */
  --font-size-xl: 1.44rem;     /* 23px */
  --font-size-2xl: 1.728rem;   /* 27.6px */
  --font-size-3xl: 2.074rem;   /* 33.2px */
  --font-size-4xl: 2.488rem;   /* 39.8px */
  --font-size-5xl: 2.986rem;   /* 47.8px */
}

---

カラーパレットの生成

ステップ 1：ベースカラーを選ぶ

すべてのパレットには次の要素が必要です。

トークン	目的	例
primary	メインのブランドカラー、CTA	ブランドカラー
neutral	テキスト、境界線、背景	グレー（暖色系／寒色系／純色）
success	肯定的な状態	緑
warning	注意が必要な状態	琥珀色／黄色
error	破壊的な状態	赤
info	情報の提示	青（primary と兼用可）

ステップ 2：色合いのスケールを生成する（50–950）

各ベースカラーについて、10 段階の色合いのスケールを生成します。ベースカラーは通常、500 の段階に設定します。

方法：HSL の調整

ベースとなる HSL 値を起点にします。

段階	明度の調整	彩度の調整
50	+45%	-30%
100	+38%	-25%
200	+28%	-15%
300	+18%	-5%
400	+8%	0%
500	0%（ベース）	0%（ベース）
600	-8%	+5%
700	-18%	+5%
800	-28%	0%
900	-38%	-10%
950	-45%	-20%

すべての値を次の範囲内に収めます。明度は 0–100%、彩度は 0–100% です。

ステップ 3：セマンティックトークンへの割り当て

色合いの各段階をセマンティックな役割に割り当てます。

/* Light mode */
--color-bg: var(--neutral-50);
--color-bg-subtle: var(--neutral-100);
--color-bg-muted: var(--neutral-200);
--color-border: var(--neutral-200);
--color-border-strong: var(--neutral-300);
--color-text-muted: var(--neutral-500);
--color-text-subtle: var(--neutral-600);
--color-text: var(--neutral-900);
--color-text-heading: var(--neutral-950);

--color-primary: var(--primary-600);
--color-primary-hover: var(--primary-700);
--color-primary-bg: var(--primary-50);
--color-primary-text: white;

---

WCAG コントラストチェック

計算式

コントラスト比 = (L1 + 0.05) / (L2 + 0.05)

ここで、L1 = 相対輝度が高い色、L2 = 相対輝度が低い色です。

相対輝度

For each channel (R, G, B):
  sRGB = channel / 255
  linear = sRGB <= 0.04045 ? sRGB / 12.92 : ((sRGB + 0.055) / 1.055) ^ 2.4

L = 0.2126 × R_linear + 0.7152 × G_linear + 0.0722 × B_linear

WCAG 要件

レベル	比率	適用対象
AA 通常テキスト	≥ 4.5:1	本文テキスト（< 18px または < 14px 太字）
AA 大きなテキスト	≥ 3:1	≥ 18px の通常テキスト、または ≥ 14px の太字テキスト
AAA 通常テキスト	≥ 7:1	より高いアクセシビリティ
AA UI コンポーネント	≥ 3:1	ボーダー、アイコン、フォーカスリング

クイックリファレンス（白 #FFFFFF に対するニュートラルカラー）

シェード	おおよそのコントラスト	適合状況
300	~2.5:1	❌ 装飾用途のみ
400	~3.5:1	✅ 大きなテキスト、UI
500	~4.5:1	✅ AA 本文テキスト
600	~6:1	✅ AA に余裕をもって適合
700	~8:1	✅ AAA 本文テキスト

プログラムでコントラストを確認する

パレットを生成するときは、必ず次を確認してください。

1. text (900) を bg (50) 上に配置 → 4.5:1 以上であること
2. text-muted (500) を bg (50) 上に配置 → 4.5:1 以上であること
3. primary (600) を white 上に配置 → 4.5:1 以上であること
4. primary-text を primary (600) 上に配置 → 4.5:1 以上であること
5. border (200) を bg (50) 上に配置 → 3:1 以上であること

組み合わせが基準を満たさない場合は、満たすまで暗い色を1段階ずつ暗くしてください。

---

スペーシングシステム

4を基準とするスケール（推奨）

すべてを4pxの倍数にします。予測しやすく、一貫性があり、ほとんどのフォントサイズに適しています。

:root {
  --space-0: 0px;
  --space-0.5: 2px;
  --space-1: 4px;
  --space-1.5: 6px;
  --space-2: 8px;
  --space-3: 12px;
  --space-4: 16px;
  --space-5: 20px;
  --space-6: 24px;
  --space-8: 32px;
  --space-10: 40px;
  --space-12: 48px;
  --space-16: 64px;
  --space-20: 80px;
  --space-24: 96px;
  --space-32: 128px;
}

これは Tailwind のデフォルトスケールと完全に一致します。

スペーシングの使用ガイド

コンテキスト	スペーシング	値
インラインアイコンの間隔	space-1 から space-2	4–8px
ボタンのパディング	space-2 × space-4	8px 16px
カードのパディング	space-4 から space-6	16–24px
セクション間の間隔（要素間）	space-6 から space-8	24–32px
セクションのパディング（コンテナー）	space-12 から space-16	48–64px
ページのセクション間の垂直リズム	space-16 から space-24	64–96px

コンテナー幅のスケール

トークン	幅	用途
sm	640px	幅の狭いコンテンツ（認証フォーム）
md	768px	ブログ記事、ドキュメント
lg	1024px	アプリのレイアウト
xl	1280px	幅の広いレイアウト
2xl	1536px	全幅のダッシュボード

---

ダークモードの導出

反転パターン

ダークモードの色を手動で選ばないでください。体系的に導出します。

Light mode          →  Dark mode
neutral-50  (bg)    →  neutral-950 (bg)
neutral-100 (bg-subtle) → neutral-900 (bg-subtle)
neutral-200 (border) → neutral-800 (border)
neutral-300 (border-strong) → neutral-700 (border-strong)
neutral-500 (text-muted) → neutral-400 (text-muted)
neutral-600 (text-subtle) → neutral-300 (text-subtle)
neutral-900 (text)  →  neutral-50  (text)
neutral-950 (heading) → neutral-50 (heading)

ルール： 背景のシェードを反転します（50↔950、100↔900、200↔800）。テキストのシェードも同様に反転します。中間のシェード（400–600）は約1～2段階ずらします。

ダークモードでのプライマリカラー

• primary-600 の代わりに、より明るい段階の primary-400 または primary-500 を使用します
• ダークな背景では彩度を少し下げます（目の疲れを軽減します）
• neutral-900 または neutral-950 の背景に対するコントラストを確認します

ダークモード用のセマンティックトークン

/* Light */
:root {
  --color-bg: var(--neutral-50);
  --color-text: var(--neutral-900);
  --color-primary: var(--primary-600);
}

/* Dark */
.dark {
  --color-bg: var(--neutral-950);
  --color-text: var(--neutral-50);
  --color-primary: var(--primary-400);
}

利点：コンポーネントは生のシェードではなく、常にセマンティックトークンを参照します。テーマの切り替えは、トークンの対応関係を入れ替えるだけです。

---

出力形式

CSS カスタムプロパティ

:root {
  /* Type */
  --font-size-base: 1rem;
  --font-size-lg: 1.2rem;
  /* Colors */
  --color-primary-500: hsl(220, 80%, 50%);
  /* Spacing */
  --space-4: 1rem;
}

Tailwind 設定

module.exports = {
  theme: {
    extend: {
      fontSize: {
        'xs': '0.694rem',
        'sm': '0.833rem',
        'base': '1rem',
        'lg': '1.2rem',
        'xl': '1.44rem',
      },
      colors: {
        primary: {
          50: 'hsl(220, 50%, 95%)',
          500: 'hsl(220, 80%, 50%)',
          900: 'hsl(220, 60%, 15%)',
        },
      },
    },
  },
}

JSON デザイントークン（W3C 形式）

{
  "color": {
    "primary": {
      "500": { "$value": "hsl(220, 80%, 50%)", "$type": "color" }
    }
  },
  "fontSize": {
    "base": { "$value": "1rem", "$type": "dimension" }
  }
}

---

手順：デザイントークンを一通り設定する

1. 確認： プロジェクトの種類は何ですか？（マーケティングサイト、SaaS アプリ、ダッシュボードなど）
2. タイプスケール： プロジェクトの種類に基づいて比率を選び、スケールを生成します
3. カラー： ブランドカラーを取得し、プライマリ、ニュートラル、セマンティックの各シェードスケールを生成します
4. コントラストの確認： すべてのテキストと背景の組み合わせを WCAG AA に照らして確認します
5. スペーシング： 4を基準とするスケールを使用します（Tailwind に合わせます）
6. ダークモード： 反転パターンを使ってライトパレットから導出します
7. 出力： CSS カスタムプロパティ、および／または Tailwind 設定を生成します

例

例1：「SaaS ダッシュボード用のデザイントークンを設定する」

• タイポグラフィ：Minor Third（1.2）の比率、ベース 16px — 大げさにならず、明確な階層を作れます
• カラー：ブランドブルーと暖色系のグレーのニュートラルカラーから生成します
• スペーシング：4を基準とするスケール（Tailwind のデフォルト）
• ダークモード：完全に導出します

例2：「このブランドカラーからカラーパレットを作りたい：#6366F1」

• HSL を解析：~239°、84%、67%
• シェード生成方法を使って 50–950 のスケールを生成します
• セマンティックトークンを割り当てます
• すべてのテキストと背景の組み合わせについて WCAG コントラストを確認します
• CSS と Tailwind 設定として出力します

例 3：「ブログ用のタイポグラフィスケールを作成する」

• 比率：長三度（1.25）— エディトリアルコンテンツに適した明確な階層
• 基準サイズ：18px（長文を読みやすくするため、やや大きめ）
• 各ステップの行の高さと文字間隔を含めてスケールを生成します