Overview
The Import feature allows you to import variable collections from JSON files into your Figma file. Variables Studio provides:
- Smart conflict detection for names, modes, and types
- Preview all changes before applying
- Flexible resolution strategies (replace or rename)
- Full preservation of modes and aliases
How to Import
Import Process
- 1
Upload JSON File
Click "Upload JSON File" and select your exported variables file. Variables Studio will analyze the file structure.
- 2
Configure Import
Review detected collections and resolve any conflicts:
- • View all collections to be imported
- • See detected conflicts (name, mode, type)
- • Choose resolution strategy for each conflict
- • Expand collections to see details
- 3
Resolve Conflicts
If conflicts are detected, choose resolution strategy for each one. Select "Replace" to update existing collections or "Rename" to create new ones.
- 4
Preview Changes
Review the preview to see exactly what will be created and updated. The summary shows the number of variables to create and update.
- 5
Review Results
See the import summary showing how many collections and variables were created or updated.
Conflict Detection
Variables Studio automatically detects three types of conflicts:
Name Conflicts
When a collection or variable with the same name already exists in your file.
Example:
Importing "Colors" collection when "Colors" already exists
Mode Conflicts
When imported modes don't match existing modes in a collection.
Example:
Existing collection has "Light, Dark" but import has "Light, Dark, High Contrast"
Type Conflicts
When a variable exists but has a different type (color vs number, etc.).
Example:
Existing "Spacing" is a number, but import defines it as a string
Resolution Strategies
For each conflict, choose how to resolve it:
Replace
Replaces the existing collection/variable with the imported one. Use when:
- • Updating existing variables
- • Syncing from source of truth
- • Overwriting old values
Result: Existing data is replaced
Rename
Creates a new collection/variable with "-copy" suffix. Use when:
- • Keeping both versions
- • Testing new values
- • Creating variants
Result: Import creates "Name-copy"
💡 Bulk Actions
Use "Replace All" or "Rename All" buttons to apply the same strategy to all conflicts at once.
Import Preview
The preview screen shows three categories of changes:
✓ Creating
New collections and variables that will be created
↻ Updating
Existing variables that will be updated with new values
⊘ Skipping
Items that won't be imported (duplicates from other collections)
Best Practices
✓ Always Preview First
Review the preview before executing the import to avoid unwanted changes.
✓ Handle Conflicts Carefully
Understand the impact of Replace vs Rename. Replace will overwrite existing data.
✓ Test with Sample Data
Download and try importing the sample JSON file first to understand the process.
✓ Backup Before Large Imports
Export your existing variables before importing large sets of changes.
Troubleshooting
Common Issues
JSON file not recognized
Ensure the JSON follows the correct format. Download a sample file to see the expected structure.
Aliases not working
Make sure the referenced variable exists in the file. Aliases are resolved after all variables are created.
Mode conflicts on every collection
This usually means the JSON has different mode names. Check that mode names match exactly (case-sensitive).