DTCG design token aliases: write, resolve, and verify references

First, identify the report that governs the file. This guide uses the published Design Tokens Format Module 2025.10, dated 28 October 2025. The DTCG FAQ describes 2025.10 as the first stable version and says the core format is suitable for production use. It also notes that the report is not on the W3C Standards Track and may be superseded. Calling a file "DTCG-compatible" is therefore incomplete. Record the target report.

The report is only one part of the execution contract. Pin the exact source file or export and its content hash. Then record the translation tool and version, its configuration, the generated destination, the consumer version, and the environment where you'll observe the result. If a tool converts the reference to another naming scheme, that conversion belongs to the tool contract, not DTCG itself.

The fixture below adapts the compact structure from the official glossary. It contains a concrete color token and one semantic token whose $value references it. For easier inspection, the alias repeats $type, although DTCG also defines type inheritance through groups and referenced values. DTCG 2025.10 defines curly-brace token references, required JSON Pointer support, and property-level references. The fixture and matrix here cover only curly-brace whole-token aliases.

{
  "$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": {
        "$type": "color",
        "$value": "{color.palette.black}"
      }
    }
  }
}

Read {color.palette.black} from the root through the nested names color, palette, and black. The path identifies the target token object. Resolving the alias yields that token's $value, which is the typed sRGB color object in this fixture. Before running a tool, you can record a precise expectation: color.text.base should resolve to the target color object. It remains an expectation until an identified translation tool produces evidence.

Alias investigations become muddled when one piece of evidence stands in for everything else. Use four named states instead. Each answers a different question, and each can fail after the previous state passes.

Suppose the source contains {color.palette.black} and you expect it to resolve to black. If a build emits --color-text-base: #000000, you have artifact evidence. You still don't know whether the application loaded that file, another stylesheet replaced the property, or the component uses a different role. Those questions belong to the consumer state.

Use the matrix to keep requirements separate from project expectations. Its first five rows concern the reference graph described by the published Format report. The remaining rows cover processing and consumption, where a DTCG-valid source can still produce the wrong project result.

Don't turn a tool's restriction into a DTCG rule. Tokens Studio describes references through its own authoring interfaces, available-token rules, token sets, and transformation workflow. GitLab's Pajamas guide adds its own naming conventions and project tooling. Both are useful operational sources within their environments. Neither replaces the published Format report as the portable contract.

For a direct reference, record one edge from the alias token to the target token. For a chain, list every edge in order. A semantic token might reference another semantic token, which eventually references a palette token. The final color alone isn't enough. Keep the ordered route because an intermediate token may change the meaning, type, or ownership of the decision.

{
  "color": {
    "palette": {
      "black": {
        "$type": "color",
        "$value": {
          "colorSpace": "srgb",
          "components": [0, 0, 0],
          "hex": "#000000"
        }
      }
    },
    "text": {
      "base": {
        "$type": "color",
        "$value": "{color.palette.black}"
      },
      "heading": {
        "$type": "color",
        "$value": "{color.text.base}"
      }
    }
  }
}

Before execution, label both hops and the final black value as expected. After execution, keep the tool's raw result or trace. If the tool reports only the final value, state that you didn't observe the intermediate traversal. Don't manufacture a trace from the source graph.

A missing target usually points to a source-composition problem: the name changed, a required file or set wasn't included, or the reference path is wrong. A circular chain is a graph problem because following the references returns to an earlier token. An incompatible value is a type problem. Keep the raw diagnostic. Different tools may describe these failures differently, even when they reject the same fixture.

Malformed JSON fails earlier. If a parser can't read the document, no alias-resolution claim has been tested. A translation tool crash isn't evidence that the reference is invalid either. It shows only that this execution failed. Route the report to the tool layer unless separate format evidence identifies a source violation.

1. 1

   Check the source identity

   Confirm that you inspected the same file, revision, export, or hash that entered the run. If not, stop and reconcile the inputs.

2. 2

   Check the authored reference

   Verify the reference text, target path, declared or inherited type, and every hop in a chain against the 2025.10 contract.

3. 3

   Check the translation tool observation

   Capture the pinned tool's raw result and warnings. If the tool didn't expose a result, keep resolution unresolved.

4. 4

   Check the transformation

   Inspect the configuration and generated artifact. Record renaming, value conversion, filtering, mode selection, or reference preservation as tool behavior.

5. 5

   Check the consumer mapping

   Identify the exact emitted symbol used by the named component or surface. Look for stale imports, local literals, overrides, wrong modes, and old bundles.

6. 6

   Assign a disposition and owner

   Accept only the tested scope. Revise when the failure has an owned correction. Block when required evidence is missing or a mismatch could reach protected consumers.

Keep two columns in your working notes. Under "DTCG 2025.10," record the published reference syntax, resolution obligations, type rules, and specified error cases. Under "tool or project," record token-set visibility, naming policies, UI behavior, transformation options, and project commands. This keeps a local restriction from becoming a false statement about the exchange format.

