The next step in migrating your Figma files to semantic tokens, is the migration of your Design System libraries. We understand the critical need for our customers to migrate their libraries along with any custom modifications they’ve made. This may include enhancements to components like buttons, input fields, and other UI elements. By migrating your Design System libraries, you ensure that your custom work integrates smoothly with the latest semantic token updates, preserving the unique functionalities and customizations you’ve built into your Design System.
Before starting the Design System library migration, it’s crucial to complete the theme migration first. This step ensures your custom theme is fully aligned with the new design token architecture. If you haven’t done this yet, please refer to the article below:
Step 1: Theme migration
Access the latest release
Start by accessing the latest R&D release, specifically the 2024.09-LTS version. This release contains all the updated Design System libraries and journey files you’ll need. You can find the release folder here.
Duplicate the Design System libraries
The next step in migrating your Design System libraries is to duplicate the latest libraries from the 2024.09 release folder and move them to your own workspace. This release contains all the updated tokens, assets, and component libraries.
You can find the list of library files you should duplicate below:
|
List of Design System libraries |
|---|
|
(2024.09) 01. Design Tokens |
|
(2024.09) 02. Design Assets |
|
(2024.09) 03. Global Library |
|
(2024.09) 04. Web Components & Patterns |
|
(2024.09) 05. iOS Components & Patterns |
|
(2024.09) 06. Android Components & Patterns |
If you’ve already completed the Theme migration, you can skip duplicating the Design Tokens file, as you’ve already duplicated and migrated your theme in the previous step.
Publish the latest Design System libraries
After duplicating, the new files will not be automatically published in your workspace. To make them available for linking, go to each duplicated file and publish all files as libraries. This step is necessary before you can proceed with relinking.
Relinking all libraries
Once your libraries are published, the next step is to relink all associated files to these latest versions. This ensures all components, tokens, and assets are correctly connected within your design system.
Linking libraries in the 2024.09-LTS release follows the same process as with previous releases. For more detailed guidance on library linking and general file setup in Figma, please refer to the dedicated article on the topic.
Transferring custom modifications
In this step, you will manually transfer any custom changes you’ve made in your old Design System files to the new release. This includes enhancements or functionalities you’ve added to components like buttons, input fields, or other elements. Since the extent of these customizations varies greatly between different customers, this step requires a careful review of your old files. Identify all custom changes and replicate them manually in the new release files. While we can’t automate this process due to the bespoke nature of these modifications, we’re here to support you in ensuring all your custom work is successfully migrated.
Replicate all design & API changes
If your Design System library includes custom design or API modifications—such as changes to component properties, additional components that aren’t part of our out-of-the-box Design System, or any naming conventions you’ve altered—these will need to be manually replicated in the latest released libraries. Carefully review your previous files to ensure that all these custom design and API changes are accurately transferred to the new release, preserving the integrity of your custom setup.
Ensure proper semantic token usage
When transferring custom changes to the new libraries, it’s crucial to ensure proper usage of semantic design tokens. Any modifications or custom elements you bring into the new libraries should be carefully rebuilt to comply with the latest token architecture updates. This is particularly important if you’re copying and pasting work from your old files into the new release, as the copied elements may still be using old tokens. By ensuring that all custom work aligns with the new semantic tokens, you’ll fully leverage the latest theming features, including seamless light and dark mode switching.
Confirming token removal
After transferring your custom work to the new library files, it’s crucial to verify that all old token usages have been completely removed. You can easily check this through the Libraries window in your Figma file.
If there are old tokens still present in your file, you will see both the old design token library and the new design token library with the semantic token architecture listed. Select the old design token library and click the Swap library button located at the bottom right of the window. This will generate a list of all tokens from the old system that are still being used in your file.
These tokens need to be addressed and replaced with new ones. To locate the exact positions where these old tokens are used, you can employ the Style Finder plugin. By verifying the removal of old tokens, you can be confident that your migration is thorough and that your file is fully updated with the new design token architecture.
Publish your changes
Once you’ve completed migrating your Design System components to the new semantic tokens and transferred all your custom changes into the updated Design System files, the final step is to publish these changes. This ensures that your team can access and apply the latest updates consistently across all projects.
