デザイントークン フォーマット・モジュール 2025.10

このフォーマットで定義されているすべてのプロパティはドル記号（$）で始まります。この慣例は、将来バージョンで新しく導入されるプロパティにも適用されます。したがって、トークンおよびグループ名は $ で始めては MUST NOT いけません。

さらに、トークンエイリアスで使用される構文上の理由から、次の文字はトークン名やグループ名のいかなる場所にも MUST NOT で含めてはいけません：

• {（左中括弧）
• }（右中括弧）
• .（ピリオド）

トークンの用途を説明するプレーンテキストをオプションの $description プロパティで指定できます。ツールは MAY さまざまな形で説明を利用します。

例：

• スタイルガイド自動生成ツールは、説明文をトークンのビジュアルプレビューと共に表示する MAY
• IDEは入力補完時のツールチップとして説明文を表示する MAY（APIドキュメントのように）
• デザインツールが、トークンを選択可能なUI上で説明文をツールチップや副説明として表示する MAY
• 変換ツールが、エクスポート先のソースコード変数などに説明文をコメントとして出力する MAY

$descriptionプロパティの値はプレーンなJSON文字列で MUST です。例：

デザイントークンは常に明確な型を持ち、ツールはその値を確実に解釈できます。

トークンの型はオプションの $type プロパティで指定できます。$type が指定されていない場合、トークンの型は次のように MUST 判断します：

• トークン値が参照であれば、参照先トークンの型に解決されます。
• それ以外で親グループのいずれかに $type があれば、もっとも近い親グループの $type を継承します。
• 親グループにも $type がない場合、トークンの型は不明となり、そのトークンは MUST 無効とみなされます。

ツールが値の中身を検査して型を推測しては MUST NOT いけません。

$type プロパティは複数の階層で指定可能です：

• グループ階層
• トークン階層

$type の値は本仕様の型定義で指定された値のいずれかであり、プレーンなJSON文字列で MUST です。値は大文字小文字を区別します。

例：

オプションの $extensions プロパティは、ツールが独自やユーザー・チーム・ベンダー固有のデータを追加するためのオブジェクトです。各ツールはベンダー固有のキーを MUST で使い、その値は任意のJSONデータ MAY とできます。

• キーは他ベンダーとの競合可能性を避けるために SHOULD 工夫するべきで、逆ドメイン名記法 が推奨されます。
• デザイントークンファイルを処理するツールは、自身が理解できない拡張データも MUST 保存・維持する必要があります。（例：ツールA由来の拡張データ付トークンをツールBで開く場合も、保存時にツールA由来の拡張データを必ず含めること）

このフォーマット対応間の相互運用性を保つため、チームやツールは拡張データ用途をトークンの値理解に必須ではない任意のメタデータに限定する SHOULD です。

ベンダーは拡張仕様をできる限り公開するのが望ましいです。他ツールでも逆コンパイルなしで対応できるからです。普及した拡張は今後の仕様で標準機能入りする可能性があります。

$deprecated プロパティはトークンを非推奨としてマークする際、および理由の説明（任意）に MAY 使えます。非推奨の理由例：

• 今後のデザインシステムでこのトークンが削除される予定
• 今すぐ削除すると既存の対応が壊れる可能性がある
• 以後このトークンの利用は推奨しない

ツール開発者は、{button.activeBorder} のようなエイリアスを含む場合、文字列を拡張する MAY です。ツールはトークン解決や、ドキュメントやコードへのリンク、もしくはUI内で新しいトークンへのリンクやビジュアル表現をレンダリングできるかもしれません。例：「今後は {button.activeBorder} をご利用ください」は、JSでは次のように出力できます：

または

グループは $deprecated プロパティをオプションで含めてグループ全体を非推奨とマークすることが MAY あります。これは子トークンにも明示的に上書きされない限り適用されます。

グループは $extensions プロパティをオプションで含め、ツールが独自のユーザー・チーム・ベンダー固有のデータを追加することが MAY あります。各ツールはベンダー固有のキーを使用し、その値は任意の有効な JSON データである MAY です。

$extends プロパティは [json-schema-2020-12] に規定された JSON Schema の $ref キーワードと意味論的に等価です。次の 2 つのグループ定義は機能的に同一です：

