Use variables and variants

Variables keep repeated values consistent, while component variant properties let one reusable component represent choices such as size, state, or theme.

The representative video demonstrates this exact workflow: Open Variables and create a named variable collection.

Verified result: The Variables tab is selected and the new Tutorial colors collection is active.

Create a variable collectionOpen Variables and create a named variable collection.Result: The Variables tab is selected and the new Tutorial colors collection is active.

Transcript

1. Open VariablesChoose Variables in the left panel.
2. Start a collectionChoose New collection to open the collection name dialog.
3. Name the collectionEnter Tutorial colors as the collection name.
4. Save the collectionPress Enter to save the collection and make it active.

Download the tutorial videoDownload English captions

Before you start

• Open the Variables tab in the left panel to work with variables.
• Create or select a main component before defining variant properties.
• Unlock the selected object. Binding and variant changes are unavailable in a view-only file.

Create a collection and color variable

1. Open Variables.
2. If the file has no collection, choose New collection, enter a name such as Primitives, and choose Save.
3. Choose New variable. The current panel creates a color variable named color/untitled with a unique suffix when needed.
4. Choose the variable name control to rename it, for example color/brand/primary.
5. Choose its value to enter a new color for the active mode.

A slash in a variable name creates a visual group in the panel. For example, space/small appears under a SPACE heading, while color/brand/primary appears under COLOR.

Names cannot be blank. Number values must be finite numbers, and boolean values must be true or false.

Add and switch modes

Modes let the same variable have different values, such as Light and Dark colors.

1. Select the collection.
2. Choose New mode, enter a name, and save it.
3. Use the mode menu to switch the collection’s active mode.
4. Edit each variable’s value while the intended mode is active.

Changing the active mode updates compatible bound objects on the canvas. Keep at least one mode in a collection; the delete control is unavailable for its final mode.

Bind a variable to a layer

1. Select one or more compatible, unlocked layers.
2. In Variables, choose Bind on the variable row.
3. Confirm the visible property changes on every selected layer.

The Variables tab uses a sensible default property for each type: color binds to Fill, number to Opacity, string to text content, and boolean to Visibility. The Fill and first Stroke rows in the Inspector also provide a variable picker for compatible color variables.

Choose Unbind to remove the relationship while keeping the value currently shown by the active mode. If any selected layer is locked or incompatible, the complete multi-selection binding is rejected so the selection is not left half changed.

Add variant properties to a component

1. Select the main component.
2. Choose Design System in the top bar.
3. In the Variant Matrix, choose Add property.
4. Enter a property name such as State.
5. Enter comma-separated options such as Default, Hover, Disabled and choose a default.
6. Save the property.

Repeat for another dimension such as Size with options Small, Medium, Large. Rename, edit, or remove a property from the same properties list.

Switch an instance to a variant combination

1. Create and select an instance of the component.
2. Open Design System.
3. Choose a cell in the Variant Matrix to apply that combination to the instance.

You can also change a variant property from the selected instance’s Component section in the Inspector. The active cell and Inspector values reflect the same instance choice.

Recover from a variable or variant problem

• If New variable creates a collection instead, finish naming that first collection, then choose New variable again.
• If a value is ignored, check that it matches the variable type and is not blank.
• If Bind does nothing, select a compatible unlocked layer and use a variable type that matches the destination property.
• If the Variant Matrix says there is no eligible selection, select one main component or one instance, not a plain layer or multi-selection.
• If a cell cannot be selected, make sure an editable instance is selected. Edit property definitions on the main component.
• Choose Undo after an unwanted collection, mode, value, binding, or variant-property change.

Current limitations

• New variable currently creates color variables. Number, string, and boolean variables already present in a file can be viewed and edited, but this panel does not yet provide a type picker for creating them.
• The Variant Matrix previews combinations from the first two properties that have option lists. Additional properties remain editable in the properties list and Inspector.
• Adding variant properties does not automatically draw a separate main component for every combination.
• Variable aliases can be displayed, but alias values are not edited inline in the current Variables tab.