Figma theme export guide
In the following guide, we will walk you through how to set up your Figma environment for creating, managing, and exporting design tokens through the Visualizer. This setup ensures seamless collaboration between design and development and minimizes errors during export and implementation.
Validate version compatibility
As a first step we want to avoid exporting issues, so we want to make sure you're using the correct Visualizer version depending on your release. Use the table below for reference:
All Visualizer exports from version 1.3.0 onwards are backwards compatible.
|
Release |
Web |
iOS |
Android |
Visualizer |
|---|---|---|---|---|
|
2024.09 |
11.0 |
5.0 |
6.0 |
1.2.0 |
|
2024.10 |
12.0 |
6.0 |
7.0 |
1.3.0 |
|
2025.03 |
12.0 |
6.0 |
7.0 |
1.3.0 |
|
2025.04 |
13.0 |
7.0 |
8.0 |
1.4.0 |
You can validate the Visualizer version in the JSON export or in the Metadata collection (after 2025.03) under tokenVersion.
Exporting tokens
Once you are satisfied with your brand's theme setup in Figma through the Visualizer and have previewed how the final application of the theme will appear in the actual product, you can export the design values directly from Figma and share them with your developers using the Visualizer widget. You can read the guides for creating a theme here.
With our new token architecture it is crucial and important to know that altering any variable names will cause errors and crashes in your production environment. If you choose or want to change the name of a token. Rename the style on the right panel and not the variable.
You can rename styles
Do not rename variables
What files to expect
The theme file is split into three folders, each representing one platform. The following is included in the folder:
Web
- default folder, which contains the default theme (your theme created in the Visualizer)
- premium theme, which contains the premium theme
- logos, which contains all 4 SVG versions of the brand’s logo
iOS & Android
- defaultTokens.json (your theme created in the Visualizer)
- premiumTokens.json (the premium theme)
- logos, which contains all PDF or SVG versions of the brand’s logo
Troubleshooting token export errors
invalidVersion
Cause
The invalidVersion error indicates that the JSON schema file you’re attempting to use is outdated. This happens because the Visualizer widget in the 2024.09 & 2024.10 files is a V1. Figma does not automatically update the Visualizer widget and will keep the version of the instance that was originally inserted. However, the steps and precautions to resolve this issue depend on the version you are running.
Fix
- Insert the latest version of the Visualizer (see Upgrading the Visualizer widget).
- Ensure tokenVersion and figmaVersion are defined in the Metadata variables collection.
tokenMalformed
Cause
The tokenMalformed error typically occurs due to an encoding issue where the system cannot find a required token value. The error triggers a loop in the system as it repeatedly fails to decode the malformed token.
Fix
- Ensure all tokens resolve to Primitives or direct HEX codes.
- Do not delete or rename base tokens on releases earlier than 2024.10.
- Don’t use published library as alias for token references as these cannot be resolved into HEX codes.
- Ensure that no tokens are unpublished or underscored. Variables folders that have an underscore prefix before their name are hidden from the exporter.
Upgrading the Visualizer widget
Figma does not automatically update the Visualizer widget and will keep the version of the instance that was originally inserted. However, the steps needed to take to resolve this issue depend on the version you are running. Follow one of these methods:
Option 1 | Insert a new instance (latest Visualizer version)
Validate collections
As the next step we need to ensure the required collections exist and are named correctly. Go to Figma’s Variables panel and check that the following collections exist:
- Metadata
- Primitives
- Theme
If needed, rename Primitives-default to Primitives.
If a Metadata collection does not exist
- Create a new collection and call it “Metadata”.
- Add the following string variables to it, each one with the corresponding value shown below:
- tokenVersion = 1.6.0
- figmaVersion = 2025.03
Option 2 | Download Visualizer file (older versions)
After upgrading
- Re-export your tokens.
- Confirm version in the JSON of the export.
- Ensure its compatibility with the version table.
Final notes
To ensure a smooth export process, always verify that your Visualizer widget version is compatible with your target platform. It's important to maintain consistent and published token structures across your design files to prevent errors during export. Use this guide as a reliable reference throughout onboarding, version upgrades, and whenever you encounter issues related to token configuration or export.
Next steps
Now that your Figma environment is set up, you're ready to bring your brand to life. Start by exploring our Visualizer to define your global branding and fine-tune component styling across platforms. Once your theme is finalized, proceed to apply it to your Backbase development environment. Use the export tools provided to implement themes seamlessly across Android, iOS, and Web, ensuring a consistent and on-brand user experience throughout your digital products.
Apply themes
How to export and apply a theme to your Backbase development environment.
Apply a theme on Android
Theme your Android app according to your branding
Apply a theme on iOS
Theme your iOS app according to your branding
Apply a theme on Web
Theme your Web app according to your branding
Multi-theming
How to add multi-theming support to your apps.