$extends を使う（Design Token 構文）:

{
    "button-primary": {
        "$extends": "{button}",
        "background": {
        "$value": {
            "colorSpace": "srgb",
            "components": [0.8, 0, 0.4],
            "hex": "#cc0066"
        }
        },
        "focus": {
        "$value": {
            "colorSpace": "srgb",
            "components": [1, 0.2, 0.6],
            "hex": "#ff3399"
        }
        }
    }
    }
    

$ref を使う（JSON Schema 構文）:

{
    "button-primary": {
        "$ref": "#/button",
        "background": {
        "$value": {
            "colorSpace": "srgb",
            "components": [0.8, 0, 0.4],
            "hex": "#cc0066"
        }
        },
        "focus": {
        "$value": {
            "colorSpace": "srgb",
            "components": [1, 0.2, 0.6],
            "hex": "#ff3399"
        }
        }
    }
    }
    

拡張の解決は次の簡潔な手順に従います：

1. ターゲットを見つける： $extends 参照を解決してターゲットグループを特定する
2. 継承コンテンツをコピー： ターゲットグループのすべてのトークンとプロパティで開始する
3. ローカルの上書きを適用： 同一パスにローカルの定義がある場合は継承されたトークン／プロパティを置き換える
4. 新規コンテンツを追加： 継承グループに存在しないローカルのトークン／プロパティを含める

これにより、継承とローカルの内容を上記の上書きルールに従って組み合わせた新しい解決済みグループが作成されます。

グループ拡張はローカルのプロパティが同一パスの継承プロパティを上書きするという 深いマージ の振る舞いに従います：

1. 継承： 参照されたグループのすべてのトークンとプロパティが継承されます（循環参照は許可されません）
2. 上書き： 継承グループとローカルグループが同じパスでトークンを定義している場合、ローカル定義が勝ちます
3. 追加： 新しいパスを持つローカルのトークン／プロパティは継承されたものと共存します

上書きルール：

• 同一パス = 上書き： 継承元とローカルの両方が同一パスでトークンを定義している場合、ローカル定義が優先されます
• 異なるパス = マージ： 異なるパスのトークンは最終結果で共存します
• 完全な置換： 上書き時にはトークン定義全体が置換され、プロパティごとの部分マージは行われません

input-amount の結果：

多段階上書きの例：

extended の結果：

グループは循環的な継承チェーンを作成しては MUST NOT いけません。次のパターンは 無効 です：

有効な継承パターン：

$extends は デザイントークンのエイリアス と同じ参照形式をサポートします。

$extends のエラー処理は JSON Schema の $ref のエラーパターンに従います：

• 解決不能な参照： ターゲットグループが見つからない場合
• 無効なターゲット： 参照が非グループ（例：トークン）を指している場合
• 循環参照： 拡張チェーンがサイクルを作る場合
• 制約違反： ローカルプロパティが継承された制約に違反する場合

ツールは MUST JSON Schema バリデータが $ref 解決で使用するのと同様のエラー検出および報告パターンを実装しなければなりません。

デザイントークン解析を実装するツールは次のいずれかを MAY 選択できます：

1. $ref へ変換： $extends を標準 JSON Schema の $ref 構文に変換し、既存の JSON Schema ライブラリで検証を行う
2. ネイティブ実装： $extends を直接実装し、JSON Schema の $ref 処理と同じアルゴリズムを使用する
3. ハイブリッド： 検証に JSON Schema ライブラリを使用しながら、デザイントークン固有の参照構文を維持する

実装手法にかかわらず、意味論的な振る舞いは JSON Schema 2020-12 以降に規定される $ref と等価であることが MUST です。

本仕様は $extends を JSON Schema の $ref キーワードの構文糖衣として定義しており、デザイントークン固有の参照構文を提供しつつ等価な振る舞いを維持します。上記の深いマージ意味論は JSON Schema 2020-12 が兄弟プロパティとともに $ref を扱う方法と整合します。

JSON Schema に馴染みのある実装者向けには、$extends の動作は次と等価です：

• "$extends": "{group}" を "$ref": "#/group" に変換する
• JSON Schema 2020-12 の $ref 解決を兄弟プロパティ評価とともに適用する

