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.

Multiple brand themes or colors will create a lot of permutations and could be difficult to maintain across all your components. We hope to tackle this head-on in the future.

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.

Using base components

Another way to utilize nested instances is by allowing variations to share a base component. Base or "structure" components are a great way to define consistency across your components and can still be used with variants to make changes at scale.

Base components themselves don't need to be part of your component set and can be placed nearby on the same page or frame. Use a . or _ to prevent them from being published as part of the design system.

Avoid nesting individual variant instances for specific properties of the component set. It might be tempting to cut down on the number of permutations, but it will be more maintenance, less flexible, and a frustrating experience for anyone using the component.