Keeping the contracts separate also makes upgrades easier to review. A newer DTCG report may change the portable contract. A Tokens Studio, transformer, or project upgrade may change only the local execution. Record both versions so you can see which boundary moved.

Choose one alias instead of auditing the entire token system at once. A narrow trace gives you evidence you can review and repeat. Expand the audit only after the first record reveals the actual processing stages in your stack.

1. 1

   Freeze one source

   Save the source locator, content hash, DTCG target, alias path, and referenced path. Don't switch exports during the run.

2. 2

   State the expectation

   Record the expected final type and value, plus every expected hop. Mark these fields as expectations.

3. 3

   Execute the identified tool

   Run the project's normal translation tool with a pinned version and configuration. Preserve raw output and warnings.

4. 4

   Inspect the artifact

   Find the emitted symbol or retained reference in the generated output. Record the artifact hash and exact excerpt.

5. 5

   Inspect a named consumer

   Select one component, property, state, and environment. Capture the computed or otherwise observed value and the artifact it loaded.

6. 6

   Compare without collapsing states

   Compare the expectation with tool output, artifact content, and consumer observation. A match at one layer doesn't repair a mismatch at another.

7. 7

   Decide the tested scope

   Choose accept, revise, or block. Name unresolved fields, the owner, and the condition for reopening the decision.

Keep this record beside the change or build evidence. The format is tool-neutral. Write unobserved instead of guessing, and preserve raw diagnostics so useful detail isn't lost in paraphrasing.

alias_acceptance:
  source:
    locator: "path, export ID, or immutable source URL"
    revision: "commit, export version, or unobserved"
    sha256: "content hash"
  contract:
    format_report: "DTCG 2025.10"
    schema_declaration: "value copied from source or absent"
  reference:
    alias_path: "color.text.base"
    authored_value: "{color.palette.black}"
    expected_target: "color.palette.black"
    expected_type: "color"
    expected_value:
      colorSpace: "srgb"
      components: [0, 0, 0]
      hex: "#000000"
    expected_chain:
      - "color.text.base -> color.palette.black"
  processing:
    tool: "name"
    version: "exact version"
    operation: "resolve, transform, build, or inspect"
    configuration: "config identity or hash"
    raw_result: "verbatim result or unobserved"
    warnings: "verbatim warnings or none observed"
  artifact:
    locator: "generated file or artifact ID"
    sha256: "artifact hash or unobserved"
    emitted_symbol: "platform identifier or retained reference"
    emitted_value: "observed value or unobserved"
  consumer:
    name: "component or surface"
    version: "application revision"
    environment: "platform, mode, viewport, and build"
    property: "property that consumes the token"
    observed_value: "computed or inspected value, or unobserved"
    evidence_locator: "log, snapshot, report, or inspection record"
  decision:
    disposition: "accept | revise | block"
    scope: "exactly what this decision covers"
    owner: "person or team"
    unresolved_fields: []
    follow_up_condition: "evidence required to reopen or complete"

Use accept when every required field for the declared scope has support and the observations match the contract. Use revise when you understand the mismatch, have safely bounded it, and have assigned an owner. Use block when a required target can't resolve, a cycle or type conflict remains, the wrong artifact reaches a consumer, or essential evidence is absent.

Identity Forge ships DTCG token exports as part of its implementation-ready kit output, so an upstream artifact is available. This fact doesn't reveal whether a particular export contains aliases, how any alias graph is arranged, which translation tool behavior it relies on, or whether your consuming project supports it. Obtain the actual export through the product's supported workflow, record its identity, and inspect the contents. If you find a $value reference, choose one and complete the acceptance record. If the selected token uses a concrete value, record that fact. Don't invent an alias test. Either result is useful because it describes the artifact you received.

• A public kit preview doesn't reveal the export's alias structure.
• A DTCG declaration doesn't prove that your chosen translation tool implements every relevant behavior.
• Claim compatibility with Tailwind, shadcn, a design tool, or an application only after executing and observing the named path.
• Keep Identity Forge upstream. Your translation tool, generated artifact, application mapping, and local overrides remain separate evidence layers.

• Design Tokens Format Module 2025.10: The published Format report defines the 2025.10 exchange format, alias reference syntax, resolution requirements, type constraints, and error conditions used in this guide.
• DTCG Glossary: The glossary defines an alias as a token value that references another token and provides a compact color-reference example.
• DTCG FAQ: The FAQ identifies 2025.10 as the first stable DTCG version while noting that the specification remains in development and is not on the W3C Standards Track.
• Token Values with References - Tokens Studio for Figma: Tokens Studio documents reference authoring through its own token sets, interfaces, terminology, and transformation workflow, showing the difference between DTCG rules and product behavior.
• Authoring design tokens - Pajamas Design System - GitLab: GitLab documents DTCG token and alias authoring within the conventions and tooling of its Pajamas design system.
• Identity Forge: Identity Forge publicly documents DTCG tokens as one of the export formats available in its design-kit workflow.