Token JSON format

#Overview

This page describes the JSON format for token files in the Tokens tab. It follows the DTCG shape ($value, $type, $extensions, …). For component files ($type: "composition"), see Composition.

Every node is either a token or a group:

#File root

The root must be a JSON object (arrays, strings, and numbers are rejected by validation).

{
  "colors": {
    "brand": {
      "primary": {
        "$value": "#635BFF",
        "$type": "color"
      }
    }
  }
}

#Core fields

#$value forms

String:

{ "$value": "#635BFF", "$type": "color" }
{ "$value": "16px", "$type": "spacing" }
{ "$value": "Inter", "$type": "fontFamily" }

Number / Boolean:

{ "$value": 8, "$type": "number" }
{ "$value": true, "$type": "boolean" }

Pure alias — one dot-notation path inside {...}:

{ "$value": "{colors.brand.primary}", "$type": "color" }

Math expression (alias embedded in a string):

{ "$value": "{spacing.base} * 2", "$type": "spacing" }
{ "$value": "clamp(16px, {spacing.base} * 4, 64px)", "$type": "sizing" }

Object / Array (composite values):

{
  "$value": { "fontFamily": "Inter", "fontSize": "16px", "fontWeight": 500, "lineHeight": "24px" },
  "$type": "typography"
}

{
  "$value": [{ "type": "DROP_SHADOW", "x": 0, "y": 2, "blur": 8, "spread": 0, "color": "#00000033" }],
  "$type": "shadow"
}

#Token types ($type)

SXL Studio supports 38 canonical token types. What each type does on Export Variables & Styles is the clearest way to group them.

Exported as Figma variables (17) — scalar tokens that become variables in a collection.

Exported as Figma styles (10) — composite tokens that become local styles.

Internal / editable only (11) — fully editable in SXL Studio and used by plugin logic or rendering, but not exported directly as a variable or style: border, strokeStyle, fontStyle, textCase, textDecoration, transition, duration, cubicBezier, template, composition, custom.

Full per-type behavior: Token types.

#$type normalization

Legacy and plural $type values are normalized automatically to the canonical key.

Tokens Studio exports (legacy value / type / extensions) can be converted through Migrate from Tokens Studio.

#Type resolution and inference

$type is resolved in this order:

If nothing resolves, validation reports an error. When no $type is present or inherited, the parser infers from the $value shape:

#$extensions

figma.scopes — variable scope hints for export:

{ "$extensions": { "figma.scopes": ["ALL_FILLS", "STROKE_COLOR"] } }

The full scope list and per-type defaults live on Scopes & Code Syntax.

figma.codeSyntax — Dev Mode snippets. Use the keys exactly as shown: Web, Android, iOS.

{
  "$extensions": {
    "figma.codeSyntax": {
      "Web": "var(--color-brand-primary)",
      "Android": "@color/brand_primary",
      "iOS": "Color.brandPrimary"
    }
  }
}

figma.hide — hide the variable from publishing:

{ "$extensions": { "figma.hide": true } }

figma.modify — color modifiers:

{ "$extensions": { "figma.modify": { "type": "lighten", "value": 0.2, "space": "oklch" } } }

figma.modify can be a single object or an array chain applied in order:

{
  "$extensions": {
    "figma.modify": [
      { "type": "lighten", "value": 0.12, "space": "oklch" },
      { "type": "alpha", "value": 0.6 }
    ]
  }
}

If space is omitted, SXL Studio defaults to oklch. space also accepts the alias $space.

Inheritance. Group $extensions are inherited by children and merged shallowly — a child key overrides the same parent key, and non-overlapping keys combine.

{
  "brand": {
    "$type": "color",
    "$extensions": { "figma.scopes": ["ALL_FILLS"] },
    "primary": { "$value": "#635BFF" },
    "primary-soft": {
      "$value": "{brand.primary}",
      "$extensions": { "figma.modify": { "type": "alpha", "value": 0.7 } }
    }
  }
}

#Aliases

Rules: one path inside braces, dot notation for segments, no circular references. A pure alias ("{a.b}") is treated as an alias — not as math — and its type resolves from the target token.

#Math expressions

A $value string containing an operator or function is evaluated after aliases resolve.

Math applies to numeric token types only: dimension, number, spacing, sizing, borderWidth, borderRadius, opacity, fontSize, lineHeight, letterSpacing, paragraphSpacing, paragraphIndent, duration, blur, backdrop-blur — and to numeric fields inside composites (shadow offsets/blur/spread, typography sizes, transition timings). String-kind values are never evaluated: a text token "37-37" stays the literal "37-37", not 0.

{ "$value": "{spacing.base} * 4", "$type": "spacing" }
{ "$value": "round({spacing.base} * 1.5, 2)", "$type": "spacing" }

Notes: round(x, n) rounds to n decimals; rem / em and seconds are normalized during evaluation; an unresolved alias or unknown function invalidates the expression.

#Validation

The JSON editor validates:

• JSON syntax;
• DTCG parse errors (a missing resolvable $type; unknown $type values are kept as editable opaque custom tokens);
• malformed alias braces;
• unknown token references.

For composition / template files, string references are also checked against workspace token paths, including local embedded composition token namespaces.

#Full example

{
  "color": {
    "$type": "color",
    "brand": {
      "primary": {
        "$value": "#635BFF",
        "$description": "Primary brand color",
        "$extensions": {
          "figma.codeSyntax": {
            "Web": "var(--color-brand-primary)",
            "Android": "@color/brand_primary",
            "iOS": "Color.brandPrimary"
          }
        }
      },
      "primary-soft": {
        "$value": "{color.brand.primary}",
        "$extensions": {
          "figma.modify": [
            { "type": "lighten", "value": 0.1, "space": "oklch" },
            { "type": "alpha", "value": 0.65 }
          ]
        }
      }
    }
  },
  "spacing": {
    "$type": "spacing",
    "base": { "$value": "4px" },
    "md": { "$value": "{spacing.base} * 4" }
  }
}

#Related pages

• Tokens overview
• Token types
• Scopes & Code Syntax
• Migrate from Tokens Studio