Variants

The production question

You're building the button component from the Day 3 set: three hierarchy values (primary, secondary, tertiary), three sizes (small, medium, large), and four states (default, hover, pressed, disabled). Multiply those axes and you're at 36 variants before you've touched label length, icon presence, or a single real screen. Do you ship all three axes as variants, or collapse one into a property? That's the real decision — not “how do I add a variant” but which options are bounded, structural, and visually distinct enough to earn a spot in the grid, versus which are actually independent toggles that belong as a property layered on top of a smaller grid. Get it wrong and you either lose control over a real design decision (folding hierarchy into a boolean) or you build a properties panel with 36+ entries that nobody, including you in three months, can navigate.

How to decide

1. Ask whether the option is a bounded, mutually exclusive set (primary/secondary/tertiary) or an open-ended value (a label string, a count). Open-ended values are never variants — route them to a text property.
2. Ask whether the option needs to change more than one layer's treatment at once (hierarchy changes fill, border, and text color together) or whether it's a single show/hide or swap decision (an icon appearing or not). Single toggles are Boolean or instance-swap properties, not a new variant axis.
3. Before building anything, multiply your candidate axes on paper. If hierarchy (3) x size (3) x state (4) already gives you 36 and you're still finding “legitimate” axes, that's the variant-explosion warning — stop and check whether one axis is really a separate component with its own responsibilities.
4. For every value in the grid, verify the layer names and structure match its siblings exactly. A text layer named “Label” in the default state and “Button Label” in the disabled state will break any Boolean or instance-swap property you try to apply across the whole set.
5. Choose the default variant deliberately — usually the most common real case (primary, medium, default state) — rather than leaving whatever you drew first. Every instance dragged onto canvas starts from that default.
6. Test by combining extremes: smallest size with the longest label you'll realistically see, disabled with the icon hidden, tertiary hierarchy against an error status badge next to it. If a combination looks broken or nonsensical, either constrain the grid or design that intersection on purpose.

Correct vs. incorrect

Practice it, then try to break it

Rebuild the status badge from Day 3 in about 10 minutes (label plus a colored dot). Add a status variant with four values — protected, at risk, syncing, error — where each value changes the dot color and the text color together. Then add size (small, large) as a second axis and switch through all eight resulting combinations. Confirm every one still reads correctly at a glance; if “syncing” at small size turns illegible, you've surfaced a real combination that needs explicit attention, not a gap you can ignore because it wasn't in the build steps.

Stress test: Rename one layer inside a single variant value only — for example, rename the icon layer inside the “pressed” state but leave the icon layer in default, hover, and disabled with its original name. Then check any Boolean or instance-swap property exposed on that component. If the property silently breaks or disappears specifically for the pressed state, it proves the variant set never had matching structure across its values — a problem invisible until someone touches that exact state.

Common mistakes

• Adding a new variant axis for every option that changes, without first checking whether it's actually a single boolean or text decision — this is what produces the 36-to-144-variant explosion.
• Building one state's layer structure or spacing slightly differently from the others (an extra pixel of padding in “pressed,” a renamed layer in “disabled”) so switching variants visibly shifts the layout instead of cleanly restyling the same structure.
• Leaving whichever variant was drawn first as the default instead of deliberately setting the most common real case, so every new instance starts from an edge case like the disabled or error state.
• Using variants to store unrelated component versions — a completely different button shape or icon-only layout — instead of a bounded set of options within one consistent structure.

Accessibility and handoff

Mismatched layer names or structure across variant values (a text layer called “Label” in one state, “Button Label” in another) breaks a clean state-to-state diff in Dev Mode and forces developers to guess which CSS properties actually changed versus which layers just happen to render differently — keep names and structure identical across every value in the grid.

FAQ

What's the actual difference between a variant and a component property?

A variant is a value in a bounded, structural set — like hierarchy or size — that typically restyles several layers at once. A property is a single independent control (text, Boolean, or instance-swap) layered on top of the variant grid, representing one decision like label copy or icon visibility that shouldn't multiply the grid.

How many variant axes is too many?

There's no fixed number, but multiply your axes before building: if the result includes combinations nobody will ever place on a real screen (tertiary, disabled, large, with icon, paired with an error status), reconsider one of those axes as a separate component, a property, or cut it entirely.

Should hover and pressed still be built as variants if interactive components handle the switching?

Yes — the variant values are the source of truth for what each state looks like. The interactive component setting (used later for prototyping) decides when to switch between them at runtime; it doesn't replace the need for the states to exist in the variant set first.

What happens to variant switching when I detach an instance?

Detaching disconnects the layer entirely from the main component, so you lose the properties panel and every other variant value along with it — you can no longer switch that instance from primary to secondary, you'd have to rebuild it by hand. That's why detachment should be reserved for instances that have genuinely stopped belonging to the system, not routine restyling.