design-tokens

デザイントークンのエキスパート

Design Tokens Community Group（DTCG）の仕様に従ってデザイントークンを扱うための専門的なガイダンスです。

クイックリファレンス

トピック	リファレンス
トークンのタイプ、構造、検証	reference/format.md
色空間、コンポーネント、アルファ、よくある間違い	reference/color.md
セット、修飾子、解決順序	reference/resolver.md
jq、JSONata、Figma のエクスポート、Terrazzo の設定	reference/tools.md
よくあるパターンと例	examples/use-cases.md

はじめに： 手順に沿ったワークフローについては、はじめにガイドを参照してください。

仕様の情報源

最新の DTCG ドラフトコミュニティグループレポートに基づいています。

• フォーマットモジュール
• カラーモジュール
• リゾルバーモジュール

基本概念

トークンの構造

トークンは$valueを持つ JSON オブジェクトです。特殊なプロパティには$プレフィックスが付きます。

{
  "brand-blue": {
    "$type": "color",
    "$value": {
      "colorSpace": "srgb",
      "components": [0.15, 0.39, 0.92],
      "hex": "#2563eb"
    },
    "$description": "Primary brand color"
  }
}

トークンのタイプ

アトミック： color、dimension、fontFamily、fontWeight、duration、cubicBezier、number

複合： strokeStyle、border、shadow、gradient、typography、transition

すべてのタイプの定義については、reference/format.mdを参照してください。

色のフォーマット

色には構造化オブジェクトを使用します（16 進数文字列ではありません）。

{
  "$type": "color",
  "$value": {
    "colorSpace": "srgb",
    "components": [1, 0, 0.5],
    "alpha": 0.8,
    "hex": "#ff0080"
  }
}

対応する色空間：srgb、display-p3、oklch、oklab、hsl、hwb、lab、lch など。reference/color.mdを参照してください。

リファレンス（エイリアス）

次の 2 つの構文に対応しています。

1. 中括弧 - トークンレベルのリファレンス："{path.to.token}"
2. JSON Pointer（$ref） - プロパティレベルのアクセス：{"$ref": "#/path/to/$value/property"}

トークンリファレンスの例：

{
  "color": {
    "primary": {"$type": "color", "$value": {"colorSpace": "srgb", "components": [0, 0.4, 0.8]}}
  },
  "button": {
    "background": {"$type": "color", "$value": "{color.primary}"}
  }
}

JSON Pointer の例（配列要素へのアクセス）：

{
  "blue": {
    "$type": "color",
    "$value": {"colorSpace": "okhsl", "components": [0.733, 0.8, 0.5]}
  },
  "blue-hue": {
    "$type": "number",
    "$ref": "#/blue/$value/components/0"
  }
}

リファレンス構文の詳細については、reference/format.mdを参照してください。

グループとタイプの継承

グループはトークンを整理します。グループの$typeはすべての子要素に適用されます。

{
  "spacing": {
    "$type": "dimension",
    "sm": {"$value": {"value": 8, "unit": "px"}},
    "md": {"$value": {"value": 16, "unit": "px"}},
    "lg": {"$value": {"value": 24, "unit": "px"}}
  }
}

テーマ設定のリゾルバー

リゾルバーは、コンテキスト（テーマ、プラットフォーム、密度）をまたいでトークンを管理します。

{
  "name": "my-system",
  "version": "2025.10",
  "sets": {
    "core": {"sources": [{"$ref": "tokens/base.json"}]}
  },
  "modifiers": {
    "theme": {
      "contexts": {
        "light": [{"$ref": "themes/light.json"}],
        "dark": [{"$ref": "themes/dark.json"}]
      },
      "default": "light"
    }
  },
  "resolutionOrder": [
    {"$ref": "#/sets/core"},
    {"$ref": "#/modifiers/theme"}
  ]
}

詳しいドキュメントについては、reference/resolver.mdを参照してください。

はじめにガイド

クイックスタート：CSS 変数を DTCG に変換する

開始点： 既存の CSS カスタムプロパティ

:root {
  --color-primary: #2563eb;
  --color-background: #ffffff;
  --spacing-sm: 8px;
  --spacing-md: 16px;
}

ステップ 1： primitives.tokens.json を作成する

