色と余白をトークンとして定義するところまでは終わった。それなのに実装には直値が残っていて、名前の付け方も人によって違う。デザインファイル側の変数と実装側の値が、いつの間にか別のものになっている。
デザイントークンが何を指すかは、どの出典でもほぼ同じ説明になります。割れるのは、名前の階層をどう数えるか、定義をどちら側に置くか、決めたあとに守られているかをどう確かめるか。この3つです。2026年9月時点で確認できた範囲で書きます。
デザイントークンとは何か
色、タイポグラフィ、余白といったUIの値に名前を付けて、一元的に定義・管理するための最小単位です。値をコードやデザインファイルに直接書く代わりに、名前を参照する。名前と値の対応を1箇所に置くことで、値を変えたときに参照している側がまとめて追従します。
Adobe の公式ブログは、色、タイポグラフィ、パディング、シャドウなどUI要素のスタイルの値を表すもの、と説明しています。SmartHR Design System も UXPin も、粒度の説明はこれと同じ方向です。ここは争点になっていません。
デザインシステムとの関係も、出典をまたいで一致します。構成要素の数え方は割れますが、どの区分でもデザイントークンは中に入っています。数え方の違いはデザインシステムとは何かに表で置いています。全体が揃うまで始められないわけではなく、制作会社のソフィエイトは「まずは1画面だけで回して、増やす」という段階的な進め方を挙げています。
名前は何を基準に決めるのか
値そのものを名前にすると、値を変えたときに名前だけが嘘になります。赤をやめて青にしても、RedButton という名前が残る。同じ記事は RedButton や BlueButton を避けて、PrimaryButton SecondaryButton のように役割で名付けることを勧めています。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つの名前の中に同居しています。役割で名付けるという方針と、段階を数字で刻むという都合が、同じ名前の上でぶつかる場所です。ここを先に決めておくと、あとから名前を作り直す量が減ります。
定義の置き場所は、値を変える人で決まる
デザインツールと実装のどちらを正にするか。ソフィエイトはこれを「早めに決めておく」ものとして扱い、「ここが曖昧だと、運用が始まった後にブレやすい」と書いています。正解を1つに固定するのではなく、運用を始める前に置き場所を決める、という整理です。
- 値を変えるのがデザイナー側だけ デザインツールの変数を正にして、実装は同期を受ける
- 値を変えるのが実装側だけ 実装の定義を正にして、デザインツールは参照する
- 両方が変える 受け渡しの形式を1つ決めて、そこを正にする
- デザインファイルより動いている画面のほうが新しい 画面を計測して値を決める
受け渡しの形式は、どこまで固まっているか
3つ目を選ぶときの材料になるのが、W3C 傘下の Design Tokens Community Group が策定している Design Tokens Format Module です。2025年10月28日に version 2025.10 として、初の安定版が公開されました。
状態は正確に見ておく必要があります。文書のステータスは Final Community Group Report で、本文には「W3C の標準ではなく、W3C の標準化過程にあるものでもない」と明記されています。正式勧告ではなく、Community Group としての合意文書です。同じ文書に「安定しているとみなす」「以後の更新は後続の仕様で提供する」とも書かれています。
採用の広がりは公表されています。Adobe、Google、Microsoft、Meta、Figma など24以上の組織がこの安定版を支持し、Style Dictionary、Tokens Studio、Terrazzo が参照実装を提供していると発表されています。一方で改訂作業は続いていて、次期版に向けたドラフトには「この版を実装しようとしないこと」「権威あるものとして参照しないこと」という注記が付いたままです。安定版を採用の基準に置き、ドラフトは追いかけない、という線の引き方になります。
動いている画面を正にする場合
デザインファイルが実装に追いつかなくなっている状態は珍しくありません。Nue のサイトの値は、デザインファイルから出したものではなく、先に動いていたトップページの描画結果を計測して決めたものです。目分量で寄せるとずれるので、変えるときも画面を計測してから変えています。
この決め方は、デザインツール側を正にするか実装側を正にするかという2択のどちらにも入りません。正にするのは、デザインファイルでも実装の定義でもなく、いま動いている画面です。
定義したのに直値が残るのはなぜか
トークンを定義しても、参照していない値は増えます。参照されていない直値は、定義の側からは見えないからです。トークンの一覧をいくら眺めても、その値がどこで無視されているかは出てきません。
確かめ方は、定義したトークンの数を数えることではなく、直値が残っている場所を数えることです。これが成り立つ条件は1つあります。値を書ける場所が1箇所に閉じていることです。
Nue のサイトでは、記事とサービスページの本文に値を直接書く形を検査でエラーにしていて、書いた時点で公開が止まります。値の置き場所をスタイル定義側のカスタムプロパティに閉じているので、そこから外れた直書きを機械が拾えます。
裏返すと、判定の範囲を決めるというのは、範囲の外を判定しないと決めることでもあります。Nue のサイトでも、検査の対象に入っていない領域では、色が16進数の直値のまま置かれています。トークンを定義したかどうかではなく、どこまでを判定の対象にしたかが、直値の残り方を決めます。
プロダクトに対しては、週次のレビューで同じことをしています。UX、UI品質、デザインシステムからの逸脱、アクセシビリティ、コピー、コンバージョンの阻害要因という観点のうち、コントラスト比、代替テキストの有無、デザイントークンからの逸脱は機械的に判定しています。範囲はプロダクト開発支援のページにあります。
判定が機械側と人側に割れること自体と、その線の引き方はデザインハーネスとは何かに書いています。トークン準拠は値の照合なので、機械側に寄る項目です。
どこまで作れば足りるか、まだ作らない方がいい場合
網羅から入らない進め方が解説されています。ソフィエイトが現実的な進め方として挙げるのは「まずは1画面だけで回して、増やす」です。1画面分の色と余白と字送りを名前に移し、次の画面で足りないものを足す。最初から全部の値を数え上げる作業にはなりません。
作らない方がいい場合の線引きは、デザインシステムのときと変わりません。定義したあとにそれを見張る担当と頻度を用意できないなら、直値との二重管理が増えます。規模の目安と、作らないと判断するための材料はデザインシステムとは何かにまとめています。
階層をどう呼ぶかは、あとから読み替えられます。決め直しが効きにくいのは、値を変える人がどちら側にいるかの判断と、判定の対象範囲の2つです。この2つを先に置くと、名前をめぐる議論は小さく済みます。