References and Aliases

Why References Matter

References let you avoid duplication and build layered token systems: base tokens hold raw values and semantic tokens give them meaning. Change a base token once, and all references update.

Alias References

Syntax

Aliases use the {token.path} pattern. The referenced token’s value fully replaces the alias.

{
  "color": {
    "palette": {
      "blue-500": {
        "$type": "color",
        "$value": {
          "colorSpace": "srgb",
          "components": [0, 0.4, 0.8]
        }
      }
    },
    "action": {
      "brand": {
        "$root": {
          "$value": "{color.palette.blue-500}"
        }
      }
    }
  }
}

Type Inference

If the alias token omits $type, it inherits from the referenced token. Here, color.action.brand has type color from color.palette.blue-500.

Aliases in Composite Values

Aliases can reference other tokens inside composite values. The reference is resolved to the referenced token’s value.

{
  "border": {
    "default": {
      "$type": "border",
      "$value": {
        "color": "{color.palette.blue-500}",
        "width": { "value": 2, "unit": "px" },
        "style": "solid"
      }
    }
  }
}

Complete Example: Base → Semantic

{
  "color": {
    "palette": {
      "blue-500": {
        "$type": "color",
        "$value": {
          "colorSpace": "srgb",
          "components": [0, 0.4, 0.8]
        }
      }
    },
    "action": {
      "brand": {
        "$root": {
          "$value": "{color.palette.blue-500}"
        },
        "hover": {
          "$value": "{color.palette.blue-600}"
        }
      }
    }
  }
}

Resolved output (conceptually): color.action.brand, color.action.brand.hover, and color.palette.blue-500 all resolve to color objects. Semantic tokens reference the base palette, and themes can override semantic tokens per context.

Circular References

Dispersa detects and reports circular reference chains as required by the spec. If Token A references Token B, and Token B references Token A (directly or transitively), the build will fail with a clear error.

JSON Pointer References ($ref)

JSON Pointer references use the $ref property to point to tokens within the same file or in external files.

Syntax

Use $ref to point to another token or document. Fragment-only references stay in the same file:

{
  "$ref": "#/color/palette/blue-500"
}

References to other files include the path and fragment:

{
  "$ref": "./other-file.json#/color/palette/blue-500"
}

Token-Level vs. Property-Level

• Token-level $ref: The entire token is resolved from the target. No extra properties.
• Property-level overrides: When an object has both $ref and other properties, those properties override the resolved content. This is common in resolver documents for sets and modifiers.

Typical Use

$ref is mainly used in resolver documents to reference token sets and files. Alias references ({path}) are used inside token files to reference other tokens.

Token Layering Pattern

Layer	Role	Example
Base	Raw design values	color.palette.blue-500 = srgb [0, 0.4, 0.8]
Semantic	Meaningful abstractions	color.action.brand → base palette

This layering keeps base values centralized and lets you swap semantic mappings per theme or brand.

The Resolver Understand how sets, modifiers, and resolution order combine tokens.