{
  "color": {
    "primitive": {
      "$type": "color",
      "blue-500": {
        "$value": { "colorSpace": "srgb", "components": [0.145, 0.388, 0.922], "hex": "#2563eb" }
      },
      "white": {
        "$value": { "colorSpace": "srgb", "components": [1, 1, 1], "hex": "#ffffff" }
      }
    }
  },
  "spacing": {
    "$type": "dimension",
    "scale": {
      "sm": { "$value": { "value": 8, "unit": "px" } },
      "md": { "$value": { "value": 16, "unit": "px" } }
    }
  }
}

ステップ 2： リファレンスを含む semantic.tokens.json を作成する

{
  "color": {
    "interactive": {
      "$type": "color",
      "primary": { "$value": "{color.primitive.blue-500}" }
    },
    "background": {
      "$type": "color",
      "page": { "$value": "{color.primitive.white}" }
    }
  },
  "spacing": {
    "$type": "dimension",
    "component": {
      "padding": { "$value": "{spacing.scale.sm}" },
      "gap": { "$value": "{spacing.scale.md}" }
    }
  }
}

変換のヒント：

• RGB の 16 進数を sRGB に変換するには、各チャンネルを 255 で割ります（例：37/255 = 0.145）
• hexプロパティにフォールバックとして 16 進数を保持します
• 用途に基づいた命名のために、セマンティックレイヤーを作成します

---

クイックスタート：ダークモードで Terrazzo をセットアップする

ステップ 1： 依存関係をインストールする

npm install -D @terrazzo/cli @terrazzo/plugin-css

ステップ 2： モード拡張を含むトークンファイルを作成する

tokens/themes/light.tokens.json：

{
  "$extensions": { "mode": "light" },
  "color": {
    "background": {
      "$type": "color",
      "page": { "$value": { "colorSpace": "srgb", "components": [1, 1, 1], "hex": "#ffffff" } }
    },
    "text": {
      "$type": "color",
      "primary": { "$value": { "colorSpace": "srgb", "components": [0.07, 0.07, 0.07], "hex": "#121212" } }
    }
  }
}

tokens/themes/dark.tokens.json：

{
  "$extensions": { "mode": "dark" },
  "color": {
    "background": {
      "$type": "color",
      "page": { "$value": { "colorSpace": "srgb", "components": [0.07, 0.07, 0.07], "hex": "#121212" } }
    },
    "text": {
      "$type": "color",
      "primary": { "$value": { "colorSpace": "srgb", "components": [0.95, 0.95, 0.95], "hex": "#f2f2f2" } }
    }
  }
}

ステップ 3： terrazzo.config.mjs を作成する

import { defineConfig } from "@terrazzo/cli";
import pluginCSS from "@terrazzo/plugin-css";

export default defineConfig({
  tokens: [
    "./tokens/primitives.tokens.json",
    "./tokens/themes/light.tokens.json",
    "./tokens/themes/dark.tokens.json"
  ],
  outDir: "./dist/",
  plugins: [
    pluginCSS({
      filename: "tokens.css",
      modeSelectors: [
        { mode: "light", selectors: [":root", "[data-theme='light']"] },
        { mode: "dark", selectors: ["[data-theme='dark']", "@media (prefers-color-scheme: dark)"] }
      ]
    })
  ]
});

ステップ 4： ビルドして使用する

npx terrazzo build

HTML 内：

<html data-theme="light">

---

クイックスタート：Figma Variables のエクスポートをインポートする

ステップ 1： Figma からエクスポートする

• Figma で Variables パネルを開きます
• DTCG エクスポートプラグインまたは Figma の組み込みエクスポートを使用します
• figma-export.jsonとして保存します

ステップ 2： エクスポートを検証する

# Check JSON is valid
jq '.' figma-export.json > /dev/null && echo "Valid JSON"

# List all token paths
jq -r 'paths(has("$value")) | join(".")' figma-export.json

ステップ 3： 必要に応じてモード拡張を追加する

Figma が個別のモードファイルをエクスポートした場合は、$extensions.modeを追加します。

# Add mode to light theme file
jq '. + {"$extensions": {"mode": "light"}}' light.json > light.tokens.json

ステップ 4： 16 進数のフォールバックを追加する（ない場合）

Figma のエクスポートには sRGB コンポーネントが含まれますが、16 進数が省略される場合があります。

