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 Android 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

The new Semantic Token API is available since version 6.5.0 of the Design System. Check the project’s build.gradle file, and ensure that the right version is being used.

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

                                                        
                                                        
                                                            dependencies{" "}
                                                        {implementation("com.backbase.android.design:design-system:6.5.0")}
                                                        
                                                            

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 Android 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 Xcode 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 android folder includes the following files:

Set up the visualizer plugin

The design tokens present in defaultTokens.json cannot be used by an Android app directly. Hence, we need a plugin to transform the design data from the json file to a legible XML output that Android apps can understand. You can follow these steps to add the visualizer plugin in your project.

1. Register maven repository

First, ensure the Backbase Maven repository is registered in pluginManagement, located in the settings.gradle file. If you’ve previously used any other Backbase plugin, you may have already completed this step and can skip it.

                                                        
                                                        
                                                            // settings.gradle file 
                                                        pluginManagement {
                                                            repositories {
                                                                maven {
                                                                    url = uri("https://repo.backbase.com/backbase-mvn-release")
                                                                    credentials(PasswordCredentials::class)
                                                                }
                                                                // Other repositories definition
                                                            }
                                                        }
                                                        
                                                            

2. Add the plugin to your build.gradle file

Once your maven repository is successfully registered, you can proceed by adding the visualizer plugin to the top level build.gradle file.

                                                        
                                                        
                                                            // Top-level build file 
                                                        plugins {
                                                            id("com.backbase.android.visualizer") version "1.1.0" apply false
                                                        }
                                                        
                                                            

3. Register the theme for generation of XML files

Then in the application build.gradle file, add the plugin and using the visualizer extension register the theme to be generated from the defaultTokens.json file.

                                                        
                                                        
                                                            // Application build file 
                                                        plugins {
                                                            id("com.backbase.android.visualizer")
                                                        }
                                                        
                                                        visualizer {
                                                            themes {
                                                                register("Theme.Backbase.Default") {
                                                                    jsonFile = layout.projectDirectory.file("themes/defaultTokens.json")
                                                                }
                                                            }
                                                        }
                                                        
                                                            

In this example, the visualizer extension is registering a new theme, with the name Theme.Backbase.Default and its content will be generated based on the defaultTokens.json file.

4. Extend your application with the new theme

Extend the application theme from the generated Theme.Backbase.Default theme:

                                                        
                                                        
                                                            // Application theme file
                                                        <resources>
                                                            <style name="AppTheme" parent="Theme.Backbase.Default" />
                                                        </resources>
                                                        
                                                            

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

Migrating typography, elevations, spacers and sizers (optional)

In the previous design token system, variables for spacers, sizers, elevations, and typography were included as hardcoded values in the theme export. Unfortunately, this functionality is not yet available in the new Semantic Token API but is actively being developed and will be included in future releases.

For now, you’ll need to manually define these variables in your XML theme file until the exporter supports dynamic export of these values.

                                                        
                                                        
                                                            <!-- Application theme file -->
                                                        <resources>
                                                            <style name="AppTheme" parent="Theme.Backbase.Default">
                                                                <item name="textAppearanceHeadline1">@style/TextAppearance.H1</item>
                                                                <!-- More typograhies -->
                                                                <!-- More spacers, sizers and elevation -->
                                                            </style>
                                                        
                                                            <style name="TextAppearance.H1" parent="@style/TextAppearance.Backbase.H1">
                                                                <item name="fontFamily">@font/<YOUR_FONT></item>
                                                            </style>
                                                        </resources>
                                                        
                                                            

For updating fonts, you have to download .ttf font files and place them under the res/font folder. Then, override the typographies in the application theme file to consume them:

                                                        
                                                        
                                                            <!-- Application theme file -->
                                                        <resources>
                                                            <style name="AppTheme" parent="Theme.Backbase.Default">
                                                                <item name="spacer2XS">2dp</item>
                                                                <item name="spacerXSmall">4dp</item>
                                                                <item name="spacerSmall">8dp</item>
                                                                <!-- more spacers, sizers and elevation -->
                                                            </style>
                                                        </resources>
                                                        
                                                            

While we wait for full support in future releases, this approach ensures that your typography, spacing, and shadow settings are properly applied and ready for migration when the new API updates are available.

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 Android.

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

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