ツールは MAY 次のいずれかを選択できます：

1. 変換アプローチ： $extends を $ref に変換して JSON Schema ライブラリを使用する
2. 直接実装： 上記の深いマージ動作を直接実装する
3. ハイブリッド： 検証に JSON Schema を使用しつつデザイントークン構文を維持する

実装手法にかかわらず、ユーザーに見える振る舞いは本仕様で説明される深いマージ意味論と一致することが MUST です。

ツールは [rfc6901] で定義される JSON Pointer 参照を MUST サポートし、$ref プロパティを使用する必要があります：

グループを処理する際、ツールは次の解決順序に従うことが MUST です：

1. ローカルトークン - $value プロパティを持つ直接の子
2. ルートトークン - $root 名のトークン
3. 拡張トークン - $extends を通じて継承されたトークン（上書きされていない場合）
4. ネストされたグループ - 再帰的に処理

トークンパスはグループ名とトークン名をピリオド（.）で連結して構築します。予約トークン名 $root は明示的かつ曖昧さのない参照を維持するためパスに含まれます。

例：

型の解決は次の優先順に従います：

1. トークンの明示的な $type プロパティ （最優先）
2. （拡張解決後の）解決済みグループの $type プロパティ
3. 親グループの $type プロパティ（階層を上って検索）
4. 型が判定できない場合はトークンは無効

拡張を伴う型解決： $extends は JSON Schema の $ref 意味論に従うため、型継承の振る舞いは明示的なマージ規則ではなく制約検証によって決定されます。ローカルの型制約は継承された制約とともに JSON Schema の検証パターンに従って評価されます。

この例では、グループ extended はローカルの $type: "dimension" 制約と、参照された base グループからの適用可能な制約の両方を満たす必要があり、JSON Schema の制約解決ルールに従います。

ツールは次での循環参照を検出してエラーを投げることが MUST です：

• トークンのエイリアス（エイリアス参照、{token}）
• グループ拡張（$extends 参照）
• JSON Pointer 参照（サポートされる場合の $ref プロパティ）

$extends の循環参照検出は JSON Schema の $ref の要件と同じです。ツールは循環検出のために JSON Schema バリデータが使うアルゴリズムを実装することを SHOULD 推奨します。

ツールはこの循環参照をグループ a、b、c に影響するエラーとして MUST 報告しなければなりません。

解決済みトークン：

• {input-amount.field.width} → { "value": 100, "unit": "px" } （上書き）
• {input-amount.field.background} → #ffffff（input から継承）

これはコンポーネントが基底コンポーネントを拡張しつつ、特定のトークンを上書きし他を継承する主要なユースケースを示します。

この構造は次のトークン参照でアクセス可能なトークンを生成します：

グループを使用することで、トークンファイルの作者はファイルをより整理しやすくなります。関連するトークンをグループにネストしてチームの命名規則やメンタルモデルと整合させることができます。手動でファイルを作成する場合、グループを使うほうが接頭辞を繰り返すフラットなトークン一覧より冗長性が少なく済みます。

例えば：

...は次のようなフラット構造より入力が簡単で読みやすい場合が多いです：

GUI を介してトークンを選択・編集させるツールはグルーピング構造を使って、折りたたみ可能なツリービューのような段階的な開示（progressive disclosure）を表示することが MAY あります。

トークン名は同一ファイル内で一意であることが保証されません。同じ名前が異なるグループで使われることがあります。また、変換ツールはコード内の変数のように一意に識別可能な方法でデザイントークンを出力する必要がある MAY あります。したがって、変換ツールはファイル内で一意であるためデザイントークンのパスを使用することを SHOULD です。

例えば、変換ツール のような Style Dictionary は、次のようなデザイントークンファイルを使用することがあります：

...そしてパスを連結して変数名を作成することで、次のようにSass変数として出力できます：

中括弧構文は完全なトークン値を参照するために設計されており、常にターゲットトークンの$valueプロパティに解決されます。

この例では、{colors.blue} は完全な色オブジェクト {"colorSpace": "srgb", "components": [0, 0.4, 0.8], "hex": "#0066cc"} に解決されます。

