On this page
Use a variant when a component needs a different visual treatment, size, state, or structure. Use a Boolean visibility property when an existing layer simply needs to appear or disappear. The number of choices alone does not decide: a button with only default and disabled states can still need variants because several visual properties change together.
A useful component library combines these approaches. In a Pixso design system, reserve variants for meaningful design differences, expose optional content through layer visibility, and use text or instance properties when the change is a label or a nested component. The goal is a component people can configure correctly, with fewer redundant versions to maintain.

Part 1. Define variants and Boolean visibility
A variant is a distinct version of a component within a component set. Primary and secondary buttons, small and large sizes, or default and disabled appearances can be expressed as variant choices. Each version has a unique combination of property values.
A Boolean is a true-or-false value. For layer visibility, it controls whether an existing child is shown. A leading icon can be present or absent without requiring a separate button variant for each case. Hiding that layer does not mean the underlying layer has been deleted.

Neither property type is an automatic performance fix. Fewer variants can reduce duplicated design work, but hidden layers, nested instances, effects, image assets, and other file contents still matter. Count the definitions you maintain, then measure the specific operation that feels slow before claiming a speed or file-size improvement.
Part 2. Set up the property on the right layer in Pixso
Pixso’s component guide distinguishes Variant, Layer, Instance, and Text properties. In this context, Layer is the visibility control discussed as a Boolean. A property belongs on the object it changes; placing every control on the parent without connecting it to a child does not define the behavior.
- Define the button choices. On the main component or component set, create named variant properties such as
sizeandstate. Give each variant a unique combination. - Expose the optional icon. Select the leading-icon child in the main component. Use the property control in the Layer section, name it
showLeadingIcon, and choose its default visibility. - Separate visibility from replacement. If collaborators need different icons, use an Instance property on a nested icon instance. Showing an icon and choosing which icon it is are different decisions.
- Expose the label. Use a Text property for the button label. Do not multiply variants for “Save,” “Save changes,” and “Send invitation.”
- Check an instance. Toggle the icon, change its component, edit the label, and switch size or state. Inspect spacing and text wrapping after each change.
The official guide also notes a prototype boundary: a visibility property does not create two separate objects to connect as interaction states. When a prototype needs distinct targets, represent those targets explicitly. The property panel and the prototype flow solve related but different problems.
Part 3. Choose by the kind of change
Start with the actual change. “Two choices means Boolean” fails for enabled/disabled appearance, compact/comfortable sizing, and other binary choices that modify multiple attributes.
| Requirement | Property to consider | Reason and check |
|---|---|---|
| Show or hide a leading icon | Layer visibility / Boolean | The same optional child appears or disappears; check the remaining label’s spacing. |
| Primary, secondary, or ghost treatment | Variant | Fill, border, and text treatment change together. |
| Default, hover, pressed, or disabled appearance | Variant | A coordinated visual state is more than hiding one layer. |
| Show a modal’s optional close control | Layer visibility / Boolean | Appropriate only if the permitted configuration still has a clear way to dismiss or complete the dialog. |
| Replace a download icon with an arrow | Instance | The slot stays present while its nested component changes. |
| Change “Save” to “Save changes” | Text | The content changes; test the longer label without creating a new variant. |

Also separate related concepts. A loading button may require a spinner, retained width, different label, and prevented repeat submission. A spinner’s visibility can be Boolean, but that toggle alone does not specify the loading behavior. Define the allowed loading state and explain which controls change with it.
Part 4. Work through the 192-to-48 example
Suppose the button library has three sizes, four color treatments, and four visual states. If all combinations are valid, that produces 3 × 4 × 4 = 48 core variants. Adding separate variants for no icons, a leading icon, a trailing icon, and both icons multiplies the set by four: 48 × 4 = 192.
Two independent visibility properties can represent those four icon combinations within each of the 48 core variants. The leading icon is on or off; the trailing icon is on or off. This removes 144 duplicated component definitions from the example. It does not remove 144 arbitrary layers, prove a 75% smaller file, or establish a measured rendering improvement.

Start with the combinations the product actually uses. If a dangerous action never uses the ghost treatment, or a particular size is not supported, a complete Cartesian product is the wrong target. Record the allowed combinations instead of building every possibility and expecting designers to remember which ones are prohibited.
For a realistic check, configure a medium primary button labeled “Save changes.” Try no icons, leading only, trailing only, and both. Switch to the small size and a longer label. If removing the leading icon leaves an empty gutter, correct the layout. If both icons squeeze the label, revise padding or constrain that combination. The clickable target also needs its own size specification; hiding an icon should not accidentally make the action too small.
Boolean bloat is the opposite failure. A single card containing unrelated profile, product, and article layouts as hidden branches can become difficult to understand. Split distinct component families when their content and behavior no longer share a coherent structure. Fewer top-level variants are not useful if configuring one instance becomes a guessing exercise.
Part 5. Agree on the design-to-code mapping
Developers commonly implement a reusable button with properties rather than writing one component for every drawing. A design choice such as size=large can correspond to a code property, and an optional icon can be represented by a Boolean, a slot, or an optional value. Agree on the actual API with engineering instead of assuming every design control becomes a code prop with the same name.

state="hover" prop.Write the contract beside the component: supported size values, default treatment, how icon slots are supplied, what disabled means, and what happens during loading. “Hide the label” should not silently create an unnamed icon-only action. If icon-only buttons are permitted, define their shape, active area, and accessible-name requirement as an explicit configuration.
Design properties organize the specification. They do not by themselves prove that production code has the intended semantics, keyboard behavior, or event handling. Review one implemented instance against the agreed contract before treating the mapping as complete.
Part 6. Refactor an existing library without breaking its users
Ask three audit questions: are unrelated layouts hidden inside one oversized component, are simple optional layers duplicated across many variants, and are property names inconsistent? Turn those questions into a small migration rather than deleting the old set immediately.
- List the configurations in use. Inspect representative screens and record the current property values, labels, and icon overrides. Include a long label and a disabled state.
- Build a replacement beside the current component. Keep stable naming where possible. Use names such as
showLeadingIconconsistently; distinguish them from the icon’s replacement property. - Recreate the same instances. Compare icon-off spacing, label wrapping, nested replacements, dimensions, and focus appearance. Resolve unsupported combinations before distributing the component.
- Review the library update with the team. Document which old configuration maps to which new values. Keep a recoverable copy until representative consuming screens have been checked.
If performance motivated the change, compare the same file and operation before and after under similar conditions. Opening a file, inserting an instance, and changing a property are separate observations. Record what improved and what did not; component-count arithmetic is not a performance benchmark.
A practical choice for the next component
Begin with one button family and its real configurations. Use variants for coordinated visual differences, visibility for optional layers, Instance properties for interchangeable components, and Text properties for labels. Validate the combinations in an instance and agree on their implementation. A smaller library is valuable when it is also easier to configure, maintain, and use correctly.