Token JSON format

#Scope of this page

This page describes the JSON format for token files used in the Tokens tab.

It focuses on DTCG-style token trees ($value, $type, $extensions, etc.).

For composition-specific files ($type: "composition") see: Composition.

#File root: required shape

A token file root must be a JSON object:

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

Invalid root shapes (array, string, number) are rejected by validation.

#Token node vs group node

SXL Studio follows DTCG parsing rules:

• a node with $value is a token node;
• a node without $value is a group node (container).

Group nodes can define inherited $type and $extensions for child tokens.

#Core fields

#$value: supported forms

The parser accepts all of the following forms:

#1. String

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

#2. Number / Boolean

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

#3. Pure alias

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

Use dot notation inside {...} for canonical alias behavior.

#4. Math expression (string)

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

#5. 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": "effects"
}

#$type: canonical type set

SXL Studio supports 37 canonical token types.

#Simple types (23)

color, dimension, sizing, spacing, borderRadius, borderWidth, opacity, number, fontFamily, fontWeight, fontStyle, fontSize, lineHeight, letterSpacing, paragraphSpacing, paragraphIndent, text, boolean, duration, cubicBezier, strokeStyle, textCase, textDecoration

#Composite types (14)

typography, shadow, blur, backdrop-blur, effects, glass, gradient, fill, img, grid, border, transition, template, composition

Full type behavior by category: Token types.

#$type alias normalization

Legacy $type values are normalized automatically:

#$type inheritance and resolution order

Type resolution order is:

1. token-level $type
2. nearest parent group $type
3. root-level $type
4. auto-inference from $value (fallback)

If no type can be resolved, validation reports an error.

#Auto type inference (fallback)

When no $type is provided/inherited, parser inference is:

For reliability, set $type explicitly.

#$extensions

#figma.scopes

Variable scope hints for Figma variable export:

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

#figma.codeSyntax

Dev Mode code syntax snippets:

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

Use keys exactly as shown: Web, Android, iOS.

#figma.hide

Hide variable from publishing:

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

#figma.modify (color modifiers)

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

Supported modifier types: lighten, darken, alpha, mix.

Supported color spaces: srgb, hsl, lch, oklch, p3.

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

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

If space is omitted, SXL Studio defaults to oklch.

For mix, set color in the modifier object.

#$extensions inheritance

Group $extensions are inherited by children and merged shallowly:

• child keys override same parent keys;
• non-overlapping keys are combined.

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

#Alias rules

#Canonical pure alias syntax

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

Rules:

• use one path inside braces;
• use dot notation for path segments;
• avoid circular references.

#Embedded alias syntax

Aliases can be embedded in strings (for math or composite fields):

{ "$value": "{spacing.base} * 3", "$type": "spacing" }

#Math expression support

Supported:

• operators: +, -, *, /, %
• parentheses
• constants: pi, e
• functions: round, floor, ceil, trunc, min, max, clamp, abs, sign, mod, pow, sqrt, hypot, exp, log, log2, log10, sin, cos, tan, asin, acos, atan, atan2

Important notes:

• pure alias ("{a.b}") is treated as alias, not math;
• unresolved alias/function errors invalidate expression evaluation;
• rem/em and seconds are normalized during evaluation.

#Validation behavior in editor

The JSON editor validates:

• JSON syntax;
• DTCG parse errors (unknown/missing $type);
• 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

• Overview: Tokens overview
• Type map: Token types
• Scopes and code syntax: Scopes & Code Syntax