JSON Format Specification

Overview

Variables Studio uses a clean, hierarchical JSON structure for exporting and importing Figma variables. The format is:

Human-readable and easy to edit
Organized by collections and modes
Compatible with design token standards
Preserves all Figma variable metadata

Basic Structure

The JSON is an array of collection objects. Each collection contains modes, and each mode contains variables:

[
  {
    "Collection Name": {
      "modes": {
        "Mode Name": {
          "Variable Name": {
            "$type": "color|number|string|boolean",
            "$value": "value",
            "$scopes": ["SCOPE1", "SCOPE2"]
          }
        }
      }
    }
  }
]

Visual Example:

JSON format example with actual variable data

Collection Object

Structure

{
  "CollectionName": {
    "modes": { ... }
  }
}

Field	Type	Description
CollectionName	string	Name of the variable collection (key)
modes	object	Object containing all modes for this collection

Mode Object

Structure

"modes": {
  "Light": { ... },
  "Dark": { ... }
}

Each mode is a key-value pair where the key is the mode name and the value is an object containing all variables for that mode.

💡 Note

Mode names must match exactly (case-sensitive) when importing into existing collections.

Variable Object

Structure

"Variable/Path/Name": {
  "$type": "color",
  "$value": "#FF0000",
  "$scopes": ["ALL_SCOPES"]
}

Field	Type	Description
$type	string	Variable type: "color", "number", "string", or "boolean"
$value	any	Variable value (format depends on type)
$scopes	array	Array of scope strings where variable can be used

Variable Types & Values

Color

"Primary": {
  "$type": "color",
  "$value": "#0066FF",
  "$scopes": ["ALL_SCOPES"]
}

Value format: Hex color string (e.g., "#0066FF", "#FF0000")

Number

"Spacing/Base": {
  "$type": "number",
  "$value": 16,
  "$scopes": ["GAP", "WIDTH_HEIGHT"]
}

Value format: Numeric value (integer or float)

String

"Font/Family": {
  "$type": "string",
  "$value": "Inter",
  "$scopes": ["FONT_FAMILY"]
}

Value format: Text string

Boolean

"Feature/Enabled": {
  "$type": "boolean",
  "$value": true,
  "$scopes": ["ALL_SCOPES"]
}

Value format: Boolean (true or false)

Variable Scopes

The $scopes field defines where a variable can be used in Figma:

All Scopes

["ALL_SCOPES"]

Can be used anywhere

Fill Scopes

["FRAME_FILL", "SHAPE_FILL"]

For fills only

Stroke Scopes

["STROKE_COLOR"]

For strokes only

Text Scopes

["TEXT_FILL"]

For text color only

Spacing Scopes

["GAP", "WIDTH_HEIGHT"]

For spacing and sizing

Font Scopes

["FONT_FAMILY", "FONT_SIZE"]

For typography

Variable Aliases

Aliases allow variables to reference other variables. They're represented as strings with the referenced variable's path:

"Primary/500": {
  "$type": "color",
  "$value": "#0066FF",
  "$scopes": ["ALL_SCOPES"]
},
"Button/Background": {
  "$type": "color",
  "$value": "Primary/500",  // Alias reference
  "$scopes": ["ALL_SCOPES"]
}

Important

Aliases are resolved after all variables are created. Make sure the referenced variable exists in the import.

Complete Example

Here's a complete example with multiple collections, modes, types, and aliases:

[
  {
    "Colors": {
      "modes": {
        "Light": {
          "Primary/500": {
            "$type": "color",
            "$value": "#0066FF",
            "$scopes": ["ALL_SCOPES"]
          },
          "Background/Base": {
            "$type": "color",
            "$value": "#FFFFFF",
            "$scopes": ["FRAME_FILL", "SHAPE_FILL"]
          },
          "Text/Primary": {
            "$type": "color",
            "$value": "Primary/500",
            "$scopes": ["TEXT_FILL"]
          }
        },
        "Dark": {
          "Primary/500": {
            "$type": "color",
            "$value": "#66B3FF",
            "$scopes": ["ALL_SCOPES"]
          },
          "Background/Base": {
            "$type": "color",
            "$value": "#1A1A1A",
            "$scopes": ["FRAME_FILL", "SHAPE_FILL"]
          },
          "Text/Primary": {
            "$type": "color",
            "$value": "Primary/500",
            "$scopes": ["TEXT_FILL"]
          }
        }
      }
    }
  },
  {
    "Spacing": {
      "modes": {
        "Default": {
          "Base": {
            "$type": "number",
            "$value": 8,
            "$scopes": ["GAP", "WIDTH_HEIGHT"]
          },
          "Large": {
            "$type": "number",
            "$value": 16,
            "$scopes": ["GAP", "WIDTH_HEIGHT"]
          }
        }
      }
    }
  }
]

Validation Rules

✗ Invalid: Missing Required Fields

"Variable": {
  "$value": "#FF0000"
  // Missing $type and $scopes
}

All three fields ($type, $value, $scopes) are required

✗ Invalid: Wrong Value Type

"Spacing": {
  "$type": "number",
  "$value": "16px",  // Should be: 16
  "$scopes": ["GAP"]
}

Number values must be numeric, not strings

✓ Valid: Proper Structure

"Primary": {
  "$type": "color",
  "$value": "#0066FF",
  "$scopes": ["ALL_SCOPES"]
}

All required fields present with correct types

Tools & Integration

Working with the JSON

Version Control

Commit JSON files to Git to track design token changes over time.

git add variables-export.json

Custom Scripts

Parse the JSON with any language to generate CSS variables, design tokens, or documentation.

Design Token Tools

Convert to other formats like Style Dictionary, Tokens Studio, or custom token formats.

Overview

Basic Structure

Collection Object

Structure

Mode Object

Structure

Variable Object

Structure

Variable Types & Values

Color

Number

String

Boolean

Variable Scopes

All Scopes

Fill Scopes

Stroke Scopes

Text Scopes

Spacing Scopes

Font Scopes

Variable Aliases

Complete Example

Validation Rules

✗ Invalid: Missing Required Fields

✗ Invalid: Wrong Value Type

✓ Valid: Proper Structure

Tools & Integration

Working with the JSON

Version Control

Custom Scripts

Design Token Tools

Related Documentation

Export Guide →

Import Guide →