Design Tokens Resolver Module

Abstract

This specification extends the [format](../format/) and describes a method to work with alternate values for [design tokens](../), such as “light mode” and “dark mode” color themes for supporting devices.

A resolver is a JSON object with the following properties:

Name	Type	Required	Description
name	`string`		A short, human-readable name for the resolver.
description	`string`		Additional information about the resolver’s purpose.
sets	Set[]	Y	Array of token subsets used as the base for resolution.
modifiers	Modifier[]		Array of modifiers that may provide alternate values.

A resolver MAY provide a human-readable name. This is used to identify the resolver.

Example 3: name

{
  "name": "Marketing Design System"
}

A resolver MAY provide additional information.

Example 4: name

{
  "name": "Marketing Design System",
  "description": "Last updated Summer 2025. Copyright Foo Corporation."
}

A resolver MUST provide an array of sets that combine to form the minimum set of design tokens. A set is an object with the following properties:

Name	Type	Required	Description
name	`string`		An optional identifier for this set.
values	<token-defs>	Y	The tokens that belong to this set.

Example 5: Sets

{
  "sets": [
    {
      "name": "color",
      "values": [
        "base/legacy.json"
        "base/foundation.json",
        "base/color-ramps.json",
        "base/semantic.json",
      ]
    },
    {
      "name": "typography",
      "values": [
        "base/scale.json",
        "base/web.json"
      ]
    },
    {
      "values": [
        {
          "space": {
            "base": {
              "100": {
                "$type": "dimension",
                "$value": { "value": 2, "unit": "rem" }
              }
            }
          }
        }
      ]
    }
  ]
}

Editor's note: Proposal

Some examples of the resolver spec used set names in the modifiers array to not only load sets by name, but also enforce a more granular order. But that syntax is missing. So

Adding an explicit way to reference a set that does NOT conflict with URLs, and does NOT conflict with the DTCG spec provides more functionality at no cost:

{
  "sets": [{ "name": "color", "values": [] }],
  "modifiers": [
    {
      "name": "theme",
      "values": [{ "name": "light", "values": [{ "$set": "color" }] }]
    }
  ]
}

But the tradeoff here is likely No sets load by default and MUST be loaded via include modifiers (otherwise, we’d have to add an “exclude” modifier which complicates things further).

Alternately, if we decide all sets are always included, no matter what, then we reduce sets to a <token-defs> array:

{
  "sets": ["color.json", "typography.json"]
}

A resolver MAY provide an array of modifiers that extend, append, and/or override the final token values. A modifier is an object with the following properties:

Name	Type	Required	Description
name	`string`	Y	The name of the modifier.
type	`"enumerated" \| "include"`	The type of modifier (default: enumerated)

An enumerated modifier adds the following additional properties:

Name	Type	Required	Description
values	`Input[]`	Y	The inputs required for this modifier.
meta	`Object`		Additional data for this modifier
meta.default	`string`		Declare the default value of the input, if none is provided.
meta.namespace	`string`		Namespace all tokens with a valid token name.

An enumerated modifier that allows users to omit an input value MUST specify a default value.

Example 6: Enumerated modifier

{
  "modifiers": [
    {
      "name": "theme",
      "type": "enumerated",
      "values": [
        {
          "name": "light",
          "values": ["themes/light.json"]
        },
        {
          "name": "dark",
          "values": ["themes/dark.json"]
        }
      ],
      "meta": {
        "default": "light",
        "namespace": "theme"
      }
    }
  ]
}

For inputs, the following inputs will provide the following result:

{ "theme": "light": } → ["themes/light.json"]
{ "theme": "dark": } → ["themes/dark.json"]
{} → ["themes/light.json"] (default specified in meta.default)

Editor's note

Proposal for modified syntax:

{
  "modifiers": [
    {
      "name": "theme",
      "type": "enumerated",
      "inputs": {
        "light": { "values": ["themes/light.json"] },
        "dark": { "values": ["themes/dark.json"] }
      },
      "default": "light"
    }
  ]
}

Removes structural problem where the schema can’t enforce values’ names are unique.
Rename values → inputs to reduce contextual use of “value” having different syntax in 3+ places.
- Also reinforces the name “inputs” which are referred to in other places
meta key removed for conflicting purposes—in some parts of the original specification it was schemaless; in others it held crucial information like aliasing & defaults
Move meta.default → default and meta.namespace → namespace

An include modifier adds the following additional properties:

Name	Type	Required	Description
values	`Input[]`	Y	The inputs required for this modifier.
meta	`Object`		Additional data for this modifier

This type of modifier is used to conditionally include a set of tokens. The values array for an include modifier contains objects with a name and a corresponding list of values (file paths or inline tokens) that will be included if that name is present in the input.

Example 7: Include modifier

{
  "modifiers": [
    {
      "name": "features",
      "type": "include",
      "values": [
        {
          "name": "experimental-feature-x",
          "values": ["features/feature-x.json"]
        }
      ]
    }
  ]
}

Editor's note

An input is a mapping of modifier names to modifier values declared in any resolver. Inputs are not part of the resolver file itself, rather, provided to the tool alongside the resolver. A resolver that declares any modifiers MUST be consumed with an input as options.

An input SHOULD be serializable to a JSON object. Meaning, an input MAY be expressed in any programming language, but that expression should be easily converted back into a JSON object. Related concepts would include an object in JavaScript or a dictionary in Python.

Tools that load a resolver that declares modifiers SHOULD throw an error if an accompanying input is not provided.

Example 8: Inputs

Given the following modifiers:

{
  "modifiers": [
    {
      "name": "theme",
      "type": "enumerated",
      "values": [
        { "name": "light", "values": ["light.json"] },
        { "name": "dark", "values": ["dark.json"] }
      ]
    },
    {
      "name": "size",
      "type": "enumerated",
      "values": [
        { "name": "default", "values": ["size-default.json"] },
        { "name": "large", "values": ["size-large.json"] }
      ]
    },
    {
      "name": "beta",
      "type": "include",
      "values": [{ "name": "enabled", "values": ["beta.json"] }]
    }
  ]
}

A valid input would follow the schema: all keys correspond to the name of each modifier. The values are valid options as designated by the modifier.

{
  "theme": "light",
  "size": "large",
  "beta": "enabled"
}

An invalid input would either add unspecified keys that don’t correspond to any modifier, and/or provide values that aren’t declared valid by any modifier type.

{
  "theme": "blue",
  "foo": "bar"
}

Example 9: Tool consuming input

Using an imaginary tool written in JavaScript, we would consume the previous example like so:

import tokenTool from './token-tool.js';

tokenTool.loadResolver(
  /* Path to resolver */
  './resolver.json',

  /* Input */
  {
    theme: 'dark',
    size: 'default',
  },
);

This imaginary tool has a loadResolver() method that takes as its parameters:

A filepath to the resolver in the first position, and
The input object in its 2nd position.

The tool then combines the resolver + inputs to produce its final resolution.

Namespacing allows for automatic prefixing of token names

Issue 4

Example:

Example 10

Given a tokens size.json:

{
  "sm": {
    "$value": { "value": 1, "unit": "px" },
    "$type": "dimension"
  },
  "lg": {
    "$value": { "$value": 10, "unit": "px" },
    "$type": "dimension"
  }
}

By applying an alias in the modifier's meta.alias, we can namespace these tokens:

{
  "modifiers": [
    {
      "name": "size",
      "type": "include",
      "values": [
        {
          "name": "default",
          "values": ["size.json"]
        }
      ],
      "meta": {
        "namespace": "spacing"
      }
    }
  ]
}

Resulting in the final token names spacing.sm and spacing.lg.

Issue 5

Modifiers are said to be orthogonal when they do not operate on the same set of tokens. In practical terms, if modifiers are orthogonal, then the order in which they are applied isn’t significant since they will produce the same values.

Implementors SHOULD make modifiers orthogonal. Tools MAY decide how to handle non-orthogonal modifiers.

An array consisting of:

string which MUST be a valid URI pointing to a valid Tokens JSON file, or
Inline objects that MUST follow valid format.

Any other inputs are invalid.

The array order is significant, where tokens with the same name overwrite previous instances of that token, if any.

Example 12: <token-defs>

[
  "base/colors.json",
  "theme/light.json",
  {
    "color": {
      "base": {
        "blue": {
          "100": {
            "$type": "color",
            "$value": {
              "colorSpace": "srgb",
              "components": [0, 0, 0.9]
            }
          }
        }
      }
    }
  },
  "base/size.json",
  "base/typography.json"
]

An $extensions object MAY be added to any set, modifier, or object in this spec to declare arbitrary metadata ignored by tooling. Its purpose in a resolver is the same as in the format.

Tools MUST handle the resolution stages in this order to produce the correct output.

Input validation
Set flattening
Modifier application
Namespacing
Alias resolution:
Resolution

