Styles to Variables Migration in Figma

Product designers often face work with multiple color themes for applications they design. This article is about how our design team set up the ability to switch themes for mockups easily and migrated the components library from styles to variables.

Our design team prepares feature mockups for handoff to development in light and dark themes. To do so we had 2 separate UI libraries in Figma with components for light and dark themes. All of these components are built based on color styles.

This approach requires a lot of manual adjustments because style names for a particular component for light and dark themes are not always the same. For example, primary-700 is used for a button background color for the light theme and primary-500 for the dark one. So after the Swap is applied, the background color should be manually changed from primary-700 to primary-500. In addition, in some cases, Figma doesn’t swap components correctly (even with identical style names for both themes), especially if any overrides to instances are applied.

One of the strategic goals of the application that we work on is the ability to support multiple client brandings and color themes. With the current approach adding more themes will increase the time for mockup delivery, the amount of UI libraries, and efforts for their maintenance.

When Figma introduced variables we immediately decided to try if that could help to solve our problem with switching themes for mockups. And spoiler — it solved! And very effectively!

As a new project in parallel with our day-to-day tasks, we started to investigate variables and migrate our components library from styles to variables.

The goals of migration:

1. Provide the ability to easily and quickly switch mockup themes in Figma to speed up mockup delivery.
2. Minimize the amount of Figma UI libraries to support when working with multiple color themes.

Research

Our process started with researching what variables are, how they work, how they differ from styles, and what changes to our UI libraries we might need to make. We reviewed Figma recommendations and different design systems to analyze their approaches to design tokens (hierarchy, structure, and naming) and how they can be aligned with our design system implementation.

What are Variables

Figma variables are analogous to design tokens. They store reusable values that can be applied to various design properties like colors, spacings, or sizings. In our case, we are particularly interested in storing multiple color values. The variable can store different color values for different color themes. When applied to a component variables allow picking a color value for a specific theme.

Useful references about Figma Variables:

• Guide to variables in Figm (Figma Learn)
• Figma tutorial: Intro to variable (Figma YouTube channel)

Approaches to Design Tokens Structure

We researched that various design systems have design token structures with different token levels. The most common approach is the hierarchy with 3 levels of tokens:

• Global tokens — the most fundamental values. These tokens store raw color values (e.g. HEX or RGBA). This level serves for easier referencing of raw values and allows for changes at a global level (like changing color themes). Global tokens are usually not tied to any specific component.
• Semantic tokens — provide context-specific values derived from the global tokens. They map global tokens to a specific use case or meaning within the design system. Semantic tokens help maintain consistency and clarity by describing the intended usage.
• Components tokens — are more specific and tailored to individual UI components. They define the design properties for particular components by referencing global or semantic tokens. These tokens ensure that components are styled consistently and are easy to update.

Useful references:

• Material Design 3
• Adobe Spectrum
• Atlassian Design System
• MEWS Design System
• Tokens, variables and styles (Figma Learn)
• The difference between variables and styles (Figma Learn)

Variables Structure

For our purposes, we decided to go with a 2-level hierarchy which consists of Global and Components Tokens. We picked this approach because:

• this structure is the minimum required to be able to switch themes for components;
• it's very easy to maintain due to the small number of levels;
• this structure is consistent with the hierarchy implemented in the Design System.

Variables eliminate the need to support both our libraries (Light and Dark) which simplifies components management a lot. As a result, we decided to incorporate variables into the Light UI library and remove the Dark one after the migration was completed.

Another thing that we decided to do is to split variables and components into separate libraries. This approach helps to:

• separate edit access for Variables and UI libraries (we have a big design team of 9 designers with different skill levels);
• have separate file histories and track changes for variables and components more easily.

We created a new Variables Library which should include all the tokens. Variables are published to be utilized for components in the UI library. In turn, components from the UI library are published to be used for feature mockups.

Converting Styles to Global Tokens

We tried to find ways to automate variable creation to reduce time-intensive manual actions and speed up the transition process. We tested different plugins for working with variables. 2 of them turned out to be especially useful and helped us to create all the Global Tokens in a few minutes:

1. Styles to Variables Converter — this plugin converts existing color styles into new variables, reflecting their names and structure. It helped us to create global tokens for light and dark themes from existing styles in our libraries.
2. Export/Import Variables — using this plugin we easily migrated global tokens to the new Variables library in 2 steps:

• exported global variables from Light and Dark UI Libraries to .json files;
• imported both .json files to the Variables Library.

Variables in Figma are organized in Collections. As a result of this stage, we came up with 2 collections in the Variables window:

1. “.Global Token [Light]” — all global tokens for the light theme.
2. “.Global Token [Dark]” — the same but for the dark theme.

As you might have noticed, these collections have a dot at the beginning of their names. It is used to block these sets from publishing because global tokens will not be directly assigned to the components.

Component Tokens

As the next step, we started to work with the Component Tokens level and created the new collection in the Variables window. This collection consists of variables that will be assigned to UI library components. To provide the ability to switch components between Light and Dark themes Component tokens should include 2 global tokens placed in separate Variable Modes. Each mode corresponds to a particular color theme (Light or Dark). In the future, more modes will be added there to support multiple clients’ brandings.

When a variable is assigned to the component it allows switching themes in 2 clicks in the Figma right panel.

Component Tokens Structure