重要：中括弧参照は完全なトークン（$value プロパティを持つオブジェクト）のみをターゲットにでき、トークン値内の個々のプロパティや任意のドキュメント位置を指すことはできません。

トークン値内の特定のプロパティやドキュメント構造の他の部分にアクセスする高度なユースケースでは、トークンは [rfc6901] で定義される JSON Pointer 表記を $ref プロパティを使ってサポートすることが MUST です。本仕様を実装するツールは JSON Pointer 構文を MUST サポートします。

この例では：

• "$ref": "#/colors/blue/$value" は "{colors.blue}" と同等です
• "$ref": "#/colors/blue/$value/components/0" は blue 色の赤成分（0）だけにアクセスします

主な違い：

中括弧参照の場合：

1. 参照を解析： {group.token} からトークンパスを抽出する
2. パスを分割： セグメント ["group", "token"] に変換する
3. トークンへ移動： ターゲットトークンオブジェクトを見つける
4. トークンを検証： ターゲットが $value プロパティを持つことを確認する
5. トークン値を返す： $value の内容を抽出して返す
6. サイクルを確認： 解決中の参照のスタックを維持する

JSON Pointer 参照の場合：

1. JSON Pointer を解析： #/path/to/target からパスセグメントを抽出する
2. ドキュメントをトラバース： 各パスセグメントを通じて移動する
3. JSON Pointer ルールを適用：
   • 配列コンテキストの数値セグメントは配列インデックスになる
   • オブジェクトコンテキストのすべてのセグメントはプロパティ名になる
   • エスケープ文字（~0, ~1）を処理する
4. ターゲットを検証： 最終ターゲットが存在しアクセス可能であることを確認する
5. 値を返す： 解決された値を抽出して返す

エイリアスは他のエイリアスを参照することが MAY あります。その場合、ツールは明示的な値を持つトークンが見つかるまで各参照をたどることが MUST です。

この例では、{semantic.link} はチェーン semantic.link → semantic.brand → base.primary をたどって、{base.primary} と同じ色値に解決されます。

参照は循環しては MUST NOT です。デザイントークンファイルに循環参照が含まれる場合、そのチェーン内のすべてのトークンの値は不明となり、適切なエラーまたは警告メッセージをユーザーに表示することが SHOULD です。

ツールはこの循環参照を検出し、循環チェーン内のすべてのトークンに影響するエラーとして報告することが MUST です。

この例では：

• layout.small は base.spacing と同じ数値（16）を使い、単位は異なり rem を使います
• layout.large は base.spacing と同じ単位（px）を使い、数値は異なり 32 を使います

この例では：

• 両方の見出しは base.text から fontFamily と lineHeight を継承します
• 各見出しは独自の fontSize と fontWeight を定義します
• ベースのフォントファミリーや行間の変更は自動的にすべての見出しに反映されます

• ルート参照： #/（ドキュメントルートを指す）
• オブジェクトプロパティ： / は各レベルを分離する（例：#/group/token/$value）
• 配列インデックス： 配列要素に対する数値インデックス（例：#/color/$value/components/0）
• 特殊文字： JSON Pointer ルールに従ってエスケープする必要がある：
  • ~ は ~0 に
  • / は ~1 に

デザイントークンは値を $value プロパティに格納するため、トークン値への JSON Pointer パスは予測可能なパターンに従います：

1. JSON Pointer を解析： #/path/to/target からパスセグメントを抽出する
2. ドキュメントを横断： 各パスセグメントを通じて移動する
3. JSON Pointer ルールを適用：
   • 配列コンテキストの数値セグメントは配列インデックスになる
   • オブジェクトコンテキストのすべてのセグメントはプロパティ名になる
   • エスケープ文字（~0, ~1）を処理する
4. ターゲットを検証： 最終ターゲットが存在しアクセス可能であることを確認する
5. 値を返す： 解決された値を抽出して返す

1. 参照を解析： {group.token} からトークンパスを抽出する
2. パスを分割： セグメント ["group", "token"] に変換する
3. トークンへ移動： ターゲットトークンオブジェクトを見つける
4. トークンを検証： ターゲットが $value プロパティを持つことを確認する
5. トークン値を返す： $value の内容を抽出して返す
6. サイクルを確認： 解決中の参照のスタックを維持する

