With our new design token architecture upgrade, we recognize the importance of ensuring a smooth migration for all aspects of the Backbase product, including the journeys our customers rely on. Whether you’re working with out-of-the-box (OOTB) journeys that you’ve adopted as they are, or custom journeys that your team has developed and maintains internally, your migration path will vary. This guide is designed to support you every step of the way, ensuring a seamless transition to the latest design token architecture for both OOTB and custom journeys.
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
Step 2: Library migration
Migrating OOTB journeys
Migrating your out-of-the-box (OOTB) journeys to the new design token architecture is a straightforward process, especially if you’re familiar with adopting previous journey releases. As of the 2024.09-LTS release, all OOTB journeys from Backbase use the new design token architecture by default.
Your main task is to bring the journey files from the latest release into your Figma workspace and properly link them with your already migrated Design System libraries and UI kits.
Access the latest release
Start by accessing the latest R&D release, specifically the 2024.09-LTS version. This release contains all the updated journey files you’ll need and is the same folder used for the theme migration and Design System migration steps. You can find the release folder at this link.
Duplicate the journey files
Next, locate the journey files that you want to update and duplicate them. You can then move the duplicated files to your workspace.
Link all libraries to your journey files
After duplicating the necessary journey files, the next step is to link them with the associated Design System libraries and UI kits to ensure everything is properly connected. Your primary task is to make sure the new journey files are correctly linked with the previously migrated design tokens, components, and other relevant libraries.
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.
Review your journey files
Once you’ve properly linked your libraries with your new journey files, you should see your out-of-the-box journeys fully migrated, with the correct theme colors, fonts, and other design elements seamlessly propagating throughout your screens in Figma. If everything appears intact in your Figma files, you’ve successfully migrated to the new design token architecture. However, if you notice any discrepancies that need further attention, you can either report them to the Design System team for review or make the necessary adjustments manually if they’re minor changes.
Migrating custom journeys
At Backbase, we understand that many of our customers have invested significant time and effort in creating and maintaining custom journeys that are uniquely tailored to their needs. These custom journeys, unlike out-of-the-box (OOTB) solutions, reflect the specific branding, functionality, and user experience goals of your organization. As we upgrade to a new design token architecture, we’re committed to ensuring that your custom work transitions seamlessly, preserving the integrity of your designs while taking full advantage of the latest enhancements.
This guide will walk you through the process of migrating your custom journeys to the new design token architecture, helping you maintain consistency and quality across your user experience.
Open your custom journey file
The first step in migrating your custom journeys is to open the specific journey file you’ve created and maintained in Figma.
Link all libraries to your custom journey file
Once your custom journey file is open, the next crucial step is to update all associated libraries to their latest versions. This ensured that your custom journey file is properly connected to your previously migrated design tokens, components, and other relevant libraries, ensuring that the latest Design System updates are accurately reflected in your custom work. Since the new semantic token update primarily focuses on enhancing our color architecture, this step will also ensure that all your existing text styles, effects, and grids are automatically updated as well.
You can follow the same library linking process used in previous releases. For more detailed guidance on library linking and general file setup in Figma, please refer to the dedicated article on the topic.
Manually replace old color usages with new color tokens
Identifying old tokens and their usages in Figma is relatively straightforward. When you select any screen or element on your canvas, you’ll notice a Selection colors section in the right-side panel. This section lists all the colors applied to your selection. A simple and reliable rule of thumb for distinguishing between old and new tokens is to look at the naming convention. Old tokens typically have longer names and include a prefix like “light-mode” or “dark-mode” in lowercase, whereas new tokens do not follow this prefix convention. If you spot a token with “light-mode” or “dark-mode” at the beginning of its name, it’s an old token that needs to be replaced with a new one.
Locating old tokens in your file
For a more detailed approach, you can use the Style Finder plugin in Figma. This plugin scans your entire file and pinpoints exactly where old tokens are located. By using Style Finder, you can quickly identify the specific layers or components where old tokens are used, and with just a click, navigate directly to those locations. From there, you can manually replace the old tokens with the new ones, ensuring your file is fully updated with the latest design token architecture.
Replacing old color tokens with new semantic tokens
Replacing old color tokens with new semantic tokens can be a straightforward process, as some old tokens have direct equivalents in the new architecture, with similar names and usage. To better understand the mapping between old and new tokens, refer to the Token Mapping Sheet—to be found in your Design Tokens file— where you can find detailed information on suitable replacements.
As you replace tokens, consider whether the old token was semantically appropriate and if a better alternative from the new token set could enhance theming capabilities. It’s crucial to adhere to the semantic token guidelines outlined in our semantic tokens documentation, which covers best practices and usage conventions.
For instance, the new semantic tokens clearly indicate their intended use in their names—tokens for backgrounds, foregrounds (such as text and icons), and borders are distinctly labeled. Following these conventions ensures that your design remains consistent and aligned with the new token architecture.
Testing your migration
Once you’ve addressed and replaced all tokens on every screen in your file, it is essential to test whether the tokens have been updated correctly and if your migration has been successfully completed. This section will guide you through the process of validating both the visual outcome of your design and the thorough removal of old tokens from your file.
Testing visual appearance
After updating the tokens, the next step is to ensure that your design looks correct in both light and dark modes. Utilize Figma’s mode-switching feature to verify how your design renders with the new tokens in each mode. Regularly switch between light and dark modes as you make changes to confirm that the visual results meet your expectations consistently.
Confirming token removal
In addition to checking the visual results, it’s important to confirm that all old token usages have been completely removed from your file. You can do this via 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.
