Anatomy of a Token

Token Structure

A design token is a JSON object. Spec-defined properties use a dollar prefix ($); group and token names defined by you do not.

Example Path

color>brand>primary= color.brand.primary

$type

requiredinherited

colorDefines the token type. Can be set on a group so all children inherit it.

$valuerequired

{
  "colorSpace": "srgb",
  "components": [
    0.2,
    0.4,
    0.9
  ]
}

#3366e6

The token value. Format depends on the type (color object, dimension, etc.).

$descriptionoptional

"Primary brand color used for CTAs and links"Human-readable documentation. Appears in generated code comments.

$deprecatedoptional

"Use color.brand.blue instead"Marks the token as deprecated. Can be a boolean or a message string.

$extensionsoptional

{
  "com.figma": {
    "styleId": "S:abc123"
  }
}

Vendor-specific metadata. Reserved for tooling, not part of the core spec.

Core Properties

$value (required unless $ref is used)

The token’s value. Every token must provide either $value (a direct value or curly-brace alias) or $ref (a JSON Pointer reference) — but not both.

{
  "color": {
    "brand": {
      "primary": {
        "$type": "color",
        "$value": {
          "colorSpace": "srgb",
          "components": [0, 0.4, 0.8]
        }
      }
    }
  },
  "spacing": {
    "md": {
      "$type": "dimension",
      "$value": {
        "value": 16,
        "unit": "px"
      }
    }
  }
}

$type (required or inherited)

The token’s type. Can be set directly on the token or inherited from a parent group. Every token must have a determinable type — either its own $type property or one inherited from an ancestor group. Valid types: color, dimension, fontFamily, fontWeight, duration, cubicBezier, number, shadow, typography, border, strokeStyle, transition, gradient.

$description (optional)

Human-readable description for the token.

{
  "color": {
    "brand": {
      "primary": {
        "$type": "color",
        "$value": {
          "colorSpace": "srgb",
          "components": [0, 0.4, 0.8]
        },
        "$description": "Primary brand color used for CTAs and links"
      }
    }
  }
}

$deprecated (optional)

Marks a token as deprecated. Use a boolean or a string message.

{
  "$type": "color",
  "$value": {
    "colorSpace": "srgb",
    "components": [0.8, 0, 0.4]
  },
  "$deprecated": "Use color.brand.primary instead"
}

$extensions (optional)

Vendor-specific metadata reserved for tooling.

{
  "$type": "color",
  "$value": {
    "colorSpace": "srgb",
    "components": [0, 0.4, 0.8]
  },
  "$extensions": {
    "com.figma": {
      "styleId": "S:abc123"
    }
  }
}

Group Nesting

Tokens can be nested in groups. Group names become part of the token path (e.g. color.brand.primary). Groups can set $type so all children inherit it.

Group-level $type

Set $type on a group to avoid repeating it on every child token. Child tokens inherit the type unless they override it.

{
  "color": {
    "$type": "color",
    "brand": {
      "primary": {
        "$value": {
          "colorSpace": "srgb",
          "components": [0, 0.4, 0.8]
        }
      },
      "secondary": {
        "$value": {
          "colorSpace": "srgb",
          "components": [0.4, 0.4, 0.4]
        }
      }
    }
  }
}

Here, color.brand.primary and color.brand.secondary both have type color from the group.

$root (optional)

A root token for a group. The $root token provides a base value for the group while allowing nested variants or extensions.

{
  "spacing": {
    "$type": "dimension",
    "$root": {
      "$value": { "value": 16, "unit": "px" }
    },
    "small": {
      "$value": { "value": 8, "unit": "px" }
    },
    "large": {
      "$value": { "value": 24, "unit": "px" }
    }
  }
}

$extends (optional)

Inherits tokens and properties from another group. Uses curly-brace or JSON Pointer syntax.

{
  "button": {
    "primary": {
      "$type": "color",
      "background": {
        "$value": { "colorSpace": "srgb", "components": [0, 0.4, 0.8] }
      }
    },
    "secondary": {
      "$extends": "{button.primary}",
      "background": {
        "$value": { "colorSpace": "srgb", "components": [0.4, 0.4, 0.4] }
      }
    }
  }
}

The Dollar-Prefix Convention

Spec-defined properties ($value, $type, $description, $deprecated, $extensions, $ref, $root, $extends) start with $

Token Types A complete reference of all DTCG token types — primitives and composites.