# Quick check if hex values exist
jq '.. | objects | select(.colorSpace == "srgb") | select(.hex == null)' figma-export.json

ステップ 5： Terrazzo を設定する

インポートしたファイルを指定するterrazzo.config.mjsを作成して、ビルドします。

Figma のエクスポートでよくある問題：

• フラットな構造（プリミティブとセマンティックが分離されていない） - 手動で再編成します
• トークン名にスペースが含まれる - jq を使ってケバブケースに変換します
• グループに$typeがない - タイプの継承を追加します

---

ワークフロー

トークンファイルの作成

Token File Creation:
- [ ] Step 1: Define file structure (primitives → semantic → components)
- [ ] Step 2: Create primitive tokens with explicit types
- [ ] Step 3: Create semantic tokens referencing primitives
- [ ] Step 4: Validate structure and references
- [ ] Step 5: Test with target tools (Terrazzo, etc.)

ステップ 1：構造を定義する

レイヤーに分けて整理します。

tokens/
├── primitives.tokens.json   # Raw values (colors, spacing scales)
├── semantic.tokens.json     # Purpose-driven aliases
└── components.tokens.json   # Component-specific tokens

ステップ 2：プリミティブを作成する

{
  "color": {
    "primitive": {
      "$type": "color",
      "blue": {
        "500": {"$value": {"colorSpace": "srgb", "components": [0.15, 0.39, 0.92], "hex": "#2563eb"}}
      }
    }
  }
}

ステップ 3：セマンティックトークンを作成する

{
  "color": {
    "interactive": {
      "$type": "color",
      "default": {"$value": "{color.primitive.blue.500}"}
    }
  }
}

ステップ 4：検証する

次の点を確認します。

• すべてのトークンに解決可能な $type がある
• 循環参照がない
• 各タイプに有効な値の形式が使われている
• 名前に {、}、. が含まれていない。また、$ で始まっていない

ステップ 5：ツールでテストする

terrazzo validate tokens.json
terrazzo build --input tokens.json --output test.css --format css

---

テーマリゾルバーの設定

Resolver Setup:
- [ ] Step 1: Organize token files by concern
- [ ] Step 2: Create resolver.json with version and sets
- [ ] Step 3: Define theme modifier with contexts
- [ ] Step 4: Configure resolution order
- [ ] Step 5: Test with different inputs

ステップ 1：ファイルを整理する

tokens/
├── resolver.json
├── base.tokens.json
└── themes/
    ├── light.tokens.json
    └── dark.tokens.json

ステップ 2：リゾルバーを作成する

{
  "name": "my-design-system",
  "version": "2025.10",
  "sets": {
    "foundation": {
      "sources": [{"$ref": "base.tokens.json"}]
    }
  }
}

ステップ 3：テーマモディファイアを定義する

{
  "modifiers": {
    "theme": {
      "contexts": {
        "light": [{"$ref": "themes/light.tokens.json"}],
        "dark": [{"$ref": "themes/dark.tokens.json"}]
      },
      "default": "light"
    }
  }
}

ステップ 4：解決順序を設定する

{
  "resolutionOrder": [
    {"$ref": "#/sets/foundation"},
    {"$ref": "#/modifiers/theme"}
  ]
}

ステップ 5：テストする

terrazzo build --resolver resolver.json --output light.css
terrazzo build --resolver resolver.json --input theme=dark --output dark.css

---

トークンファイルの検証

Validation Checklist:
- [ ] Step 1: Check JSON syntax
- [ ] Step 2: Verify type declarations
- [ ] Step 3: Validate value formats
- [ ] Step 4: Check reference resolution
- [ ] Step 5: Verify naming constraints

ステップ 1：JSON 構文

jq '.' tokens.json > /dev/null && echo "Valid JSON"

ステップ 2：タイプ宣言

すべてのトークンには、解決可能な $type が必要です（明示的に指定するか、親グループから継承します）。

ステップ 3：値の形式

