Copyright © 2025 the Contributors to the Design Tokens Resolver Module 2025.10 Specification, published by the Design Tokens Community Group under the W3C Community Final Specification Agreement (FSA). A human-readable summary is available.
この仕様はフォーマットを拡張し、 複数のコンテキスト（例えば「ライトモード」や「ダークモード」などのカラーテーマ）で デザイントークンを扱う方法について記述します。
この仕様は デザイントークン・コミュニティグループによって公開されました。 これは W3C 標準ではなく、また W3C 標準トラックにもありません。 W3C コミュニティ最終仕様合意書（FSA） の下で他の条件が適用されることにご注意ください。 W3C コミュニティおよびビジネスグループについて詳しくはそちらをご覧ください。
このセクションでは、公開時点でのこの文書のステータスについて説明します。 他の文書がこの文書に取って代わる場合があります。 現在の W3C コミュニティグループのレポート一覧や、本レポートの最新版は W3C コミュニティグループ レポートインデックス https://www.w3.org/community/reports/ でご覧いただけます。
この文書は DTCG より 候補勧告 として W3C プロセスで定義された説明に従い公開されました。 このドラフトへの貢献は コミュニティ貢献者ライセンス契約（CLA） に従って管理されており、 W3C コミュニティグループプロセス で規定されています。
これは W3C 勧告ではありませんが、 この分類は徹底的な合意形成の後、この仕様が実装を意図していることを明確にするものです。
この仕様は安定と見なされています。 今後の更新は後続の仕様で提供されます。
この仕様についての議論には GitHub Issues の利用が推奨されます。
このセクションは規範的ではありません。
デザイントークンの利用者は、異なるコンテキストで適用される代替値を表現する必要がよくあります。例として、以下に挙げるものに限定されませんが：
しかし、これらの代替コンテキストは組合せ爆発の影響を受けやすく、保存や管理が扱いにくくなります。
このフォーマットは、すべてのコンテキストにわたるトークンの重複する値を排除する仕組みと、すべてのコンテキストの順列を列挙する方法を記述します。
このセクションは規範的ではありません。
各々が排他的なトークン上で動作する、2つ以上のコンテキストを記述する特性、すなわち重なりがないこと。修飾子は直交してもよいですが、必須ではありません。
修飾子を可能な限り直交化することで、認知的負荷を減らし、ユーザーのエラーを減らします。
順列とは、リゾルバードキュメントの単一の可能な配置のことです。順列は input と 1:1 で対応しますが、「input」は使用される修飾子コンテキストを強調し、「順列」は最終的なトークン集合を強調します。
リゾルバードキュメントは標準の JSON 構文（[RFC8259]）を必ず使用しなければなりません。
ツールは、JSONC や JSON5 といった拡張をサポートしてもよいですが、ドキュメントが通常の JSON に変換でき、トークン値に影響しないことが条件です。
ユーザーはリゾルバードキュメントの名前に .resolver.json というファイル拡張子を使用すべきです。
リゾルバードキュメントを HTTP 経由で送信する際、ユーザーは Content-Type ヘッダー（[RFC1341]）に期待される
application/json の MIME タイプ（[RFC6838]）を使用すべきです。
ユーザーは、カスタムまたは予期しない MIME タイプを使用してはなりません。
リゾルバードキュメントは、ルートレベルで以下のプロパティを含みます：
| Name | Type | Required | Description |
|---|---|---|---|
| name | string |
ドキュメントの短い人間可読の名前。 | |
| version | YYYY.MM |
Y | バージョン。2025.10でなければなりません。 |
| description | string |
このドキュメントの人間可読の説明。 | |
| sets | Map[string, Set] |
セットの定義。 | |
| modifiers | Map[`string, Modifier] | 修飾子の定義。 | |
| resolutionOrder | (ReferenceObject | Set | Modifier)[] |
Y | セットと修飾子の解決順。 |
ドキュメントはルートレベルに人間可読の name を提供してもよいです。これは、ファイル名だけでは十分でない場合に、別のリゾルバードキュメントと区別するのに役立ちます。
ドキュメントはルートレベルにバージョンを必ず提供しなければならず、必ず2025.10 である必要があります。これは、将来破壊的変更が導入された場合に備えた予約です。
ドキュメントはルートレベルに description を提供してもよいです。これは name に存在しない追加の説明やコンテキストを加えるために使用できます。
セットは、DTCG フォーマットのデザイントークンの集合です。セットは、直接宣言されたトークンを含む sources
配列、またはデザイントークンを含む JSON ファイルを指す参照オブジェクト、あるいはその両方の組み合わせを必ず含まなければなりません。
セットは、セットの目的を説明する description を含めてもよいです。
配列が複数のソースを宣言する場合、それらは配列順にマージされます。つまり、トークンが複数回宣言されている場合、配列内の最後の出現が最終値になります。ツールは配列の順序を必ず尊重しなければなりません。
修飾子は set に似ていますが、contexts マップを通じて条件付きの取り込みを可能にします。
修飾子は、string 値からトークンソースの配列への contexts マップを必ず宣言しなければなりません。トークンソースの配列は、ReferenceObject、インライントークン、またはその両方の組み合わせでなければなりません。
修飾子は 2 つ以上の contexts を持つべきです。1 つだけだと set と同等になるためです。修飾子は空の contexts マップを持ってはなりません。ツールはコンテキストが 1 つしかない修飾子に対してエラーを投げるべきです。コンテキストが 0 の修飾子に対しては必ずエラーを投げなければなりません。
sets と同様に、配列の順序は必ず尊重され、競合がある場合には配列内の最後のトークンの出現が最終値を生成します。
修飾子はコンテキスト値の中で set を参照してもよいです。ただし、修飾子は他の修飾子、同じ修飾子内の別コンテキストを含め、参照してはなりません。
修飾子は人間可読の description を宣言してもよいです。
修飾子は contexts のキーのいずれかに必ず一致する default 値を宣言してもよいです。値が contexts に存在しない場合、ツールは必ずエラーを投げなければなりません。
ドキュメントが生成し得る解決の数は、すべての修飾子にわたる
contexts の総数の積で予測できます。
resolutionOrder キーは、最終的なトークンの結果を生成するために順序付けられた sets と modifiers の配列です。順序は重要で、競合がある場合には配列の後方のトークンが前方のトークンを上書きします。
resolutionOrder において、set または modifier
は、name と type キーがオブジェクトに追加される限り、インラインで宣言してもよいです：
| Property | Type | Required | Description |
|---|---|---|---|
| name | string |
Y | 他のresolutionOrder 内のいかなる
name とも衝突してはならない一意な名前。
|
| type | "set" | "modifier" |
Y | タイプに応じて "set" または "modifier" でなければなりません。
|
ツールは、インラインオブジェクトから name または type が欠落している場合、または name
がいずれかのオブジェクト間で重複している場合には、必ずエラーを投げなければなりません。
インラインセットと修飾子は、いかなる方法でも参照してはなりません。参照オブジェクトが解決順の項目を指している場合、ツールはエラーを投げるべきです。
このセクションは規範的ではありません。
resolutionOrder
配列は、ユーザーの選択による任意のセットと修飾子の順序付けを可能にします。しかし、多くのセットが競合解決のために修飾子の後に置かれなければならないような状況では、予測不能で壊れやすいトークン構成のコードスメルである可能性が高いです。理想的には、修飾子は条件付きの値を十分に扱い、上書きがほとんど（あるいは全く）不要となります（直交性参照）。実務的には、これは次を意味します
別の JSON ドキュメントや同一ドキュメント内の構造を参照する場合、参照オブジェクトを使用しなければなりません。これは JSON Schema 2020-12
において、$ref キーを持ち、その文字列が [RFC6901] に記述された有効な JSON
ポインタであるオブジェクトとして説明されています。
ツールはリゾルバードキュメント内のすべての参照オブジェクトを必ず解決しなければなりません。
参照オブジェクトは循環してはなりません。すなわち、自身を参照する他のポインタを参照したり、参照オブジェクトの親ノードを参照したりしてはなりません。
ツールは同一ドキュメント内参照オブジェクトを必ずサポートしなければなりません。これはこのリゾルバーモジュールをサポートするための最小要件です。それ以外については、ツールはローカルファイルシステム上のファイルのインポートや TCP/IP 経由のリモート URI など、いくつかの URI タイプをサポートしないという個別の判断を行っても構いません。
ポインタは同一ドキュメント内のどこを指してもよいですが、次の例外があります：
#/modifiers/…）を参照できます。セットおよび修飾子は他の修飾子を参照してはなりません。
#/resolutionOrder/…）内のいかなるものも、参照オブジェクトが指してはなりません。解決順はその性質上、ドキュメントの多くの部分を参照します。これのいかなる部分を複製しても、複雑で予測困難な連鎖を生じます。
ツールは、無効なポインタに遭遇した場合、必ずエラーを投げなければなりません。
JSON Schema 2020-12
が許すように、参照オブジェクトには $ref と並んで他のキーが存在してもよいです。このような場合、$ref と並ぶローカルキーは上書きとして扱わなければなりません。
$ref と並ぶキーがオブジェクトまたは配列を宣言している場合、ツールはこれらを浅くフラット化しなければなりません。つまり、オブジェクトや配列はマージされません。
$extensions オブジェクトは、任意の set、modifier、または インラインの set/modifier に追加してもよいもので、個々のツールが使用するか無視するかは任意のメタデータを宣言します。
提供される場合、$extensions はベンダー固有の名前空間をキーとするオブジェクトでなければなりません。これにより、複数のツールがこのメタデータを衝突なく使用できます。
ツールは JSON Schema の $defs
で構造を定義することを許可してもよいですが、必須ではありません。ただし、ツールは $defs に遭遇した際にエラーを投げてはなりません。未対応の場合はそのキーを無視しなければなりません。
リゾルバードキュメントは、条件付きトークン値が生成されてもよい方法のみを記述します。しかし、その条件はどこかで依然として提供される必要があります。「入力」という用語は、ツールに渡されるコンテキスト値の任意の選択を指します。
ツールは、JSON シリアライズ可能なオブジェクト（例えば、JavaScript のオブジェクトや Python の辞書）としての入力を必ず受け付けなければなりません。
修飾子を宣言するリゾルバを読み込むツールは、付随する入力が提供されない場合、エラーを投げるべきです。
入力は大文字・小文字を区別しないべきです。例えば、
{ "theme": "dark" }、{ "Theme": "Dark" }、{ "THEME": "DARK" } は
同等であるべきです。ただし、ツールは大文字・小文字の区別について個別の判断をしてもよいです。
入力の値は必ず文字列でなければなりません。入力に { "beta": true } や
{ "size": 100 } のような非文字列の値が含まれている場合、ツールは必ずエラーを投げなければなりません。
ツールは正しい出力を得るために、解決の段階を必ず処理しなければなりません。
resolutionOrder 配列の追跡。ツールは、すべての入力が、提供された修飾子のコンテキストに一致することを必ず要求しなければなりません。
リゾルバが修飾子を宣言していない場合は、このステップをスキップして順序付けに進みます。
ツールはresolutionOrder 配列を順番に反復処理しなければなりません。
配列内の各項目について、それがsetかmodifierかを判定し、配列順に単一のトークン構造へフラット化します。
sources を結合して単一のトークン構造を生成します。contextのみを選択し、配列を順に結合して単一のトークン構造を生成します。
resolutionOrder 配列の最後まで到達するまで繰り返します。
最終結果は、最初から単一のソースであったかのように動作するトークン構造になります。
エイリアスはこのステップまで解決してはなりません。
順序付けが単一のトークン構造にフラット化された後、残る唯一のステップはエイリアスの解決です。エイリアスは フォーマットで概説されているのと全く同じ方法で解決されます：
$type を指していなければなりません。このセクションは規範的ではありません。
リゾルバードキュメントは、整理のためにトークンの使用を複数の JSON ファイルに分散させることを許可します。しかし、移植性の観点からは、単一の JSON ドキュメントのみを扱う方が有利な場合があります。
「バンドル」は、リゾルバードキュメントを単一ファイルにまで縮約するプロセスを指します。これを達成する戦略は複数あり、本ドキュメントで概説する以上のものがあります。しかし、説明のために、ここでは多数ある可能なアプローチのうち 2 つを概説します：
インライン化とは、リモートファイルへのすべての参照オブジェクトを取り出して、その内容に置き換えることです。これは最終目標を達成する単純な戦略ですが、同じファイルが複数回参照される場合には重複が発生します。ツールは重複したトークンに問題を抱えないかもしれませんが、このドキュメントを読む人間は、おそらく生成されるコード行数の多さに苦労するでしょう。
$defs で説明されているように、$defs はリゾルバードキュメントにおいて定義済みの挙動を持ちません。JSON Schema
のこの機能をサポートすることをツールが決定した場合にのみ使用できます。
この戦略は、トップレベルに $defs キーを作成し、各トップレベルキーにそのファイルの内容を含めることを伴います。
$defs を使用する唯一の欠点は、リゾルバードキュメントの最小要件ではないため、一部のツールがそれを無視することを選ぶ場合がある点です。
非規範的とマークされたセクションに加えて、本仕様のすべての執筆ガイドライン、図表、例、および注記は非規範的です。それ以外の本仕様のすべては規範的です。
この文書におけるキーワード MAY、MUST、MUST NOT、SHOULD、SHOULD NOT は、 BCP 14 [RFC2119] [RFC8174] に記載されているとおり、ここに示すように全面大文字で現れる場合にのみ、解釈されます。
リゾルバ仕様を実装するツールは必ず次を行わなければなりません：
このセクションは規範的ではありません。
このリゾルバ仕様は、Hyma チーム（Mike Kamminga、Andrew L’Homme、Lilith などを含むがこれらに限定されない）の支えなしには実現しませんでした。 また、Joren Broekema、Louis Chenais による重要な貢献がありました。Design Tokens Community Group のメンバーによる 貢献とフィードバックに感謝いたします。