Figma Export JSON

A Figma Variables export in JSON format generated by a plugin. This file represents raw plugin output and requires normalization before use with Variable Design Standard (VDS) tooling.

• Raw file: figma-export.json

Note: This is a plugin-generated format, not the native Figma REST API format. The REST API uses a different structure with valuesByMode and variable IDs. See REST API format for details.

Figma Variables overview

Figma Variables store reusable values that can be referenced across designs. Key concepts:

• Variable types: color, number, string, boolean
• Collections: Group related variables (e.g., “Primitives”, “Tokens”)
• Modes: Contextual variants within a collection (e.g., light/dark, mobile/desktop)
• Aliasing: Variables can reference other variables

For complete Figma documentation, see:

• Overview of variables, collections, and modes
• Modes for variables
• Variables in Dev Mode

Export structure

Collections

Collections are prefixed with @ in the export and contain $collection_metadata:

{
  "@primitives": {
    "$collection_metadata": {
      "name": "Primitives",
      "figmaId": "VariableCollectionId:502:189",
      "modes": [{ "key": "mode_1", "name": "Mode 1" }]
    }
  }
}
                    

Note: The @ prefix is added by the export plugin. In Figma UI, you name the collection “Primitives” (without @). The export adds the prefix to distinguish collections from groups.

The figmaId is Figma’s internal identifier, used for round-trip sync with the design file.

Variables

Variables include $type, $value, and $variable_metadata:

{
  "$color": {
    "$green": {
      "200": {
        "$type": "color",
        "$value": "#37ff57",
        "$description": "",
        "$variable_metadata": {
          "name": "color/green/200",
          "figmaId": "VariableID:502:227",
          "modes": {
            "mode_1": "rgba(55,255,87,1.00)"
          }
        }
      }
    }
  }
}
                    

Note: The $ prefix on group names (e.g., $color, $green) is added by the export plugin. In Figma UI, you use / as path separators (e.g., color/green/200). The export converts path segments to nested JSON with $ prefixes to avoid conflicts with DTCG reserved properties.

The $variable_metadata.name contains the original Figma path with / separators.

Modes

Mode values live inside $variable_metadata.modes, not in $value:

{
  "primary": {
    "$type": "color",
    "$value": "{@primitives.$color.$neutral.0}",
    "$variable_metadata": {
      "name": "surface/primary",
      "figmaId": "VariableID:510:6354",
      "modes": {
        "light": "{@primitives.$color.$neutral.0}",
        "dark": "{@primitives.$color.$neutral.1000}"
      }
    }
  }
}
                    

The top-level $value contains one mode’s value (typically the first). All mode values are in modes.

References

Figma uses {@collection.$group.variable} syntax for references:

{
  "minimal": {
    "$type": "color",
    "$value": "{@primitives.$color.$neutral.200}",
    "$variable_metadata": {
      "modes": {
        "light": "{@primitives.$color.$neutral.200}",
        "dark": "{@primitives.$color.$neutral.800}"
      }
    }
  }
}
                    

Note the @ prefix on collection names and $ prefix on group names.

Figma vs Variable Design Standard (VDS) format

Obtaining exports

Figma Variables can be exported via:

• REST API: Local Variables endpoint (Enterprise plan only: requires Full seat in an Enterprise org)
• Plugin API: figma.variables (all plans, requires plugin development)
• Third-party plugins: Tokens Studio, Design Tokens export plugins

The example file was generated using a plugin export.

REST API format

The REST API uses a different structure than plugin exports. Key differences:

• Uses valuesByMode object with mode IDs as keys
• Variables referenced by internal IDs (VariableID:xxx:xxx)
• Collections referenced by internal IDs (VariableCollectionId:xxx:xxx)

{
  "variables": {
    "VariableID:502:227": {
      "id": "VariableID:502:227",
      "name": "color/green/200",
      "resolvedType": "COLOR",
      "valuesByMode": {
        "502:0": {
          "r": 0.216,
          "g": 1,
          "b": 0.341,
          "a": 1
        }
      }
    }
  }
}
                

The Figma adapter handles both formats. See Figma Adapter for details.

Failure modes

Using raw Figma exports without normalization causes:

• Invalid references: {@primitives.$color.x} is not valid DTCG syntax. Build tools fail or produce broken output.
• Missing mode values: Mode data in $variable_metadata.modes is ignored by DTCG-compliant tools that expect modes in $value.
• Metadata loss: $collection_metadata and $variable_metadata are not preserved in standard DTCG $extensions.
• Path mismatches: Figma’s / separators and $ prefixes create inconsistent naming with other sources.

Out of scope

This example shows raw Figma output, not:

• Normalized format: See DTCG Compliant Example for canonical structure.
• Normalization steps: See Figma Adapter for conversion rules.
• Tokens Studio format: Different export structure with its own adapter.
• Plugin development: See Figma Plugin API for building export tools.

Normalization

The Figma Adapter transforms this format into Variable Design Standard (VDS) canonical structure:

1. Remove @ and $ prefixes from paths
2. Move $variable_metadata.modes into $value objects
3. Convert reference syntax to DTCG format
4. Relocate metadata to $extensions

See Adapter Pipeline for export-to-contract conversion examples.