Marcus Andrey Study
Ler em português Library

Design Systems · Labs · 5 min read

Design a component with variants in Figma

A guided lab: design the Harbour button as a Figma component set, starting from its API. Write the props table, build one base with auto layout and variables, add variant, boolean, instance swap and text properties, and test it the way people will break it. About two hours in Figma.

A component set with 90 variants is usually three properties pretending to be one. The fastest way to a small, honest component is to write its API before you draw it: which choices does a designer make, and which are just content? You'll build the Harbour button that way, so the Figma properties match the code's props and the set stays small.

What you'll do:

  • Write the button's props table before drawing
  • Build one base with auto layout and semantic variables
  • Add variant properties, then boolean, instance swap and text properties
  • Decide what is a variant, what is a property and what is a slot
  • Test the component with long text, both modes and a swap

You'll need: Figma (publishing to a library needs a paid plan; building doesn't), the variables from Build a token set with modes or any light and dark set, about two hours.


1. Write the API first

variant
size
boolean
Book a seat

Button: variant=primarysecondarydanger, size=mdsm, showIcon=truefalse, label="Book a seat"

The Harbour button with the properties you'll build: two variant properties, one boolean and one text property. Three variants times two sizes is six variants in Figma; the icon and the label are properties, not variants, so they don't multiply the set. Text contrast: 6.35:1 (primary, secondary) and 5.14:1 (danger).Live demo: Marcus Andrey, CC BY 4.0. CSS only, no script.

Play with the figure: that's the component you'll build. Before opening Figma, write its props table. Figma has five kinds of component property: variant, boolean, instance swap, text and slot (Figma, Explore component properties).

Property Figma type Values Default In code
variant Variant primary, secondary, danger primary variant
size Variant md, sm md size
state Variant default, hover, pressed, focus, disabled default CSS states, not a prop
label Text any "Button" children
showIcon Boolean true, false false icon is set
icon Instance swap any icon from Harbour Icons arrow-right icon

The rule of thumb: if it changes how the component looks by design choice, it's a variant. If it's content, it's text or instance swap. If it turns a part on or off, it's boolean. A label as a variant, or an icon per variant, is how sets explode.

state is a variant in Figma because designers need to show and hand off hover and focus, but in code it's the browser's job (:hover, :focus-visible, disabled). Note that in the "In code" column, so nobody adds a state prop (see States and edge cases).


2. Build one base

  1. Draw the primary, medium button once: a frame with auto layout, horizontal, gap 8, padding space.5 (24 px) left and right, height 44.
  2. Inside it, a text layer for the label and an icon instance after it.
  3. Bind the fill to color.action.primary, the text to color.text.on-action, and the corner radius to radius.control. No raw hex anywhere.
  4. Set the frame to hug its content horizontally, so a long label grows the button instead of being cut.
  5. Make it a component (⌥⌘K on Mac, Ctrl+Alt+K on Windows) and name it Button.

Check the base in both modes before you multiply it. Every mistake now becomes 30 mistakes later.


3. Add the variant properties

Add a Variant property from the properties panel; Figma turns the component into a component set, a container that can only hold components. Every variant has to be a unique combination of property values, but you don't have to build every combination (Figma, Create and use variants).

  1. Name the first property variant and add secondary and danger. Change their bindings: secondary is a color.surface.default fill with a 2 px color.action.primary stroke and text; danger uses color.feedback.danger.
  2. Add size, with sm: padding 16, height 32, label 14 px.
  3. Add state last, with its five values. Focus is a 2 px ring with a 2 px gap, in a colour that passes 3:1 against the background in both modes.

Three variants × two sizes × five states is 30 components. That's fine; 30 with a clear grid is easy to maintain. Lay them out as a grid with labels beside the set, and keep the default (primary, md, default) in the top-left corner, because Figma uses the top-left variant as the default.


4. Add the other properties

  • Text property on the label layer, named label. Designers now type the label in the properties panel without digging into layers.
  • Boolean on the icon layer, named showIcon, default off.
  • Instance swap on the icon, named icon, with preferred instances set to a short list of icons that make sense on a button.

Use multi-edit to apply them to all variants at once. Then open the properties panel on an instance: you should see variant, size, state, label, showIcon and icon, and nothing else. If you see "Property 2", rename it.


5. Variant, property or slot?

The button doesn't need a slot. A slot is a flexible area in a component where people can add and arrange content in an instance without detaching it, useful for things like a list of tasks or the body of a card or a dialog (Figma, Slots).

Try it on a second component to feel the difference: a Harbour SailingCard with a header and a body. Make the body a slot, with preferred instances (Tag, Notice, a text block) and a maximum of three layers. Now one card can hold what product teams need without a variant for every combination, which is the idea behind Composition over configuration.


6. Test it the way people will break it

  1. Long label: "Continue to payment and seat selection". Does it grow, wrap or cut? Decide, and document it.
  2. Short label: "OK". Is it still at least 24 × 24 px? (WCAG 2.2 asks for 24 × 24 CSS pixels as the minimum target size, Understanding 2.5.8.)
  3. Dark mode: switch the variable mode on the frame. Every variant, every state.
  4. Swap: place an instance, then change variant, size and icon. Nothing should shift that you didn't expect.
  5. A designer who didn't build it: give them the component and a screen to make. Watch where they hesitate.

7. Check your work

Reflection questions: Which property did you want to make a variant, and why wasn't it? What did the designer who didn't build it get wrong first?

Variants, properties and slots · Anatomy and API of a component · Building a Figma library · Code Connect and the design-code bridge · Accessible components

Saved only on this device.

↑ ↓ to move · Enter to open · Esc to close