SXL Studio
Tokens

Token JSON format

How to write token JSON files: DTCG syntax, $value, $type, $description, $extensions fields, groups, aliases, and inheritance.

What is JSON

JSON (JavaScript Object Notation) is a text-based format for storing structured data. Tokens in SXL Studio are stored in JSON.

If you've never worked with JSON, this section will teach you to write token files from scratch.

Basic syntax

JSON consists of key-value pairs enclosed in curly braces:

JSON
{
  "key": "value"
}

Rules:

  • Keys are always in double quotes: "color", "fontSize"
  • String values are in double quotes: "#FF0000", "Inter"
  • Numbers have no quotes: 16, 1.5, 0.8
  • Booleans have no quotes: true, false
  • Objects use curly braces: { }
  • Arrays use square brackets: [ ]
  • Items are separated by commas
  • The last item in an object or array has no trailing comma

Nesting

Objects can contain other objects:

JSON
{
  "brand": {
    "colors": {
      "primary": "#6366F1",
      "secondary": "#EC4899"
    }
  }
}

Arrays

An array is an ordered list of values:

JSON
{
  "sizes": [4, 8, 16, 24, 32]
}

Tip: use any text editor for JSON. SXL Studio has a built-in editor with syntax highlighting and validation.

DTCG format

SXL Studio uses the Design Tokens Community Group (DTCG) format — an open standard for describing design tokens. A file is regular JSON with special $-prefixed fields.

Token structure

JSON
{
  "token-name": {
    "$value": "#6366F1",
    "$type": "color",
    "$description": "Primary brand color"
  }
}

Required fields

FieldDescription
$valueToken value. Format depends on type
FieldDescription
$typeToken type: color, dimension, typography, etc.
$descriptionText description of the token's purpose

Additional fields

FieldDescription
$extensionsExtensions: scopes, code syntax, color modifiers

$value — value

The $value format depends on $type:

String (simple types):

JSON
{ "$value": "#6366F1", "$type": "color" }
{ "$value": "16px", "$type": "dimension" }
{ "$value": "Inter", "$type": "fontFamily" }

Number:

JSON
{ "$value": 0.8, "$type": "opacity" }
{ "$value": 700, "$type": "fontWeight" }

Boolean:

JSON
{ "$value": true, "$type": "boolean" }

Object (composite types):

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

Array (multiple effects):

JSON
{
  "$value": [
    { "color": "#00000026", "offsetX": "0px", "offsetY": "4px", "blur": "8px", "spread": "0px" },
    { "color": "#0000000D", "offsetX": "0px", "offsetY": "1px", "blur": "2px", "spread": "0px" }
  ],
  "$type": "shadow"
}

$type — type

The type determines how the plugin interprets $value:

JSON
{
  "primary": {
    "$value": "#6366F1",
    "$type": "color"
  }
}

Full list: color, gradient, img, fill, opacity, dimension, number, spacing, sizing, border, borderWidth, borderRadius, strokeStyle, shadow, backdrop-blur, blur, glass, effects, typography, fontFamily, fontWeight, fontStyle, fontSize, lineHeight, letterSpacing, paragraphIndent, paragraphSpacing, textCase, textDecoration, transition, duration, cubicBezier, grid, boolean, text, template, composition.

Detailed map: Token types.

$description — description

Text description for documenting purpose:

JSON
{
  "error": {
    "$value": "#EF4444",
    "$type": "color",
    "$description": "Color for errors, destructive actions, and alert banners"
  }
}

The description appears in the plugin UI on hover and exports to Figma variables.

$extensions — extensions

Extensions add extra metadata to a token.

figma.scopes

Figma variable visibility scopes:

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

figma.codeSyntax

Code syntax for Dev Mode:

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

figma.hide

Hide the variable from library publishing:

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

figma.modify

Color modifiers (only for color):

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

Modifier types: lighten, darken, alpha, mix.

Chained modifiers as an array:

JSON
{
  "$extensions": {
    "figma.modify": [
      { "type": "lighten", "value": 0.1, "space": "oklch" },
      { "type": "alpha", "value": 0.5 }
    ]
  }
}

Groups (nesting)