Tools MUST require all inputs meet the schema described in that resolver’s modifiers syntax.

If a resolver does NOT declare any modifiers, skip this step and proceed to Sets flattening

For every key in the input object:
1. Verify it corresponds with a valid modifier. If it does not, throw an error.
2. Verify that key’s value corresponds with that modifier’s allowed values. If it does not, throw an error.
For every modifier in the resolver:
1. If that resolver does NOT declare a default value, verify a key is provided in the input. If not, throw an error.

Tools MUST iterate over the resolver’s sets syntax in order.

Starting with the first set:
1. Load the first item in the values array to form the basis for all tokens.
2. Load the next item in the values array, merging the objects together.
3. Resolve conflicts according to conflict resolution.
4. Aliases MUST NOT be resolved yet. That must happen at the end. Aliases MAY refer to values that will be supplied in upcoming steps.
5. Continue loading the next item in the values array, repeating steps 2–3.
6. After all values have been merged into the basis object, keep that in memory and continue onto the next set.
Continue onto the set, loading tokens in the same way as before.
1. Repeating the steps previously, you’ll also end up with a basis for this set—a single object containing all tokens referenced in the set.
Continue one-by-one through the remaining sets, until you have a collection of one basis object per set.
Return back to the first set, first basis, then merge the second set, second basis, and so on, until you reach the final set.
1. Resolve conflicts as every additional set is merged.
After all sets have been merged, there will be one single tokens object containing all tokens referenced.

Conflict resolution occurs when flattening sets or applying modifiers, and a token name is occupied by tokens of different values, from different sources. In many cases, this is intentional, but not always.

When 2 tokens try and occupy the same space, tools MUST resolve the conflict in the following manner:

If the token types are identical, overwrite the latter value with the former.
If the token types are incompatible, the tool MUST throw an error.
If one namespace is a token, and the other is a group, the tool MUST throw an error.
If one value is an alias (i.e. the $type is unknown), overwrite the value.

Example 13: Conflict resolution

{
  "sets": [
    {
      "name": "foundation",
      "values": [
        {
          "color": {
            "text": {
              "default": {
                "$value": { "colorSpace": "srgb", "components": [0, 0, 0] },
                "$type": "color"
              }
            }
          }
        },
        {
          "color": {
            "text": {
              "default": {
                "$value": {
                  "colorSpace": "srgb",
                  "components": [0.1, 0.1, 0.1]
                },
                "$type": "color"
              }
            }
          }
        }
      ]
    }
  ]
}

Here, 2 color.text.default tokens were supplied, one after the other. Since the order matters, the last declaration “wins” and the final result will be:

{
  "color": {
    "text": {
      "default": {
        "$value": { "colorSpace": "srgb", "components": [0.1, 0.1, 0.1] },
        "$type": "color"
      }
    }
  }
}

Example 14: Invalid conflict

{
  "sets": [
    {
      "name": "foundation",
      "values": [
        {
          "text": {
            "error": {
              "$value": { "colorSpace": "srgb", "components": [0.8, 0.1, 0] },
              "$type": "color"
            }
          }
        },
        {
          "text": {
            "error": {
              "font": { "$value": ["Consolas"], "$type": "fontFamily" },
              "color": {
                "$value": { "colorSpace": "srgb", "components": [0.8, 0.1, 0] },
                "$type": "color"
              }
            }
          }
        }
      ]
    }
  ]
}

These sets can not be merged, since text.error is a color token in the first item, and is a group in the second item. An error will be thrown.

Apply the selected modifiers based on the inputs. Modifiers can override tokens from the base sets or introduce new tokens.

For every modifier in the modifiers array, iterate in declaration order.
1. For that modifier, load the corresponding input value.
  1. If there is not an input value, load meta.default.
  2. If there is no default value, throw an error and stop resolution.
2. Load the <token-defs> array that corresponds to the input value, or default value.
3. Apply namespacing if meta.namespace is declared.
4. In array order, flatten each token using the same steps as set flattening.
5. At the end of the array, merge into the basis object created in the previous set flattening step.
Continue through all modifiers repeating the same process, merging into the basis each time.

Example 15

Given the input:

{ "theme": "dark" }

Then that would load only the tokens specified in the theme modifier, under the dark name value.

{
  "modifiers": [
    {
      "name": "theme",
      "values": [
        { "name": "light", "values": ["colors/light.json"] },
        { "name": "dark", "values": ["colors/dark.json"] }
      ]
    }
  ]
}

Issue 6

