色と余白をトークンとして定義するところまでは終わった。それなのに実装には直値が残っていて、名前の付け方も人によって違う。デザインファイル側の変数と実装側の値が、いつの間にか別のものになっている。
名前の階層、定義を置く場所、直値が残っていないかの確認方法を決めると、トークンを作った後の運用まで見通せます。
デザイントークンとは何か
色、タイポグラフィ、余白といったUIの値に名前を付けて、一元的に定義・管理するための最小単位です。値をコードやデザインファイルに直接書く代わりに、名前を参照する。名前と値の対応を1箇所に置くことで、値を変えたときに参照している側がまとめて追従します。
Adobe の公式ブログは、色、タイポグラフィ、パディング、シャドウなどUI要素のスタイルの値を表すもの、と説明しています。SmartHR Design System も UXPin も、粒度の説明はこれと同じ方向です。ここは争点になっていません。
デザインシステムが基準や部品を扱うのに対し、トークンは色や余白などの値を名前で管理する手段です。デザインシステム全体を完成させる前に、その画面で使う値から定義できます。ソフィエイトは、まず1画面に必要なトークンとコンポーネントを用意し、運用しながら広げる方法を勧めています。
トークンをデザインシステムの説明で独立した項目として挙げるかは、出典によって異なります。分類の違いはデザインシステムとは何かで確認できます。
名前は何を基準に決めるのか
トークン名を値そのものだけで決めると、色や余白を変えたときに名前と用途が食い違います。どこで使う値かを名前から分かるようにしておく。Adobe は運用のヒントとして「名前のルールを明確にする」を挙げ、CodeGrid は color.brand.main のようにカテゴリをネストさせる書き方を紹介しています。
階層の呼び方は出典ごとに違う
実務でつまずくのは、役割で名付けるかどうかより、階層の呼び方のほうです。同じ「セマンティックトークン」という語が、出典によって別の層を指します。
| 出典 | 階層の数と呼び方 |
|---|---|
| SmartHR Design System | 2階層。プリミティブ（具体性のある値で、もっとも低レイヤーで原子的な意味を持つ）とセマンティック（特定のコンテキストに関連した値） |
| UXPin 公式ブログ（2026年5月更新） | 3階層。Global（Primitive）、Alias（Semantic）、Component。Alias と Semantic を同じ層の別名として扱う |
| Think IT（2025年3月） | 3階層。プリミティブ、エイリアス、セマンティックを、それぞれ別の層として区別する |
Think IT はエイリアスを「プリミティブトークンに分かりやすい別名を付けたもの」、セマンティックを「エイリアストークンにさらに細かな意味ごとに別名を付けたもの」と定義したうえで、小規模なプロジェクトでは両者を区別せず、まとめてエイリアストークンと呼ぶことがある、とも書いています。書き手の側が揺れを認めている形です。
仕様を見ると理由が分かります。Design Tokens Format Module の用語定義に並ぶのは Token、Token Properties、Design tool、Translation tool、Documentation tool、Type、Group、Alias、Composite Token の9項目で、「プリミティブ」「セマンティック」「コンポーネント」という階層名は1つも出てきません。階層の呼び方は仕様が定めたものではなく、各ツールとデザインシステムが空いている場所を埋めた慣習です。
社内で揃えるべきなのは呼び名ではなく、層をいくつ持つかと、どの名前がどの層に属するかの対応です。読み替えの表を1枚持っておけば、外の記事を読むときにも詰まりません。
役割名と段階の数字が混ざる場所
役割で名付けると決めても、濃淡や不透明度の段階はどこかで数字になります。この数字を名前のどこに入れるかを決めていないと、書く人によって位置が変わります。
Nue のサイトのスタイル定義がその実例です。面、文字、フォント、字送りを役割名で定義していますが、文字色だけは役割名と不透明度の段階が1つの名前の中に同居しています。役割で名付けるという方針と、段階を数字で刻むという都合が、同じ名前の上でぶつかる場所です。ここを先に決めておくと、あとから名前を作り直す量が減ります。
定義の置き場所は、値を変える人で決まる
デザインツールと実装のどちらを正にするか。ソフィエイトは、Figmaとコードの値がずれる問題を挙げ、どちらを正本にするかを先に決めるよう勧めています。値をどこで確定させるかを、運用前に揃えるという考え方です。
- デザイナーだけが値を変える場合は、 デザインツールの変数を正にして、実装へ値を反映する。
- 実装側だけが値を変える場合は、 実装の定義を正にして、デザインツールは参照する。
- 両方が値を変える場合は、 値の正本と変更の承認者を決め、共通形式で受け渡す。
- 動いている画面がデザインファイルより新しい場合は、 画面を計測して値を決める。
受け渡しの形式は、どこまで固まっているか
3つ目で値を受け渡す形式を決めるときの材料になるのが、W3C 傘下の Design Tokens Community Group（DTCG）が策定している Design Tokens Format Module です。仕様が定めるのはツール間で交換するファイル形式で、どちらが値を承認するかではありません。2025年10月28日に version 2025.10 として、初の安定版が公開されました。
状態は正確に見ておく必要があります。文書のステータスは Final Community Group Report で、本文には「W3C の標準ではなく、W3C の標準化過程にあるものでもない」と明記されています。正式勧告ではなく、Community Group としての合意文書です。同じ文書に「安定しているとみなす」「以後の更新は後続の仕様で提供する」とも書かれています。
DTCG は、策定参加者の所属先として Adobe、Google、Microsoft、Meta、Figma などを挙げ、Style Dictionary、Tokens Studio、Terrazzo を参照実装として紹介しています。一方で改訂作業は続いていて、次期版に向けたドラフトには「この版を実装しようとしないこと」「権威あるものとして参照しないこと」という注記が付いたままです。安定版を採用の基準に置き、ドラフトは追いかけない、という線の引き方になります。
動いている画面を正にする場合
デザインファイルが実装に追いつかなくなっている状態は珍しくありません。Nue のサイトの値は、デザインファイルから出したものではなく、先に動いていたトップページの描画結果を計測して決めたものです。目分量で寄せるとずれるので、変えるときも画面を計測してから変えています。
この決め方は、デザインツール側を正にするか実装側を正にするかという2択のどちらにも入りません。正にするのは、デザインファイルでも実装の定義でもなく、いま動いている画面です。
定義したのに直値が残るのはなぜか
トークンを定義しても、参照していない値は増えます。参照されていない直値は、定義の側からは見えないからです。トークンの一覧をいくら眺めても、その値がどこで無視されているかは出てきません。
確認する範囲は、まず対象画面とそのスタイル定義で決めます。CSSの値とトークン参照を照合し、意図して残す直値は例外として分けます。本文のインラインスタイルを検出するだけでは、CSSに残る値までは分かりません。
プロダクト開発支援のページでは、週次レビューの観点としてUX、UI品質、デザインシステムからの逸脱、アクセシビリティ、コピー、コンバージョンの阻害要因を挙げています。そのうちコントラスト比、代替テキストの有無、デザイントークンからの逸脱を機械的に判定するという説明です。
判定が機械側と人側に割れること自体と、その線の引き方はデザインハーネスとは何かに書いています。トークン準拠は値の照合なので、機械側に寄る項目です。
どこまで作れば足りるか、まだ作らない方がいい場合
網羅から入らない進め方が解説されています。ソフィエイトは、まずよく使う画面に必要な分だけトークンと部品を用意し、その画面で運用できてから別の画面へ広げる方法を紹介しています。最初から全部の値を数え上げる作業にはなりません。
作らない方がいい場合の線引きは、デザインシステムのときと変わりません。定義したあとにそれを見張る担当と頻度を用意できないなら、直値との二重管理が増えます。規模の目安と、作らないと判断するための材料はデザインシステムとは何かにまとめています。
階層をどう呼ぶかは、あとから読み替えられます。先に決めたいのは、値の参照元と、直値を確認する対象範囲です。この2つを揃えると、名前をめぐる議論は小さく済みます。