Design Tokens Resolver Module

Abstract

This specification extends the format and describes a method to work with design tokens in multiple contexts (such as “light mode” and “dark mode” color themes).

A resolver is a JSON object with the following properties:

Name	Type	Required	Description
name	`string`		A short, human-readable name for the resolver.
version	`YYYY-MM-DD`	Y	Version, expressed as a ISO 8601 date.
description	`string`		Additional information about the resolver’s purpose.
tokens	(Set \| Modifier)[]	Y	Resolution order of tokens.

Users SHOULD name resolver files with a .resolver.json syntax.

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

Example 1: name

{
  "name": "Marketing Design System"
}

MUST be 2025-10-01. Reserved for future versions in case breaking changes are introduced.

{
  "name": "Marketing Design System",
  "version": "2025-10-01"
}

A resolver MAY provide additional information.

Example 2: name

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

The tokens key is an array that may contain any combination of sets and modifiers. The order is significant, with tokens later in the array overriding any tokens that came before them, in case of conflict.

Name	Type	Required	Description
type	`"set"`	Y	MUST be `"set"`.
name	`string`		Optional human-readable name for this set.
sources	<token-defs>	Y	The tokens that belong to this set.

Example 4: Sets

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

File strings from sources MAY be hoisted into the top-level tokens array as a simpler syntax.

Inline tokens (objects) MUST NOT ever be declared in tokens. An object inside tokens MUST be either a set or modifier.

Example 5: Shortened syntax

All of the following are equivalent, and will result in the exact same final tokens because the order is preserved. The grouping is at the user’s discretion, and is only used for the purposes of organization.

{
  "tokens": [
    "base/legacy.json",
    "base/foundation.json",
    "base/color-ramps.json",
    "base/semantic.json"
  ]
}

{
  "tokens": [
    {
      "type": "set",
      "sources": [
        "base/legacy.json",
        "base/foundation.json",
        "base/color-ramps.json",
        "base/semantic.json"
      ]
    }
  ]
}

{
  "tokens": [
    { "type": "set", "sources": ["base/legacy.json"] },
    { "type": "set", "sources": ["base/foundation.json"] },
    { "type": "set", "sources": ["base/color-ramps.json"] },
    { "type": "set", "sources": ["base/semantic.json"] }
  ]
}

A modifier can be thought of as a “conditional set,” where its contents depends on an external input. T

Name	Type	Required	Description
type	`"modifier"`	Y	This MUST be `"modifier"`.
name	`string`	Y	The name of the modifier. This MUST be unique among other modifiers in the same file.
context	`Record<string, <token-set>>`	Y	A key–value map of contexts to <token-defs>.
default	`string`		Optional default value. MAY be provided in case the input doesn’t require this value.

Tools MUST throw an error if 2 modifiers with the same name are declared in tokens.

Example 6: Modifier

{
  "tokens": [
    {
      "type": "modifier",
      "name": "theme",
      "context": {
        "light": ["themes/light.json"],
        "dark": ["themes/dark.json"]
      },
      "default": "light"
    }
  ]
}

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 default)

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 7: Inputs

Given the following modifiers:

{
  "tokens": [
    {
      "type": "modifier",
      "name": "theme",
      "context": [
        "light": ["light.json"],
        "dark": ["dark.json"]
      ]
    },
    {
      "type": "modifier",
      "name": "size",
      "context": {
        "default": ["size-default.json"],
        "large": ["size-large.json"]
      }
    },
    {
      "type": "modifier",
      "name": "beta",
      "context": {
        "false": [],
        "true": ["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": "true"
}

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 8: 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.

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 10: <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
Token flattening
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 tokens array in order.

Sets are loaded in the tokens array order.
If this uses simple syntax (string), treat it as if it is a set with no name, with a single item in the sources array.
Every token reference in sources MUST be resolved in array order.
For every token reference, merge with the previous set.
Aliases MUST NOT be resolved yet. That must happen at the end. Aliases MAY refer to values that will be supplied in upcoming steps.

Example 11: Conflict resolution

{
  "tokens": [
    {
      "type": "set",
      "name": "foundation",
      "sources": [
        {
          "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, two 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 12: Invalid conflict

{
  "tokens": [
    {
      "type": "set",
      "name": "foundation",
      "sources": [
        {
          "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 tokens 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.

Example 13: Simple syntax comparison

All of the following MUST be flattened in the same order, and are equivalent to one another:

{
  "tokens": ["base/foundation.json", "base/colors.json"]
}

{
  "tokens": [
    { "type": "set", "sources": ["base/foundation.json", "base/colors.json"] }
  ]
}

{
  "tokens": [
    { "type": "set", "sources": ["base/foundation.json"] },
    { "type": "set", "sources": ["base/colors.json"] }
  ]
}

Every modifier is applied in order, taking in the external input inputs.

For that modifier, load the corresponding input value.
1. If there is not an input value, load the default context.
2. If there is neither an input value nor default context, throw an error and stop resolution.
Load the context’s appropriate <token-defs> array that corresponds to the input value.
Flatten the <token-defs> array into the existing basis, in array order.

Example 14

Given the input:

{ "theme": "dark" }

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

{
  "tokens": [
    {
      "type": "modifier",
      "name": "theme",
      "context": {
        "light": ["colors/light.json"],
        "dark": ["colors/dark.json"]
      }
    }
  ]
}

Issue 3

Conflict resolution occurs when flattening sets or applying modifiers, and a token name appears 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 name 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.

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 15: Theme resolution

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

Name	Code
Resolver	`{ "tokens": [ { "type": "set", "sources": ["foundation.json"] }, "components/button.json", { "type": "modifier", "name": "theme", "context": { "light": ["themes/light.json"], "dark": ["themes/dark.json"] } } ] }`
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	`{ "theme": { "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).

Tokens flattening

The first item is a set containing ["foundation.json"] in sources. Load these in array order..

The second item is a set containing "components/button.json". Load that, and merge with the previous result, resulting 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"
    }
  }
}

The third item is a modifier with the name theme.
1. Taking the { "theme": "dark" } input results in ["themes/dark.json"].
2. Load that, and flatten with the previous result, resulting in:

{
  "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": "{theme.accent}"
    },
    "padding": {
      "$value": { "value": 8, "unit": "px" },
      "$type": "dimension"
    }
  }
}

Alias resolution
1. After all tokens have been loaded, {theme.accent} may now be resolved.

Resolution

The final result, with the aliases applied, results in:

{
  "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 takeaways:

Without the resolver, {theme.accent} is an invalid alias since it exited in a remote file.
Sets and modifiers are applied in declaration order.
The theme modifier did not have a default value. Therefore an error would have been thrown without an input.

Design Tokens Resolver Module

Abstract

Status of This Document

1. Introduction

2. Terminology

2.1 Resolver

2.2 Context

2.3 Set

2.4 Modifier

2.5 Input

2.6 Resolution

2.7 Orthogonal (orthogonality)

3. Syntax

3.1 Resolver file

3.2 Name

3.3 Version

3.4 Description

3.5 Tokens

3.5.1 Set

3.5.1.1 Shortened syntax

3.5.2 Modifier

3.6 Inputs

3.6.1 Orthogonality

3.7 <token-defs>

3.8 $extensions

4. Resolution Logic

4.1 Input validation

4.2 Token flattening

4.2.1 Sets

4.2.2 Modifiers

4.2.3 Conflict resolution (flattening)

4.3 Alias resolution

4.4 Resolution

5. Conformance

A. Acknowledgments

B. References

B.1 Normative references