Alias resolution may only done after all sets and modifiers are handled, and there are no other tokens to merge in. Resolve aliases the same way as outlined in the format, allowing deep aliases but erring and stopping resolution on circular aliases and/or aliases that point to unresolvable types (such as aliasing a dimension token inside a gradient token, which is invalid).

After all aliases resolve correctly in the final set, the end result is one tokens object, that behaves as if it was a single JSON file to begin with.

Example 16: Theme resolution

We’ll start with the following file structure, followed by walking through the resolution stages step-by-step.

Name	Code
Resolver	`{ "sets": [ { "name": "foundation", "values": ["foundation.json"] }, { "values": ["components/button.json"] } ], "modifiers": [ { "name": "theme", "type": "enumerated", "values": [ { "name": "light", "values": ["themes/light.json"] }, { "name": "dark", "values": ["themes/dark.json"] } ], "meta": { "default": "light", "namespace": "theme" } } ] }`
Input	`{ "theme": "dark" }`
foundation.json	`{ "color": { "brand": { "primary": { "$value": { "colorSpace": "srgb", "components": [1, 0, 0], "hex": "#ff0000" }, "$type": "color" } } } }`
components/button.json	`{ "button": { "background": { "$value": "{theme.accent}" }, "padding": { "$value": { "value": 8, "unit": "px" }, "$type": "dimension" } } }`
themes/dark.json	`{ "accent": { "$value": { "colorSpace": "srgb", "components": [0, 1, 0], "hex": "#00ff00" }, "$type": "color" } }`

Input Validation
1. Verify that theme is a defined modifier (it passes).
2. Verify that dark is a valid value for the theme modifier (it passes).

Set flattening

Load foundation.json and components/button.json. File paths MUST be resolved relative to the location of the resolver file.

Flattening all sets resuls in:

{
  "color": {
    "brand": {
      "primary": {
        "$value": {
          "colorSpace": "srgb",
          "components": [1, 0, 0],
          "hex": "#ff0000"
        },
        "$type": "color"
      }
    }
  },
  "button": {
    "background": {
      "$value": "{theme.accent}"
    },
    "padding": {
      "$value": { "value": 8, "unit": "px" },
      "$type": "dimension"
    }
  }
}

Modifier application

Apply the theme modifier with value dark.
Load themes/dark.json

Apply namespacing as per meta.namespace ("theme"), resulting in:

{
  "theme": {
    "accent": {
      "$value": {
        "colorSpace": "srgb",
        "components": [0, 1, 0],
        "hex": "#00ff00"
      },
      "$type": "color"
    }
  }
}

Alias resolution
1. Resolve {theme.accent} in button.background.

Resolution. The final tokens will take the shape of:

{
  "color": {
    "brand": {
      "primary": {
        "$value": {
          "colorSpace": "srgb",
          "components": [1, 0, 0],
          "hex": "#ff0000"
        },
        "$type": "color"
      }
    }
  },
  "theme": {
    "accent": {
      "$value": {
        "colorSpace": "srgb",
        "components": [0, 1, 0],
        "hex": "#00ff00"
      },
      "$type": "color"
    }
  },
  "button": {
    "background": {
      "$value": {
        "colorSpace": "srgb",
        "components": [0, 1, 0],
        "hex": "#00ff00"
      },
      "$type": "color"
    },
    "padding": {
      "$value": { "value": 8, "unit": "px" },
      "$type": "dimension"
    }
  }
}

Key highlights:

The accent token was renamed to theme.accent because of the meta.namespace value.
Without a resolver, button.background would have an invalid alias since theme.accent is not in the same file.

Design Tokens Resolver Module

Abstract

Status of This Document

1. Introduction

1.1 Naïve approach

1.2 Resolver approach

2. Terminology

2.1 Resolver

2.2 Set

2.3 Modifier

2.4 Input

2.5 Alternate value

2.6 Resolution

2.7 Orthogonal (orthogonality)

3. Syntax

3.1 Resolver file

3.2 Name

3.3 Description

3.4 Sets

3.5 Modifiers

3.5.1 Enumerated type

3.5.2 Include type

3.5.3 Inputs

3.5.4 Namespacing

3.5.5 Orthogonality

3.6 <token-defs>

3.7 $extensions

4. Resolution Logic

4.1 Input validation

4.2 Set flattening

4.2.1 Conflict resolution

4.3 Modifier application

4.4 Alias resolution

4.5 Resolution

5. Conformance

A. Acknowledgments

B. References

B.1 Normative references