ツールは次のエラーを報告することが MUST です：

• 無効な構文： 中括弧や JSON Pointer 構文の不正
• 解決不能なパス： ターゲットパスがドキュメント内に存在しない
• 無効なトークン参照： 中括弧構文がトークン以外を指している場合
• 循環参照： 自分自身に戻る参照チェーン
• 型の不一致： 参照された値が期待される型と互換性がない場合

デザイントークン解析を実装するツールは次を MUST 満たす必要があります：

1. 中括弧構文をサポートすること — トークン間参照の主要な参照機構として
2. JSON Pointer 構文をサポートすること — ドキュメントレベルの参照およびプロパティアクセスのため
3. 参照ターゲットを検証すること — 中括弧は有効なトークンを、JSON Pointer は有効なドキュメント位置を指すことを確認する
4. 参照を解決すること — 本仕様の解決アルゴリズムに従う（Resolution Algorithms）
5. 循環参照を検出すること — 解決を試みる前に検出する
6. 参照を保持すること — メモリ/ストレージ内で参照を保持し、値が必要なときのみ解決する
7. 参照元の変更を伝播すること — 参照されるトークンの変更をすべてのエイリアスに伝播する

明確な解決：

ツールは次のエラーを報告することが MUST です：

• 無効な参照構文： 中括弧や JSON Pointer の構文が不正
• 解決不能な参照： ターゲットパスが存在しない
• 循環参照： 自分自身に戻る参照チェーン
• 型の不一致： 参照されたプロパティの型がトークンの型と互換性がない
• 無効なプロパティパス： 存在しないプロパティを参照しようとした場合

• $value.unit は "px" または "rem" のみ許容されます。
  • px: ビューポート上の理想化されたピクセルを表します。Android では dp、iOS では pt に相当します。翻訳ツールは必要に応じてこれらや他の同等単位へ変換することを SHOULD です。
  • rem: システムのデフォルトフォントサイズの倍数を表します（ユーザーによって設定可能な場合がある）。1rem はデフォルトフォントサイズの 100% を意味します。Android での 1rem の相当は 16sp です。すべてのプラットフォームに rem の相当があるわけではないため、翻訳ツールは既定フォントサイズ（通常 16px）を仮定して固定 px サイズへロスのある変換を行うことが MAY あります。
• $value.value が 0 の場合でも $value.unit は必須です。

• $value.unit は "ms" または "s" のみ許容されます。

文字列のストロークスタイル値は次の事前定義値のいずれかであることが MUST です：

• solid
• dashed
• dotted
• double
• groove
• ridge
• outset
• inset

これらの値は CSS の同等の「line style」値と同じ意味を持ちます。CSS 仕様に従い、正確なレンダリングは実装依存です。たとえば dashed スタイルでのダッシュとギャップの長さはツールによって異なる場合があります。

オブジェクトとして表されるストロークスタイル値は、次のプロパティを持つことが MUST です：

• dashArray: dimension 値 および/または dimension トークンへの参照の配列。交互に現れるダッシュとギャップの長さを指定します。配列の各要素は明示的な dimension 値か dimension トークンへの参照でなければなりません。要素数が奇数の場合は、その値のリストを繰り返して偶数にします。
• lineCap: 次のいずれかの事前定義文字列値のいずれかである必要があります："round"、"butt"、"square"。これらは SVG の stroke-linecap と同じ意味を持ちます。

文字列値とオブジェクト値は相互排他的な表現手段です。たとえば inset や groove のような文字列値は、ボーダーの一部の領域で色を明るく/暗くする実装固有の手段を必要とするため、単純に dashArray と lineCap で表現できない場合があります。逆に、正確に定義された dashArray と lineCap の組合せは、実装依存であるため dashed や dotted キーワードと完全に同一の見た目を保証しません。

さらに、一部のツールやプラットフォームはこの型が表現できるすべてのストロークスタイルをサポートしていない場合があります。そのため、ツールはネイティブにサポートしていない strokeStyle トークンを表示またはエクスポートする際に、サポートされている最も近い近似にフォールバックするべきです。

「最も近い近似」の選択方法は実装依存ですが、以下の例はツールがいくつかの状況で採用しうるフォールバックを示します。