Creating and organizing Variants

Variants bring a range of new possibilities to components and scalable design systems. At first glance, creating and organizing variants might seem like more work. While there is some effort for the designer creating the component set with variants, the end result for anyone using the component is a simpler and more delightful experience.

Easier component browsing - A designer no longer needs to sift through multiple variations of the same component in the asset panel, or wonder which one is the right one.

Reduced complexity of instances - Easily select or adjust properties without changing the entire component.

Preserved overrides - Nested components and styles overrides are preserved when switching between variants.

Compatibility with existing work - Variants automatically replace any existing components so migration for existing files is a breeze.

This guide will cover some useful tips and practical examples for getting the most out of variants. If you have existing components you'd like to convert to variants, check out the Prepare for Variants guide. And try out the playground file for a hands-on learning experience.

Using Variants effectively

Before we run off and create variants for everything, it’s important to understand when it makes sense to use variants and which situations to avoid. Not everything needs to be a variant and you can still use existing techniques alongside variants.

Use variants when:

• Multiple versions of similar components share the same properties such as state, size, count, layout, and more.
• Components can toggle between two distinct variations that could be represented as true/false, on/off, or yes/no.
• Component variants map to properties that align with your code components following the prop/value format used in popular frontend frameworks like React and Vue.

Avoid situations where:

• Adding variants creates an unmanageable number of permutations, consider nesting instances or using base components instead.
• Colors or themes might create an increasing number of variants and would need to be maintained across every component.

Nesting instances

Nesting instances is a powerful technique for composing complex designs and can be used alongside variants for more complex component sets.

Let's start with a button. You may have several properties like type (primary, secondary), state (active, hover), or whether the button has an icon or not.

You might be tempted to define a variant for every possible icon, but this quickly becomes unmanageable. It's better to use an instance of an icon and swap the nested instance as you would with traditional components.

Library organization

Figma offers several approaches for organizing components in the assets panel through naming conventions of layers, frames, and pages. As discussed in the Prepare for Variants guide, streamlining your design system with variants can simplify some of these conventions and might make others redundant.

Layers - When combining variants, any forward-slash / groups in layer names will be converted into values for variant properties. You can still add additional forward-slash groups after-the-fact if you want to add or restore other levels of hierarchy.

Frames - Frames can be used to group related components. When combining variants, the frame may become redundant so you can either remove it or use it as a larger grouping if you have multiple component sets on the page.

Pages - If you have main components on multiple pages, the page name will also appear in the assets panel. It's possible that all of your components on a page will combine into a single component set (Buttons/Button). While this might feel repetitive, keeping the "Buttons" page will allow for additional button components in the future that may not be part of the Button component set.

Alternatively, there might be opportunities to combine pages into more logical groupings of component sets. If you end up with a page with a single Input component set and another with a single Dropdown, you might consider combining these on to a "Forms" page.

Adding variant descriptions

Each variant component can have its own description, along with a description for the whole component set. The descriptions for both the component set and the specific variation will appear in the inspect panel.

Existing component descriptions will become variant descriptions when combined so you won’t lose anything you’ve already added.