As part of our recent design token upgrade, we recognize that many of our customers have bespoke themes that need to be preserved. This guide will walk you through the process of migrating your existing theme in Figma to align with our new architecture. The theme migration process is straightforward and involves exporting the values from your old design token file and importing them to your new file using our Semantic Token Migrator plugin for Figma.
Export values
First, you’ll need to export the design token values from your existing theme file. This will involve using the Semantic Token Migrator plugin in Figma, which will extract all of your current color, text and effect styles so that you can easily copy & paste them into your new semantic-driven Design Tokens file in later steps.
Open your existing Design Tokens file
Navigate to your existing Design Tokens file from which you want to export your theme.
Run the Semantic Token Migrator plugin
Once your file is open, press Cmd + P and search for “Semantic Token Migrator” or locate it in your installed plugins list. When you click on the plugin name, you’ll see two options: Export values and Import values. Choose the Export values option to launch the plugin.
Copy exported data to your clipboard
A new window should appear on top of your Figma canvas with the plugin’s UI. The plugin will display all design token categories (e.g., color styles, text styles, effect styles) in an accordion-style list. You can drill in and review the categories to ensure all necessary values are included.
At the bottom of the plugin window, click the Copy data to clipboard button. This will copy the exported design token values in JSON format to your clipboard.
Import values
Now, you’ll need to import the copied design token values into your new theme file. This will involve again using the Semantic Token Migrator plugin in Figma. The plugin will use the values from your previous setup to build a smart default new theme that matches your old theme as closely as possible.
Duplicate the new Design Tokens file
First, navigate to the release folder where the 2024.09-LTS release is stored and locate the new design tokens file included in the release. Right-click on the file’s thumbnail and select Duplicate to create a copy in your own Figma workspace. Once duplicated, you can open the new file.
Run the Semantic Token Migrator plugin again
Once your file is open, press Cmd + P and search for the Semantic Token Migrator plugin. To proceed, this time select the Import values option to launch the plugin.
Import data from your clipboard
A new window will now appear on top of your Figma canvas, displaying a text area where you can paste the JSON data you copied earlier. After pasting the JSON data into the text area, click the Import values button to import the design tokens data into your new file.
Preview and test your theme
Once the process is complete, you should see your theme propagate seamlessly throughout the entire design tokens file. You can also preview the test screens on the Visualizer page to ensure your theme has migrated correctly.
If further adjustments are needed, you can easily manage your design tokens directly in the Local Variables window within your design tokens file.
Publish your changes
Once you’ve completed migrating your theme to align with the new semantic token architecture, the final step is to publish these changes. This ensures that other files in your workspace can access and apply the theme consistently across all projects.
