How to move variables between collections in Figma?
My solution to Figma’s missing feature — Learn how to divide a single variables collection into a separate collections in Figma.
As the creator behind the Ant Design System for Figma, I encounter numerous challenges whenever Figma undergoes a significant update or when Ant Design for React brings new changes. My goal is to ensure that users of my UI kit receive the latest Figma features while maintaining alignment with the Ant Design library’s concise principles.
As Figma had not yet provided support for transferring variables used within components between collections, I faced a notable challenge recently while attempting to restructure my UI kit’s variable collections. I had to reorganize my variable collections, which meant moving variables from one Default collection into four distinct ones: Colors, Dimensions, Typography, and Components.
The background
Before Figma introduced the variables feature, the Ant Design System for Figma was built with Figma Tokens with the Tokens Studio plugin. To fully support the variables’ functionality, I’ve decided to modify the UI kit so our users can use the native variables’ feature. I used the Tokens Studio plugin to convert the tokens into variables. After the conversion, the way the tokens were structured in the UI kit resulted in one collection containing variable groups. Before the newest update (5.13), the Ant Design System for Figma contained one collection (”Default”) that had multiple groups inside: Color, Size, Space, Typography, Border Radius, and Components.
To enhance the organization and user-friendliness of variables within the Ant Design System for Figma, I decided to restructure our collections. Here’s the breakdown of the changes:
- Colors — This collection now houses all color variables present in the library.
- Dimensions — This collection encompasses Size, Space, Screen Size, and Border Radius variables.
- Typography — Although Figma doesn’t currently support typography variables (as of when I wrote this article on January 14, 2024), I store them here. This allows us to utilize our Theme Buddy plugin to generate JSON, enabling developers to access theme settings from the Ant Design System for Figma and use them in their code.
- Components — Within this collection, you’ll find variables associated with components that reference variables from the previously mentioned collections.
This structured approach allows us to separate Colors from Dimensions, enabling different modes for each collection. For instance, the Colors collection can now have Light and Dark modes, while the Dimensions collection can have Default and Compact modes. These changes align our UI kit more closely with the principles of Ant Design for React, making it concise and facilitating easier maintenance for the teams that rely on it.
The problem
I knew that the Figma variables feature was still in beta, and it was missing a lot of functionalities, including the one to move variables between collections. In order to achieve such a change, I had to find a solution to modify the structure of my variable collections. I googled ‘move variables between collections in Figma’ and learned that there were many people who had the same problem. Unfortunately, there was no solution for my exact need. I also asked on X (Twitter) but had no luck.
The solution
To finally find a solution, I dug deeper into the issue and took matters into my own hands. Below, I’ll share the steps I took to successfully divide a single collection into four separate collections while ensuring that components retained their connections to the variables they used. As an example, I will use the Ant Design System for Figma, but the approach will also work for any other Figma file with one collection.
Step 1. Duplicate the initial collection
- Make sure to make a copy of the file you will be working on or save the state from before the changes (Command + Option + S)!
- Install the Variable Utilities plugin.
- Search for the plugin in the file assets panel.
- Click on the plugin and select Duplicate Variable Collection.
- Select the initial collection.
- Enter the name of the new collection, for example, “1. Colors”.
- Click on the Duplicate Variable Collection button.
- Repeat the process for the amount of collections you want to create — make sure to always duplicate the initial collection.
Step 2. Clean up irrelevant variable groups in the new collections
In the second step, it’s essential to remove any groups inside the collections that are unrelated to the new collections. For instance, if you’ve created a new collection called “Colors,” delete any groups or variables that do not pertain to colors. This process should be repeated for each of the remaining collections. Remember not to rename or ungroup your variables during this phase; the focus is solely on deleting variables or groups that are irrelevant to the specific collection.
Step 3. Export collection with broken variable connections
In my case, the “4. Components” collection contains all variables related to the components. These variables also reference variables from the higher collections — “1. Colors”, “2. Dimensions” and “3. Typography”. For example, Button’s “defaultBg” variable references “colorBgContainer” from the “1. Colors” collection.
Unfortunately, after duplicating the collections, all connections between variables are lost. To fix that, we need to do some Jedi tricks. The “Variables Pro” plugin and ChatGPT will help us with that.
- Install the Variables Pro plugin.
- Open the plugin.
- Go to the Export tab.
- Select the collection where variable connections are broken — in my case, I selected the “4. Components” collection.
- Click on the Export button.
Step 4. Modify JSON to restore broken connections
After I exported the “4. Components” JSON, I’ve noticed why the variable connections were broken. Each variable referenced the “4. Components” collection instead of the collection specific to the value. See the example below.
"Form": {
"Global": {
"screenXSMax": {
"$scopes": [
"ALL_SCOPES"
],
"$type": "float",
"$libraryName": "",
"$collectionName": "4. Components",
"$value": "{Size.Screen Size.screenXSMax}"
},
}The “$collectionName” references the “4. Components” collection while it should reference the “2. Dimensions” collections because “$value”: “{Size.Screen Size.screenXSMax}” is a Size value. To fix that, we need to replace all “$collectionName” values with proper collection names related to the “$value” below.
In my case, there are over 1500 variables in the “4. Components” collection. Doing it manually would be a death sentence! However, in today’s world, we have access to modern tools like ChatGPT that can simplify the process. By providing a straightforward prompt with a set of rules, AI can generate a script to automate the transformation of our code.
This was my prompt:
I want you to transform the JSON file with these rules:
- if "$value" has the "Colors." word, set "$collectionName" to "1. Colors"
- if "$value" has the "Size.", "Space." or "Border Radius." words, set "$collectionName" to "2. Dimensions"
- if "$value" has the "Typography." word, set "$collectionName" to "3. Typography"
The code should take the first word in the {}. For example, in "$value": "{Typography.Font Size.fontSizeHeading3}" the collection name should be "3. Typography"
Create a javascript code that will allow me to transform the code of the export.json file that lives in the same folder with the script.js you will write
Make sure to generate the new file after the script runs and name it "transformed.json"
Here's the sample of the JSON file:
{40 lines of my JSON as an example}After a few adjustments, GPT generated such code:
const fs = require('fs');
// Read the original JSON file
fs.readFile('export.json', 'utf8', (err, data) => {
if (err) {
console.error('Error reading JSON file:', err);
return;
}
try {
const jsonData = JSON.parse(data);
// Define a function to extract the first word within curly braces
function extractFirstWord(value) {
const matches = value.match(/\{([^}]+)\}/);
if (matches && matches[1]) {
const words = matches[1].split('.');
if (words.length > 0) {
return words[0];
}
}
return '';
}
// Define a function to update $collectionName based on the extracted word
function updateCollectionName(obj) {
for (const key in obj) {
if (key === '$value') {
if (typeof obj[key] === 'string') {
const firstWord = extractFirstWord(obj[key]);
if (firstWord === "Colors") {
obj.$collectionName = "1. Colors";
} else if (firstWord === "Size" || firstWord === "Space" || firstWord === "Border Radius") {
obj.$collectionName = "2. Dimensions";
} else if (firstWord === "Typography") {
obj.$collectionName = "3. Typography";
}
}
} else if (typeof obj[key] === 'object') {
updateCollectionName(obj[key]);
}
}
}
// Iterate through the JSON data and update $collectionName using the function
jsonData.forEach(item => {
updateCollectionName(item);
});
// Write the transformed JSON data to a new file
const transformedData = JSON.stringify(jsonData, null, 2);
fs.writeFile('transformed.json', transformedData, 'utf8', (err) => {
if (err) {
console.error('Error writing transformed JSON file:', err);
return;
}
console.log('JSON transformation completed. Check "transformed.json".');
});
} catch (err) {
console.error('Error parsing JSON:', err);
}
});Here’s what comes next:
- Save the code ChatGPT generated into a script.js file.
- Create a new folder.
- Move the script.js file to the new folder.
- Move the export.js file you exported from the Variables Pro plugin into the same folder.
- Open your code editor — I used VS Code.
- Open the terminal in the code editor.
- Navigate to the folder with the ‘cd’ command.
- Type ‘node script.js’ in the terminal.
- If your script.js code contains no problems, the new transformed.json file will be created in the same folder. If there are problems, copy the contents from the code editor console and ask ChatGPT to resolve them. This is how I perfected my script.
Step 5. Import the new JSON
Check some variables in the newly created JSON file. If the “$collectionName” references proper collections, it’s time to import them to Figma with the Variables Pro plugin. If not, try to resolve the issues with ChatGPT.
- Open the Variables Pro plugin in Figma.
- Go to the Import tab.
- Upload the new “transformed.json” file. It will take some time to import the file, depending on your file size.
Once the file is imported, a new collection will be added to your variable collections. Open the newly added collection and check if your variables have proper connections. In my case, the new “4. Components” collection was created, and I had to check if the variables reference other variables from “1. Colors”, “2. Dimensions,” and “3. Typography” collections. If the new collection was appropriately added and you can see that the variables are referenced correctly, you can delete the old exported collection. In my case, I had to delete the old “4. Components” collection.
Step 6. Swap variables
In this step, we need to swap variables in our components. The components still use the variables from the initial collection, in my case, “Default”. For example, the Button component is using the “defaultBg” variable from the “Default” collection, and it should use the “defaultBg” variable from the “4. Components” collection.
Don’t worry. We don’t have to reapply all variables in all components manually! In that case, we will use the Variables Pro plugin Swap feature. If your file is large and you have a lot of components (like mine), I encourage you to go page by page. If you have a small system with few components, you can try to use the plugin on all pages simultaneously. However, I noticed that swapping the variables on all pages at once if your file is large can fail, and the plugin will crash.
- In your Figma file, go to the component page, for example, Button.
- Open the Variables Pro plugin.
- In the Swap tab, select the Current Page radio button.
- In the Source column, select your initial collection. In my case, “Current File” → “Default”.
- In the Target column, select the first one of the newly created collections. In my case, “Current File” → “1. Colors”.
- After a while, the plugin will find the variables to swap and list them below. Click on the Swap button to apply the changes.
- Repeat the process for all remaining new collections. Select your initial collection in the Source column and then select the following new collection in the Target column.
- Repeat the process for all pages in your document.
Things to watch out for
Once you swap all variables, there are a few things to watch out for.
- The Variables Pro plugin does not swap the stroke width variables. You need to reapply them manually or wait for a plugin update. I already contacted the plugin creator and asked for an update.
- If you use variables in the Effect styles, such as box shadows, you need to swap the variables in each effect manually.
Voila! That’s it. I hope you find this guide helpful!
