Design Tokens Community Group (DTCG) Specification

The Design Tokens Community Group (DTCG) is the official body responsible for the design tokens specification. The group's goal is to provide standards that allow products and design tools to share stylistic pieces of a design system (such as colors, spacing, and typography scales) across many tools and platforms at scale.

The specification is built on three core principles:

1. Inclusive: Empowering people of all skill levels to participate and implement tools.
2. Focused, yet extensible: Maintaining a small, simple footprint with zero dependencies while allowing for future extensibility.
3. Stable: Providing a long-term foundation by using existing and trusted standards.

Inlining is a bundling strategy where all reference objects ($ref) pointing to remote files are replaced with the actual contents of those files. This results in a single, portable JSON document.

Pros and Cons:

• Pro: Simplifies portability by reducing the document to a single file.
• Con: Causes data duplication. If the same file is referenced multiple times (e.g., in both light and dark contexts), its entire content is copied into every instance, which can make the document difficult for humans to read.

{
  "$schema": "https://www.designtokens.org/schemas/2025.10/resolver.json",
  "sets": {
    "foundation": {
      "sources": [
        {
          // (contents of foundation/colors.json)
        },
        {
          // (contents of foundation/size.json)
        }
      ]
    }
  }
}

While both use JSON syntax and support hierarchical structures, they serve different purposes:

Key takeaway: JSON is the syntax; DTCG is the semantics. DTCG defines how to use JSON to represent design tokens in a standardized, interoperable way.

Tools MUST implement circular reference detection and throw an error if a cycle is detected in any of the following:

• Token aliases: {token} references.
• Group extensions: $extends references.
• JSON Pointer references: $ref properties.

For $extends, tools SHOULD use the same algorithms used by JSON Schema validators for cycle detection. An error must be reported for all groups involved in the cycle.

{
  "a": { "$extends": "{b}" },
  "b": { "$extends": "{c}" },
  "c": { "$extends": "{a}" }, // Creates circular reference: a → b → c → a
}

A Resolver is a JSON document that extends the design tokens format to handle multiple contexts. It uses Modifiers (conditional sets of tokens) and Composition (the order in which tokens are combined) to produce different outputs.

• Input: A JSON-serializable object passed to a resolver that specifies which context values to use (e.g., { "theme": "dark", "size": "mobile" }).
• Resolution: A single possible permutation produced by a resolver for a specific input. For example, a resolver with a theme modifier (light/dark) and a size modifier (mobile/desktop) can produce 4 distinct resolutions: light-mobile, light-desktop, dark-mobile, and dark-desktop.
• Resolver file: A JSON file with the .resolver.json extension containing the sets, modifiers, and composition rules.

An Alias is a token value that references another token instead of a raw value. This allows you to create semantic layers (e.g., color.text.base) that point to primitive values (e.g., color.palette.black), making it easier to update themes or palettes globally.

In the JSON format, an alias is defined using the "$value" key with a string reference in curly braces.

{
  "$schema": "https://www.designtokens.org/schemas/2025.10/format.json",
  "color": {
    "palette": {
      "black": {
        "$type": "color",
        "$value": {
          "colorSpace": "srgb",
          "components": [0, 0, 0],
          "hex": "#000000"
        }
      }
    },
    "text": {
      "base": {
        "$value": "{color.palette.black}"
      }
    }
  }
}

To produce correct output, tools must process resolution in four specific, sequential stages:

1. Input validation: Verifying that the provided inputs match the declared modifiers and their allowed values.
2. Ordering: Tracing the resolutionOrder array to flatten sets and modifiers into a single tokens structure.
3. Aliases: Resolving token aliases (references) within the flattened structure.
4. Resolution: The final resulting tokens structure.

Note that aliases must not be resolved until after the ordering stage is complete.

Tokens may reference other aliases, creating a chain. Tools must follow each reference in the chain until they reach a token with an explicit $value. This allows for multi-layered semantic mapping (e.g., link → brand → primary → base_color).

{
  "base": {
    "primary": {
      "$value": {
        "colorSpace": "srgb",
        "components": [0, 0.4, 0.8],
        "hex": "#0066cc"
      },
      "$type": "color"
    }
  },
  "semantic": {
    "brand": {
      "$value": "{base.primary}"
    },
    "link": {
      "$value": "{semantic.brand}"
    }
  }
}