Design Systems · Step 3 · 6 min read
Variants, properties and slots
There are three ways to make one component cover many cases: variants for a fixed set of looks, properties for small switches, slots for open areas. When to use each, how they multiply, and how to name them the same in Figma and in code.
Flexibility is a design decision, and every kind of flexibility has a price. A component that can't change gets copied and detached. A component that can change anything stops being a system. Variants, properties and slots are three different answers to "what may change here?", and choosing the right one for each part is most of the craft of building a component.
What you'll be able to do after reading:
- Tell a variant from a property from a slot
- Choose the right one for each thing that changes in a component
- Estimate how many combinations your choices create, and keep them low
- Name them so that Figma and code say the same thing
1. One component, many cases
<Button variant="primarysecondaryghostdanger" size="defaultcompact" iconStart="ticket">Book crossing</Button>
:has(:checked); the button follows the site's light or dark mode.Try it: four variants, two sizes, an optional icon. The button is one component, and the line of code under it changes with your choices. In Harbour's Figma library it's the same: one component set with the properties Variant, Size and Show icon, and the same values.
2. Three kinds of flexibility
| What it is | Use it for | Harbour example | |
|---|---|---|---|
| Variant | One of a fixed list of designed versions | Changes that touch many parts at once: importance, size, state | Button variant: primary, secondary, ghost, danger |
| Property | A small switch: on or off, a text, a swap | One part shown or hidden, a label, a nested icon | Button Show icon (Boolean), Label (text), Icon (instance swap) |
| Slot | An open area that takes other content | Content the system can't predict | The body of a Dialog; the details area of the Ticket card |
Figma has a property type for each of these: variant, Boolean, text, instance swap, and slot (Figma Help, Explore component properties). Figma's own advice for the icon case matches the table: "instead of creating variants for each state, apply a boolean property to the icon's layer visibility."
3. Variants multiply
Variants are the clearest option for people using the library, and the most expensive one for the people who keep it. They multiply.
- Harbour's Button: 4 variants × 2 sizes = 8 frames.
- Add the icon as a variant instead of a Boolean: × 2 = 16.
- Add the five states as a variant (rest, hover, focus, disabled, loading): × 5 = 80.
- Add light and dark as variants instead of variable modes: × 2 = 160.
Each of those frames has to be drawn, kept in sync and checked when a token changes. That's why the icon is a Boolean, the label a text property, and light and dark are variable modes (Themes and modes), not variants. The only axes that stay variants are the ones that really change the design: importance, size and state.
A quick test: if two values of an axis differ in only one layer, it's a property, not a variant.
4. Slots: room for what you can't predict
Some components hold content the system can't know in advance. A dialog can ask a question, show a form or list three options. A card can hold a ticket, a cabin or a meal. Before slots, Figma libraries faked this with a dozen hidden layers or a "placeholder" instance, and people detached the component to get what they needed.
Figma describes slots as "flexible areas placed inside main components that let you freely add, resize, and arrange content within an instance without having to detach it". You can set preferred instances for a slot and a minimum or maximum number of layers (Figma Help, slots). Use those limits: Harbour's Ticket card details slot prefers the Detail item component and accepts at most four.
Code had slots first. In React, everything you put between a component's tags arrives as children; React's docs describe it as a "hole" that can be "filled in" by its parent (React, Passing JSX as children). Web components have a <slot> element for the same idea (MDN, slot). A Figma slot that maps to a code slot is one less thing to explain in a handoff. Lesson 4 of this step goes further: Composition over configuration.
5. Name things the same on both sides
The variant picker above writes variant="secondary" because that's the name in code and in Figma. That sounds obvious. In practice, libraries drift: Figma says Type=Outline, code says variant="secondary", the docs say "secondary button". Three names for one thing.
Rules Harbour uses:
- Property names in code style, in both places:
variant,size,iconStart. Figma allows any name, so use the code one. - Values in lower case, from a fixed list:
primary, notPrimaryin one place andMainin another. - The same order: variant, size, then states. Designers scan the panel in that order; developers read the props in that order.
- Danger is a meaning, not a colour. Carbon treats danger as its own kind of button "for actions that could have destructive effects on the user's data" (Carbon, Button). Harbour does the same, so Skiff can make it a different colour without renaming anything.
When names match, tools can connect them. Code Connect and the design-code bridge shows how.
6. Common mistakes
- Making every difference a variant, until the component set has hundreds of frames.
- Using a variant for light and dark instead of variable modes.
- Slots with no limits, so the "card" ends up holding a whole page.
- Different names for the same property in Figma and code.
- A Boolean that changes three things at once: that's a variant pretending to be a switch.
- Variants named after looks ("Blue", "Outline") instead of meaning ("primary", "secondary").
7. Vocabulary
| Term | Meaning |
|---|---|
| Variant | One designed version from a fixed list, like variant=danger |
| Component set | In Figma, all the variants of one component, grouped |
| Boolean property | An on or off switch, usually showing or hiding a layer |
| Instance swap | A property that swaps one nested component for another, like the icon |
| Slot | An open area in a component that accepts other content |
| Preferred instances | The components Figma suggests for a slot or a swap |
8. Try it (no tools needed)
- Take a component with many versions in a product you know: a card, an alert, a list item.
- List everything that changes between versions.
- Sort each change into variant, property or slot, using the test from section 3.
- Multiply your variants. How many frames would the library need?
Reflection questions: Which change did you first want to make a variant that turned out to be a property? Which part of the component is really an open area?
9. If you already practise
- Audit your biggest component set: count the frames, and find the axes that differ in a single layer.
- Move light, dark and density to variable modes if they're still variants.
- Set preferred instances and layer limits on every slot, and document why.
- Add a lint check or a review question: "Do the property names match the code?"
Checklist
Learn more
- Figma Help: Explore component properties · Create and use slots
- React, Passing JSX as children · MDN, the slot element
- Carbon, Button: five kinds, and danger as a kind of its own
Books, courses and videos to go deeper
- Design SystemsAlla KholmatovaBook · Smashing Magazine, 2017 (Amazon)
- Atomic DesignBrad Frost2016, free online (Amazon)
Book links go to Amazon. As an Amazon Associate I earn from qualifying purchases, at no extra cost to you.
Related
Anatomy and API of a component · States and edge cases · Composition over configuration · Themes and modes · Building a Figma library · Code Connect and the design-code bridge · Design a component with variants in Figma · Component API checklist