···

    Prepare for variants

    Variants has arrived! 🎉 For detailed instructions on how to use variants, check out our Create and use variants article.

    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:

    A screenshot of the canvas in Figma with 24 variants of a button component. The variants are grouped in a grid structure in one container and there are labels on the top and sides to explain the properties and values of the variants

    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.

    An instance of a single variant selected in the canvas. In the right sidebar we can see that it is a component of a button, which has the values of primary, large, and default.

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

    Note: You can only convert components into variants. If your selection includes other layers or objects, you won’t have the option to combine them as variants.

    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

    Note: These suggestions affect how users can select components from libraries in Figma. If this will cause problems for your team, hold off on making these changes until you have access to variants.

    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.

    An annotated diagram which shows a list of variants for a button component before they are converted to variants. Next to that we see the instance section of the right sidebar after they have been converted to variants. There are lines that connect each level in the variant name to the property in the sidebar.

    Tip! You can also rename layers in bulk using the rename layers modal. Learn more about renaming layers in bulk →

    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.

    A button with each of its variants. In step two we override the fille color, which is preserved when we switch to the hover state as this variant has the same original fill. When we switch to the secondaary variant, the override isn't kept as the original fill is different.

    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.

    A screenshot of the button variants organized in a grid on the canvas. The properties and values are labelled. There is a line under each label to color-code it. The instance panel is also open in the right sidebar and is highlighted to match the color-coding of the labels in the canvas.

    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.

    Create instances of variants: Figma will make sure your instances point to the correct component. When you convert components to variants, any instances will reference the new variant.

    Anyone accessing design systems in the Assets panel or Instance menu will see a single result for that component. Once they place an instance on the canvas, they can select the desired variant in the right sidebar.

    Related Videos

    See more