design-system-tokens

デザインシステムトークン

W3C Design Token Community Group（DTCG）の仕様に準拠したデザイントークン管理です。トークンは、デザインツール（Figma、Penpot）とコード（CSS、Tailwind、iOS、Android）で共有される、色、間隔、タイポグラフィ、エレベーションなどのデザイン上の決定事項の信頼できる唯一の情報源となります。主な採用企業には、Figma（Variables API）、Google（Material Design 3）、Microsoft（Fluent UI）、Shopify（Polaris）があります。

クイックリファレンス

カテゴリー	ルールファイル	影響度	使用する場面
W3C トークン形式	tokens-w3c-format.md	CRITICAL	.tokens.json ファイルを作成または読み込むとき
コントラストの適用	tokens-contrast-enforcement.md	CRITICAL	トークンの定義時に WCAG コントラストを検証するとき
3 層階層	tokens-three-tier.md	HIGH	トークンをグローバル／エイリアス／コンポーネントの各レイヤーに整理するとき
OKLCH 色空間	tokens-oklch-color.md	HIGH	知覚的均一性のある色を定義するとき
間隔と奥行き	tokens-spacing-depth.md	HIGH	エレベーションのシャドウや間隔のスケールをトークンとして定義するとき
Style Dictionary	tokens-style-dictionary.md	HIGH	トークンを CSS／Tailwind／iOS／Android 向けに変換するとき
テーマ設定とダークモード	tokens-theming-darkmode.md	HIGH	テーマ切り替えやダークモードを実装するとき
バージョン管理	tokens-versioning.md	HIGH	利用側に影響を与えずにトークンを進化させるとき

合計：8 カテゴリーにわたる 8 つのルール

クイックスタート

W3C DTCG トークン形式（.tokens.json）：

{
  "color": {
    "primary": {
      "50": {
        "$type": "color",
        "$value": "oklch(0.97 0.01 250)",
        "$description": "Lightest primary shade"
      },
      "500": {
        "$type": "color",
        "$value": "oklch(0.55 0.18 250)",
        "$description": "Base primary"
      },
      "900": {
        "$type": "color",
        "$value": "oklch(0.25 0.10 250)",
        "$description": "Darkest primary shade"
      }
    }
  },
  "spacing": {
    "sm": {
      "$type": "dimension",
      "$value": "8px"
    },
    "md": {
      "$type": "dimension",
      "$value": "16px"
    },
    "lg": {
      "$type": "dimension",
      "$value": "24px"
    }
  }
}

3 層トークン階層

トークンは 3 つのレイヤーに整理され、それぞれが下のレイヤーを参照します。

階層	目的	例
グローバル	生の値	color.blue.500 = oklch(0.55 0.18 250)
エイリアス	意味付け	color.primary = {color.blue.500}
コンポーネント	スコープを限定した使用	button.bg = {color.primary}

この分離により、コンポーネントトークンに手を加えずにテーマを切り替えられます（エイリアスのマッピングを差し替えます）。

{
  "color": {
    "blue": {
      "500": { "$type": "color", "$value": "oklch(0.55 0.18 250)" }
    },
    "primary": { "$type": "color", "$value": "{color.blue.500}" },
    "action": {
      "default": { "$type": "color", "$value": "{color.primary}" }
    }
  }
}

OKLCH 色空間

OKLCH（Oklab Lightness、Chroma、Hue）は知覚的な均一性を実現します。数値を同じだけ変化させると、視覚的にも同じ程度の変化が生じます。これにより、同じ明度でも hsl(60, 100%, 50%)（黄色）が hsl(240, 100%, 50%)（青）よりはるかに明るく見えるという、HSL の問題を解決します。

/* OKLCH: L (0-1 lightness), C (0-0.4 chroma/saturation), H (0-360 hue) */
--color-primary: oklch(0.55 0.18 250);
--color-primary-hover: oklch(0.50 0.18 250);  /* Just reduce L for darker */

主な利点：明度チャンネルだけを調整すれば、一貫したコントラスト比を持つ、アクセシブルな色の濃淡スケールを作成できます。

詳細ルール

各ルールファイルには、誤ったコードと正しいコードの組み合わせ、および実装ガイダンスが含まれています。

Read("rules/tokens-w3c-format.md")

Read("rules/tokens-contrast-enforcement.md")

Read("rules/tokens-three-tier.md")

Read("rules/tokens-oklch-color.md")

Read("rules/tokens-spacing-depth.md")

Read("rules/tokens-style-dictionary.md")

Read("rules/tokens-theming-darkmode.md")

Read("rules/tokens-versioning.md")

Style Dictionary の統合

Style Dictionary は、W3C トークンをプラットフォーム固有の出力（CSS カスタムプロパティ、Tailwind テーマ、iOS Swift、Android XML）に変換します。1 つの config.json を設定すれば、単一のトークンソースからすべてのプラットフォーム向けの出力を生成できます。

Style Dictionary 5.x（現行） — style-dictionary >= 5.3.0 を固定してください。ほかの箇所で説明されている 4.x と比べた、関連する変更点は次のとおりです。