タイプ	有効な形式
color	{colorSpace, components, [alpha], [hex]}
dimension	`{value: number, unit: "px"
duration	`{value: number, unit: "ms"
cubicBezier	[P1x, P1y, P2x, P2y]。P1x と P2x ∈ [0,1]
fontWeight	1～1000、または文字列（"normal"、"bold" など）

ステップ 4：参照

• すべての {path.to.token} 参照が解決可能であること
• 循環参照（A → B → A）がないこと
• 自己参照がないこと

ステップ 5：命名

• 名前を $ で始めることはできません
• 名前に {、}、. を含めることはできません

---

他の形式からの移行

Migration Workflow:
- [ ] Step 1: Export existing tokens to JSON
- [ ] Step 2: Map types to DTCG equivalents
- [ ] Step 3: Convert color values to structured format
- [ ] Step 4: Update reference syntax
- [ ] Step 5: Validate and test

一般的な変換：

変換元	DTCG への変換先
"#ff0000"	{colorSpace: "srgb", components: [1,0,0], hex: "#ff0000"}
"16px"	{value: 16, unit: "px"}
"$colors.primary" または {colors.primary}	"{colors.primary}"

Terrazzo での変換：

terrazzo convert --from style-dictionary --to dtcg input.json output.tokens.json

ベストプラクティス

トークンレイヤー

1. プリミティブ - セマンティックな意味を持たない生の値
2. セマンティック - プリミティブを参照する、用途に基づいたトークン
3. コンポーネント - セマンティックトークンを参照する、特定のコンポーネント用トークン

命名規則

• 小文字とハイフンを使用します：color.brand.primary
• 構造：[category].[subcategory].[variant].[state]
• 外観ではなく意味を表す名前を使います：color.blue-500 ではなく color.interactive.default

テーマ戦略

テーマにはリゾルバーを使用します（グループ拡張よりも推奨）。

• 関心事をより明確に分離できます
• テーマ間でトークンパスの一貫性を保てます
• テーマを簡単に組み合わせられます（例：ダーク＋高コントラスト）
• ビルドツールでの入力処理を標準化できます

アクセシビリティ

色のコントラスト： $extensions にコントラスト比を記録します。

{
  "$extensions": {
    "com.example.a11y": {"contrastRatio": 7.5, "wcagLevel": "AA"}
  }
}

モーションの軽減： リゾルバーモディファイアを使用します。

{
  "modifiers": {
    "motion": {
      "contexts": {
        "full": [{"$ref": "motion/full.json"}],
        "reduced": [{"$ref": "motion/reduced.json"}]
      },
      "default": "full"
    }
  }
}

ファイル規則

• トークンファイル：.tokens または .tokens.json
• リゾルバーファイル：.resolver.json
• エンコーディング：UTF-8

一般的なタスク

タスク	方法
形式の検証	DTCG 仕様に照らして確認し、Terrazzo validate を使用する
構造の最適化	プリミティブ → セマンティック → コンポーネントのレイヤーに整理する
エイリアスの解決	参照をたどり、循環依存がないか確認する
リゾルバーの設定	セット、モディファイア、解決順序を定義する
テーマの実装	コンテキストファイルとリゾルバーモディファイアを使用する
複数コンテキストでのビルド	テーマ／プラットフォーム／密度ごとに出力を生成する
ツール連携	クエリには jq、変換には Terrazzo を使用する
移行	色を構造化形式に変換し、参照を更新する

あなたの役割

デザイントークンについてサポートする際は、次の点に従ってください。

1. 主張する前に確認する - DTCG がサポートしていること、またはサポートしていないことを述べる前に、リファレンスファイルを確認してください。仕様の制限を決めつけないでください。
2. 最新の DTCG 仕様を使用する - 構造化されたカラー形式と適切な型を使用してください。
3. 構造を検証する - $value、$type、参照を確認してください。
4. ベストプラクティスを提案する - 命名、整理、レイヤリングについて提案してください。
5. ツールをサポートする - jq クエリ、Terrazzo コマンド、JSONata 変換をサポートしてください。
6. プラットフォームを考慮する - $extensions を使用して Web、iOS、Android に対応してください。
7. 規模を考慮する - 保守性を重視して設計してください。
8. アクセシビリティを優先する - コントラスト、モーション、フォーカスインジケーターに配慮してください。
9. デザインとコードをつなぐ - ツールと実装の橋渡しをしてください。

重要： 仕様で可能なこと（有効な構文や利用できる機能）について質問された場合は、必ず最初に該当するリファレンスファイルを読んでください。仕様に関する思い込みや以前の知識に頼らないでください。

明確な例を示し、提案の根拠を必ず説明してください。