Variants introduce a new way to group and organize variants of the same component. This makes components easier to maintain and more intuitive to use.

Combine variants into a single component with custom properties and values. These can mirror front-end code, simplify asset libraries, and make picking the right variant easier.

You can have as many properties and values as you need. You can define properties and values during the creation process, as well as add, remove, and reorder them as your design system evolves.

In our example, we have a button component which has 24 variants. You can see these variants in this image of our design system:

There are four properties in our example, each containing a set of values.

• Type property with Primary and Secondary values.
• Size property with Large and Small values.
• State property with Default, Pressed, and Inactive values.
• Icon property with True and False values.

Figma uses this set of properties and values to identify each unique variant. The screenshot below shows this variant in the Instance section of the right sidebar.

Use the next to the property to select your preferred combination of values. Or toggle specific properties off and on using the and switches.

Prepare for variants

There are a couple of things that you can do to make converting your existing design system components as easy as possible.

1. Use a consistent naming convention
2. Checks for override preservation
3. Organize components on the canvas
4. Group related components

Use a consistent naming system

Figma already supports slash / naming system to organize components. You can use this naming system to help convert your existing components to Variants.

We recommend using the following structure for any components you want to convert: componentName/property1value/property2value/property3value

• Any text before the first / will become the component name. Every extra / level will create a new property.
• By default, Figma will name the first property Variant, the next Property 2, then Property 3, and so on.
• Every variant will need a value for each property. Make sure that each component uses the same number of slashes.
• If you have suffixes in your naming system, you should convert these to / levels before combining the components as variants. For example: if you have component states for - hover or - pressed, create another / level for the state.
• When you combine variants into one component, Figma will create toggles for any Yes/No or True/False values.

For example: our button component has the following name: Button/Primary/Large/Default/True

Once converted, the resulting variant will look like:

Component name: Button
Variant: Primary
Property 2: Large
Property 3: Default
Property 4: True

You’ll be able to change the name and order of any properties once you convert them to variants. Reorder properties in the Variants section of the right sidebar. This will also change the order of the values in each variant’s name.

Checks for override preservation

With this launch, Figma is also changing the way overrides are preserved. Figma will now preserve all supported overrides, including overrides to fill and stroke properties, and blur or shadow effects. This will apply when swapping between instances, as well as selecting different variants.

Figma will use the following criteria to determine whether to preserve an override:

• Layer names need to match between the current instance and the variant you're selecting. This applies both when swapping instances and selecting variants.
• When selecting variants, Figma will also check if the layer properties you’ve overridden originally match between variants. If so, Figma will preserve your overrides.

In the example below, Figma preserves the fill override on Step 3, but not on Step 4.

This is because the default primary button and hover primary button both have a matching fill of #1BC47D. Our override changes the hex code from #1BC47D to #F531B3.

Figma doesn't preserve our override when we select the hover secondary variant, as this variant has a fill of #ffffff, not the #1BC47D we applied our override to.

Organize components on the canvas

It can be easier to keep track of all your variants if you lay them out in a grid. The top-level container of a component can’t hold anything other than variants. This means you can't group a set of variants together, or insert text or other annotations into the container.

To annotate your variants, we recommend adding text labels for relevant properties and values beside the variant container.

You don’t need to have a component for every possible combination of properties and values, just the ones that you and your team use. This can include any variants you’ll need for interactive components.

Figma groups variants in a single container. By default, Figma will represent this container with a dashed, purple border. Like regular frames, you can adjust the properties, like fill or stroke, to suit your design system.

Group related components

Figma only looks at layer names when combining components, not page and frame names. If you were using pages or frames to organize variants, these may become redundant on conversion.

You’ll still be able to use pages and top-level frames to create extra levels of hierarchy. This makes for better component organization in the Assets panel and Instance menu.

You could use an approach similar to Shopify’s Polaris design system. It groups sets of components, that are functionally similar. For example Button and Button Groups under Actions, or Text field and Date picker under Forms.