Migration in code

With the introduction of the 2024.09-LTS release and our new semantic design tokens, we are committed to ensuring a smooth migration for our customers. This guide provides a clear, step-by-step approach to transitioning to our new Semantic Token API, helping you successfully upgrade your web projects to the latest design token architecture.

At a high level, the migration process involves three key steps:

1. Migrating Figma files

Updating your theme, design system and journeys in Figma to align with the new tokens.

2. Migrating your theme

Transitioning your project’s theme to use the latest design token architecture.

3. Migrating custom journeys

Adapting custom journeys to integrate with the new Semantic Token API.

Installation

First, ensure that your project has the @backbase/ui-ang package installed. To access the new Semantic Token API, the package must be updated to version 11.12 or higher.

You can install the right version of the package with the following command:

                                                        
                                                        
                                                            npm i @backbase/ui-ang@11.12
                                                        
                                                            

Theme migration

The first step in migrating your project to the new Semantic Token API is updating your theme. This process converts your current design token values to a new format, which follows modern design token practices and supports our new semantic token structure.

Migrate theme & export files from Figma

The migration of your theme from the old design token architecture to the new one happens primarily in Figma. This means that migrating in Web requires the Figma migration to be completed first. In Figma, our Semantic Token Migrator plugin can be used to easily update your old design token values to align with the new Semantic Token API. After that you can use the Visualizer to export code-ready theme files directly from your Design Token file in Figma. This ensures a seamless migration of your theme in both design and code.

If you’re a developer looking to migrate your project’s theme, and you don’t have edit access to the Figma files, you’ll likely need to collaborate with your designer to handle the migration and export of theme files.

For a detailed step-by-step guide in Figma, you can refer to a dedicated article on migrating your theme in Figma.

Import new theme to your project

Once you have the new theme files exported from Figma, you can continue with importing the right files into your project. The theme files are shipped as a bundled .zip file, which contains theme files for each platform in separate ios, android and web folders.

The web folder includes the following files:

1. Copy tokens into your themes folder

To begin you can copy the default.scss file and paste it into the themes folder of your app. If your app does not already have one, create a dedicated themes folder next to your app.

2. Import theme to your app

Ensure the new theme has been imported into your app. This depends on the approach you are adopting to inject your theme (i.e. single-theme approach vs. multi-theme approach).

Single-theme approach

If you're using the single theme approach, ensure that the old theme in your global stylesheet is replaced with <app-path>/themes/default/main.scss. The following process is also documented in detail in a dedicated article about applying a theme on Web.

First, locate your global stylesheet. You can find its path by checking your angular.json (or project.json if you're using NX to manage your apps). The app section, such as "retail-usa," may vary depending on the project you're theming (e.g., "business-universal," "business-usa," or "retail-usa").

                                                        
                                                        
                                                            "options": {
                                                            ...
                                                            "styles": [
                                                                "apps/retail-usa/src/styles.scss"
                                                            ],
                                                        }
                                                        
                                                            

Once you've located the global stylesheet, open it and import the theme styles by adding an import statement at the top of the file:

                                                        
                                                        
                                                            @import 'themes/style.scss';
                                                        
                                                            

Multi-theme approach

If you’re using multiple themes in your app you’ll have to ensure that the new theme is injected into your project.json. Set inject: true so that it is available in your app by default. The following process is also documented in detail in a dedicated article about multi-theming on Web.

We recommend building your app to verify that your theme has been successfully migrated and that the visual integrity of your project has been preserved.

Journey migration

In this step, all design tokens used in your projects will be migrated from the old API to the new Semantic Token API. This involves converting each token in your project to its corresponding token in the new system. While the migration process is mostly manual, it is primarily handled by designers in Figma, so as a developer, you won’t be responsible for selecting the appropriate replacements for the old tokens.

Typically, the designer will take the lead by refactoring and migrating all design files in Figma to use the new semantic tokens. After completing this, the designer will hand over the updated Figma designs to you as a developer, where you can inspect them and identify the new tokens for use in development.

To assist the designer in their part of the process, you can direct them to the relevant article about Journey migration in Figma. Close collaboration between designers and developers is key to ensuring a smooth transition.

How to read tokens in Figma (as a developer)

If your designer has migrated the Figma designs to use semantic tokens and handed over the design files to you for implementation, it’s important to understand how to read and translate the token names from Figma into your code. There’s a consistent pattern you can follow to make this process smoother. Additionally, tokens available in Figma always have a matching token available on Web.

In Figma, token names typically use a format like background/page. However, when working in your Web code, these tokens are accessed slightly differently. Here’s a few basic examples:

Comparing the old and the new API

In terms of usage, there should be minimal differences between the old tokens and the new ones. However, the new approach provides clearer, more meaningful semantic naming, making it easier to understand and work with design tokens.

Here’s a comparison to illustrate the difference:

                                                        
                                                        
                                                            // Old API
                                                        $color-primary
                                                        $color-neutral-white
                                                        
                                                        
                                                        // New API
                                                        $color-background-brand
                                                        $color-background-surface-1
                                                        
                                                            

If you want to dive deeper into the concepts behind the new API, including the theory and detailed use cases of semantic tokens, you can refer to a dedicated article that explains the foundational concepts.

Frequently asked questions