Since the Component Tokens collection includes a large number of tokens we also worked on its structure. All the variables are grouped by the components they should be assigned to. Groups are presented in the left panel in the Variables window. Additional rules are prepared for the components that have multiple types (for example, toast alert which has danger, info, and success types):

• variables for the specific types of components are stored in subgroups inside the component’s group. For example, variables that apply to the Danger Toast Alert are placed in the Danger subgroup inside of the Toast Alerts group.
• variables that are general to all types of a particular component are stored without subgroups. These variables are simply placed in the Toast Alert group.

Component Tokens Naming

Another thing we worked on is defining Component Tokens naming to be self-explanatory including where it should be applied to provide easier variable management. We closely collaborated with the Design System team to be consistent with the already implemented token names. As a result, we came up with a naming pattern that includes 4 parts:

1. Component name — the name of a component the variable should be assigned to (e.g. button, toast alert, card, etc.).
2. Type — specific type of this component (e.g. primary, secondary, danger, etc.).
3. Entity — atomic part of the component (e.g. background, stroke, icon, etc.).
4. State — component interactive state (e.g. default, hover, disabled, etc).

In case any of these 4 parts are not relevant for the particular component they may be skipped. For example, if the component is not interactive and has only a default state (for example, a badge), the State part should be excluded. Here are some naming examples:

• dropdown_button-secondary-bg-default
• text_field-outline-border-focused
• badge-primary-bg

Approach to Shadows

We also worked on the approach to shadows. The challenge is that Figma doesn’t provide the ability to create variables for shadows. It allows assigning shadows only via styles. Considering we have different shadows for the Light and Dark themes and still need to use styles, we worked on defining the shadow tokens structure and aligning it with the existing tokens structure.

Accounting that shadow tokens are already implemented in our Design System and have specific names (e.g. shadow-neutral-0) we created the new shadow token collections (for light and dark themes) in the Variables Library to be consistent and reflect these names. Shadow tokens store Global Tokens. In turn, Shadow Tokens are assigned to the Component Tokens, i.e. shadow token names are stored in the component tokens that are assigned to UI components. This approach provides clarity for developers and allows them to review which shadow token is used when inspecting components.

Shadow styles are stored in the Variables library to provide the ability to manage both styles and variables in one place. They have the same names as the component tokens for the shadow color. Styles are published to be utilized in the UI Library.

The connection between tokens and style is the following.

In the Variable Library:

• Shadow Token contains Global Tokens for Light and Dark themes;
• Component Tokens contain Shadow Tokens for Light and Dark themes, as well as tokens for X/Y directions, blur and/or spread properties created as a #Number variable in case it should have different values for light and dark themes;
• shadow style includes component tokens for the shadow properties (color, direction, blur, spread).

In the UI Library:

• shadow style from the Variable Library is applied to a component in the UI Library.

Transition Process Flow

Our design team consists of 9 members. To provide a clear and structured plan that facilitates a smooth and efficient transition for such a big team, we created the flow diagram to visualize the process, review it, and agree with all the contributors.

The transition process consists of 2 global phases:

1. Foundational work includes defining token structures and naming conventions, preparing guidelines, and prioritising components.
2. Component Token creation and assignment implies the manual creation of component tokens and their assignment to components in the UI library. This phase is oriented towards two personas — Variables Creator and Variables Assigner:

• Variables Creator prepares component variables for the specific component in the Variables Library and publishes library updates. Also, they describe tasks in Jira for the variables assignment using the existing template.
• Variables Assigner creates a new branch in the UI Library and links new variables to the component using prepared guidelines. During this work, they also do a QA review of the created variables and communicate with Variables Creator if anything needs to be improved or fixed. After the assignment is done link to the branch is sent back to the Variables Creator to make a peer review.
• Variables Creator makes peer review. If all the variables are assigned and the component switches between themes correctly, they merge the branch and publish UI Library updates.

These steps imply all the team members may contribute to the transition project, which speeds it up. Also, dividing the process between 2 persons provides a two-step peer review, which minimizes the number of mistakes and any issues with the existing library that is actively utilized for feature design.

Project Management

To effectively manage the migration project for our team and monitor the progress we created the new epic in Jira. The epic includes numerous tasks for the Component Tokens creation and assignment for all the elements in the UI library. The tasks are prioritized based on:

• Component atomic structure — atoms first (e.g. colors, typography, icons).
• Component usage — frequently used components first, defined based on the team experience and Figma component usage analytics (analytics is available in the Organization and Enterprise plans).

Guidelines

To document the process we prepared a guideline with all the information about the transition process, variables structure, naming, and creation/assignment rules. It includes examples and also recommendations for different cases. This is the single source of truth for all the contributors to successfully migrate components and achieve consistent outcomes. The guidelines are divided into 2 parts focusing on personas (for variable creators and assigners).

Summary

Migrating from styles to variables significantly speeds up the design process when working with multiple color themes, making it more efficient. By automating foundational tasks, establishing clear structures, and having comprehensive guidelines, you can ensure a smooth transition and engage your entire design team effectively. As design trends evolve, mastering such migrations is becoming increasingly useful.

For our design team, this transition enabled easy and quick theme switching for mockups with just one click in Figma. We decreased time and effort preparing hand-offs for development and maintaining UI libraries. In addition, we are ready to incorporate multiple new color themes and brandings.