Applying theme

How to apply a theme in your code

After completing this guide, your iOS app will be themed according to your branding. Before following these steps, make sure you've successfully created a theme with the Backbase Visualizer.

Note: If you’d like to apply a theme on iOS on a release version prior to 2024.09, read our guidelines in our old documentation site.

From the exporter you should have a folder that includes:

Description	Contents
The design tokens file	defaultTokens.json
A logos folder with your brand's logos	.pdf logo files
A fonts folder with your brand's fonts	.ttf or .otf font files

If you were provided with fonts in a different format—such as WOFF, WOFF2 or EOT—, you can use a third-party tool like CloudConvert to convert your font files to the desired format. Different native platforms might accept a different subset of font file formats, but we recommend sticking to a single one from TTF or OTF for ease of the theme deployment and for consistency.

Import token file

Unzip and open the theme.zip file and copy the defaultTokens.json to your project in Xcode.

Step 1

Drag and drop the file into your project

Open the theme folder, select the defaultTokens.json file and drop in into your project's source folder.

Step 2

Configure destination and the target

After you’ve dropped the tokens file into your project a dialog window is going to open. Make sure to select the Copy items if needed in the destination field, select your app as the target and then click the Finish button.

Step 3

Initialise the Mobile Design System SDK

Add these lines to the AppDelegate.swift file:


                                                                                                                                                  
                                                                                                                                                  
                                                                                                                                                      Theme.decodingInfo.filename =  "defaultTokens"
                                                                                                                                                  // The bundles to look for the file
                                                                                                                                                  Theme.decodingInfo.bundles = [.main]

Note:

You only need to change this if your default token file has a different name. By default it will look for defaultTokens in bundle .main and .design. Make sure that this is set before the Design System has been used, as the first usage of a token will trigger the Design System to ingest the tokens from the JSON.

Import logos

For in-app logos, it's best to use the .pdf format. This will ensure that the logos will scale properly to different screen sizes. Overriding Backbase's logos is as easy as importing four images into your project's .xcassets.

Step 4

Add the wide logo

First, drag and drop the app-logo-wide.pdf file into your .xcassets.

Step 5

Configure your image set

Proceed by properly setting up your image set via the right panel. You can follow these settings:

Appearances: Any, Dark

Scales: Single scale

Step 6

Import the dark appearance

Now drop the app-logo-wide-dark.pdf into the asset’s dark appearance to make sure the asset will properly render in dark mode.

Step 7

Repeat for the square logo

Finally, you can follow the same instructions to import app-logo-square.pdf:

Add the square logo to your assets

Configure the appearance and scales fields

Add the square logo’s dark appearance

Step 8

Add explicit light and dark logos

In order for you to be able to use the light and dark version of the logo explicitly, regardless of the device’s preferred color mode you can also import all of the standalone files with -light and -dark suffixes. Add these files to your assets and make sure to configure the Appearance field to None.

Import fonts

For iOS you will need to have the font files in .tff format, which have a separate font file for each font weight.

Step 9

Map the font files to the correct font weights

Inside your AppDelegate.swift, you can edit the font filename mapping to use the custom font files you have. Simply match the name of the file to the corresponding font weight. Do not include the .ttf extension in the filename.


                                                        
                                                        
                                                            DesignSystem.shared.fonts = DesignSystem.Fonts(fontFileNameMappings: [
                                                            .black: "LibreFranklin-BlackItalic",
                                                            .bold: "LibreFranklin-BoldItalic",
                                                            .heavy: "LibreFranklin-ExtraBoldItalic",
                                                            .ultraLight: "LibreFranklin-ExtraLightItalic",
                                                            .light: "LibreFranklin-LightItalic",
                                                            .medium: "LibreFranklin-MediumItalic",
                                                            .regular: "LibreFranklin-Italic",
                                                            .semibold: "LibreFranklin-SemiBoldItalic",
                                                            .thin: "Li

fonts-import

Step 10

Drop the font files into your project

If your project already doesn’t have a specific place to keep fonts, create a new Fonts folder in the Sources directory of your project. Then simply drag & drop the font files to your project.

fonts-setup

Step 11

Check your bundle resources

Make sure your font files are being properly copied to your app's main bundle under:

Build Phases → Copy Bundle Resources

You have now successfully applied your theme to your app using the design system tokens!