Tokens are organized into groups via nested objects:

JSON
{
  "colors": {
    "brand": {
      "primary": {
        "$value": "#6366F1",
        "$type": "color"
      },
      "secondary": {
        "$value": "#EC4899",
        "$type": "color"
      }
    },
    "neutral": {
      "100": {
        "$value": "#F5F5F5",
        "$type": "color"
      }
    }
  }
}

Token path is formed from keys: colors.brand.primary, colors.neutral.100.

$type inheritance

A type set at the group level is inherited by all nested tokens:

JSON
{
  "spacing": {
    "$type": "spacing",
    "xs": { "$value": "4px" },
    "sm": { "$value": "8px" },
    "md": { "$value": "16px" },
    "lg": { "$value": "24px" }
  }
}

This is equivalent to:

JSON
{
  "spacing": {
    "xs": { "$value": "4px", "$type": "spacing" },
    "sm": { "$value": "8px", "$type": "spacing" },
    "md": { "$value": "16px", "$type": "spacing" },
    "lg": { "$value": "24px", "$type": "spacing" }
  }
}

Inheritance works at any depth. A token can override its parent's type.

$extensions inheritance

Extensions are also inherited from groups and merged:

JSON
{
  "brand": {
    "$type": "color",
    "$extensions": {
      "figma.scopes": ["ALL_FILLS"]
    },
    "primary": {
      "$value": "#6366F1"
    },
    "primary-light": {
      "$value": "{brand.primary}",
      "$extensions": {
        "figma.modify": { "type": "lighten", "value": 0.2, "space": "oklch" }
      }
    }
  }
}

brand.primary inherits figma.scopes: ["ALL_FILLS"] from the group.

brand.primary-light gets both figma.scopes from the group and its own figma.modify.

Aliases (references)

An alias references another token via {path.to.token} syntax:

JSON
{
  "primitive": {
    "$type": "color",
    "blue-500": { "$value": "#3B82F6" }
  },
  "semantic": {
    "$type": "color",
    "link": { "$value": "{primitive.blue-500}" },
    "info": { "$value": "{primitive.blue-500}" }
  }
}

Changing primitive.blue-500 automatically updates semantic.link and semantic.info.

Important: an alias must reference an existing token in the files loaded in the plugin. Circular references are not allowed.

Auto type detection

When $type is not specified and not inherited, the plugin infers the type from the value:

ValueInferred type
true, falseboolean
Number without unitsnumber
#RGB, #RRGGBB, rgb(...), rgba(...)color
16px, 1.5rem, 2emdimension
Array of 4 numbers [0.4, 0, 0.2, 1]cubicBezier
Object with r, g, bcolor

Tip: always specify $type explicitly for reliability and file readability.

Full file example

JSON
{
  "color": {
    "$type": "color",
    "neutral": {
      "50": { "$value": "#FAFAFA" },
      "100": { "$value": "#F5F5F5" },
      "900": { "$value": "#171717" }
    },
    "brand": {
      "primary": {
        "$value": "#6366F1",
        "$description": "Primary brand color",
        "$extensions": {
          "figma.codeSyntax": {
            "Web": "var(--color-brand-primary)",
            "iOS": "Color.brandPrimary",
            "Android": "@color/brand_primary"
          }
        }
      }
    }
  },
  "spacing": {
    "$type": "spacing",
    "xs": { "$value": "4px" },
    "sm": { "$value": "8px" },
    "md": { "$value": "16px" },
    "lg": { "$value": "24px" },
    "xl": { "$value": "32px" }
  },
  "typography": {
    "heading": {
      "lg": {
        "$value": {
          "fontFamily": "Inter",
          "fontSize": "32px",
          "fontWeight": 700,
          "lineHeight": "40px",
          "letterSpacing": "-0.02em"
        },
        "$type": "typography"
      }
    }
  },
  "shadow": {
    "sm": {
      "$value": {
        "color": "#0000001A",
        "offsetX": "0px",
        "offsetY": "1px",
        "blur": "3px",
        "spread": "0px"
      },
      "$type": "shadow"
    }
  }
}

Copy this file, load it into SXL Studio, and export to Figma Variables — you'll see a complete token system in action.