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 iOS 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 BackbaseDesignSystem Cocoapod package installed. To access the new Semantic Token API, the package must be updated to version 5.2.1 or higher.

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

                                                        
                                                        
                                                            pod `BackbaseDesignSystem`, '~> 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 iOS 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 ios folder includes the following files:

First, grab the defaultTokens.json file and drop it into project’s resource directory. You must ensure that this file is being included in your Copy Bundle Resources build phase. After this, the exported theme should be already automatically applied to your project.

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.

Changing file & bundle names

Some projects may have specific requirements, naming conventions, or custom directory structures. If you need to use a different name for your defaultTokens.json file or want to specify a different bundle for the file, you can modify the following line at the top of your AppDelegate.swift:

                                                        
                                                        
                                                            import BackbaseDesignSystem
                                                        
                                                          final class AppDelegate: RetailUniversalAppDelegate {
                                                            
                                                                override init() {
                                                        
                                                                    Theme.decodingInfo.filename = "YOUR_FILE_NAME.json"
                                                                    Theme.decodingInfo.bundles = [{{YOUR_BUNDLE_NAME}}] // defaults to .main if not set
                                                                    
                                                                    super.init { (sdk, design) in
                                                                        …
                                                        
                                                            

Migrating typography, shadows, spacers and sizers (optional)

In the previous design token system, variables for spacers, sizers, shadows, font file names, and font families 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 code until the exporter supports dynamic export of these values. To map custom font file names, you can update your AppDelegate.swift with the necessary font family mappings. Similarly, spacers, sizers, and shadow variables should also be set directly in your code.

Here’s an example of how to do this:

                                                        
                                                        
                                                            // Font Family
                                                        DesignSystem.shared.fonts = DesignSystem.Fonts(fontFileNameMappings: [
                                                            .black: "<>-Black",
                                                            .bold: "<>-Bold",
                                                            .heavy: "<>-ExtraBold",
                                                            .ultraLight: "<>-ExtraLight",
                                                            .light: "<>-Light",
                                                            .medium: "<>-Medium",
                                                            .regular: "<>-Regular",
                                                            .semibold: "<>-SemiBold",
                                                            .thin: "<>-Thin"
                                                        ])
                                                            
                                                        // Sizers
                                                        DesignSystem.shared.sizer.xxs = 1
                                                        DesignSystem.shared.sizer.xs = 2
                                                        DesignSystem.shared.sizer.sm = 4
                                                        DesignSystem.shared.sizer.md = 8
                                                        DesignSystem.shared.sizer.lg = 16
                                                        DesignSystem.shared.sizer.xl = 32
                                                        DesignSystem.shared.sizer.xxl = 64
                                                        
                                                        // Spacers
                                                        DesignSystem.shared.spacer.xxs = 1
                                                        DesignSystem.shared.spacer.xs = 2
                                                        DesignSystem.shared.spacer.sm = 4
                                                        DesignSystem.shared.spacer.md = 8
                                                        DesignSystem.shared.spacer.lg = 16
                                                        DesignSystem.shared.spacer.xl = 32
                                                        DesignSystem.shared.spacer.xxl = 64
                                                        
                                                        // Shadows
                                                        DesignSystem.shared.shadows.large = .init(offset: .init(width: 20, height: 20), 
                                                            opacity: 0.8,
                                                            radius: 16,
                                                            color: .black)
                                                        
                                                            

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

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

Comparing the old and the new API

As you begin migrating your project to the new Semantic Token API, it’s essential to understand the key differences between the old and new APIs. In the old system, tokens were accessed through the DesignSystem.shared object, whereas the new API simplifies this by using the Theme object. 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
                                                        let backgroundColor: UIColor = DesignSystem.shared.colors.primary.default
                                                        
                                                        // New API
                                                        let backgroundColor: UIColor = Theme.colors.background.brand
                                                        
                                                            

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