• OKLCH のネイティブ出力 — 4.x で必要だったカスタムの color/oklch 変換は不要になりました。入力トークンが OKLCH 値を持つ $type: "color" を使用していれば、組み込みの css/variables フォーマッターが OKLCH を直接出力します。独自に作成した変換処理は削除してください。
• DTCG v2025.10 の dimension オブジェクト — $type: "dimension" は、単独の文字列 "16px" ではなく、オブジェクト { "value": 16, "unit": "px" } を受け取るようになりました。5.3 以降はどちらも解析できますが、新しいトークンではオブジェクト形式を使用してください。
• 4.x のグローバルな registerTransform／registerFormat 呼び出しに代わり、Hooks API を使用します。ツリーシェイキングを改善するため、フックを設定に渡してください。

設定パターンとカスタム変換については、rules/tokens-style-dictionary.md を参照してください。

ダークモードとテーマ設定

トークンベースのテーマ設定では、エイリアストークンをテーマごとに異なるグローバル値へマッピングします。ダークモードはテーマの一つです。ハイコントラストやブランドのバリエーション、季節ごとのテーマなど、いくつでもサポートできます。

:root {
  --color-surface: oklch(0.99 0.00 0);
  --color-on-surface: oklch(0.15 0.00 0);
}

[data-theme="dark"] {
  --color-surface: oklch(0.15 0.00 0);
  --color-on-surface: oklch(0.95 0.00 0);
}

テーマ切り替えのパターン全般については、rules/tokens-theming-darkmode.md を参照してください。

バージョン管理と移行

トークンは進化します。トークンパッケージにはセマンティックバージョニングを適用し、トークンファイルに非推奨の注釈を付け、破壊的変更には codemod を使用してください。

{
  "color": {
    "brand": {
      "$type": "color",
      "$value": "oklch(0.55 0.18 250)",
      "$extensions": {
        "com.tokens.deprecated": {
          "since": "2.0.0",
          "replacement": "color.primary.500",
          "removal": "3.0.0"
        }
      }
    }
  }
}

移行戦略については、rules/tokens-versioning.md を参照してください。

shadcn/ui v4 プリセットの統合

shadcn CLI v4 は、スタイル、テーマ、フォント、アイコンを共有可能なプリセットコードにまとめます。プリセットは、トークン階層にマッピングする CSS 変数を含む globals.css を生成します。

npx shadcn@latest init --preset b2D0xPaDb  # Luma + Emerald + Geist

Luma のエレベーショントークン（トークンが最も豊富なスタイル）：

/* Luma elevation system — soft depth hierarchy */
--shadow-card: 0 1px 3px 0 rgb(0 0 0 / 0.1), 0 1px 2px -1px rgb(0 0 0 / 0.1);  /* shadow-md */
--ring-card: 0 0 0 1px var(--foreground) / 0.05;  /* ring-1 ring-foreground/5 */
--shadow-dropdown: 0 4px 6px -1px rgb(0 0 0 / 0.1);  /* shadow-lg */
--shadow-dialog: 0 10px 15px -3px rgb(0 0 0 / 0.1);  /* shadow-xl */
--radius-button: var(--radius-4xl);  /* pill-shaped */
--radius-card: var(--radius-4xl);
--radius-input: var(--radius-3xl);

検出方法： components.json の "style" フィールドを読み取り、有効なエレベーション／角丸トークンを特定します。プリセットが生成した CSS 変数を、Style Dictionary の変換を通じて W3C DTCG トークンにマッピングします。

主な決定事項

決定事項	推奨事項
トークン形式	$type／$value を使用する W3C DTCG .tokens.json
色空間	知覚的な均一性を得られる OKLCH
階層	3 層構造：グローバル、エイリアス、コンポーネント
ビルドツール	W3C パーサーを備えた Style Dictionary 4.x
テーマ設定	data-theme 属性を使った CSS カスタムプロパティ
トークン参照	{path.to.token} のエイリアス構文を使用

アンチパターン（禁止）

• コンポーネント内のハードコード値：必ずトークンを参照し、生の #hex や 16px は使用しないでください
• フラットなトークン構造：テーマ対応のため、3 層の階層構造を使用してください
• シェードスケールに HSL を使用：OKLCH は知覚的に均一なスケールを生成しますが、HSL は生成しません
• $type の省略：ツールとの互換性を保つため、すべてのトークンで型を宣言してください
• 生の値をクラス切り替えでテーマ設定：テーマごとに再マッピングするセマンティックエイリアストークンを使用してください
• バージョン管理されていないトークンパッケージ：トークンの変更は利用側に影響します。semver を使用してください

参考資料

リソース	説明
references/w3c-token-spec.md	W3C DTCG 仕様の概要
references/style-dictionary-config.md	Style Dictionary 5.x の設定ガイド
references/token-naming-conventions.md	命名パターンと規約

エージェント連携

design-system-architect エージェントは、Figma Variables の抽出から Style Dictionary による変換、テーマのデプロイまで、トークンのワークフロー全体を統括します。トークンアーキテクチャに関する決定に取り組む際、エージェントはコンポーネントでのトークン利用について frontend-ui-developer と連携し、コントラスト検証について accessibility スキルと連携します。

関連スキル

• ork:ui-components — コンポーネントライブラリのパターン（shadcn/ui、Radix）
• ork:accessibility — WCAG 準拠、コントラスト比
• ork:responsive-patterns — レスポンシブブレークポイント、流動的なタイポグラフィ
• ork:figma-design-handoff — Figma Variables からトークンへのパイプライン