Extend a variable collection – Figma Learn - Help Center

Before you Start

Who can use this feature

Anyone with can edit access to a file can extend a variable collection

Extended collections help you manage multi-brand design systems. With extended collections, design systems authors can create a parent collection, then extend it to create an instance for each brand. Designers can then override variables within the extended collection to match their brand-specific themes.

An extended collection is tied to its parent collection and will inherit updates made to any variables that have not been explicitly overridden. This allows the extended collection to stay up-to-date with the parent collection, while maintaining brand colors and values.

Note: We're gradually rolling out this feature over the next two weeks. If it isn't available in your account yet, it will be shortly.

You can migrate your existing variable collections to the new extended collection format. The migration workflow you use depends on how you’ve organized your brand themes:

Single collection: All brand themes live in one collection
Multi-collection: Brand themes are spread across multiple collections

Note: To prevent performance issues, we recommend performing the migration workflow directly on your main branch, rather than creating a separate branch.

Single collection migration workflow

If you organize your brand themes in a single collection, you can use the following workflow to migrate them to the extended collection format.

Step 1: Export and delete brand-specific modes

Open the Variables modal, then select the collection you want to extend.
Select a brand mode from your list of modes, then right-click on it and choose Export mode. The variables will be exported to a JSON file.
Once exported, right-click on the mode again and select Delete mode.
Repeat this process for each brand mode until just the parent collection’s modes remain.

Step 2: Create an extended collection for each brand

Select the parent collection from your list of collections, then right-click on it and choose Extend collection.
Double-click on the extended collection to rename it.
Repeat this process for each brand.

Step 3: Import your brand modes to their extended collection

Open an extended collection.
Select a mode column, then right-click on it and choose Import mode. Select the corresponding JSON file to import over the existing values.

Any values that differ from the parent collection are highlighted in blue. Click on a variable to modify its value, or click Reset change to revert the override back to the parent collection’s values.

Note: An extended collection’s mode and variable names, settings, and order are inherited from the parent collection. You cannot add additional variables or modes, or change a variable’s description or scope from an extended collection. Open the parent collection to modify these settings.

Step 4: Publish library updates and reapply modes

Once your extended collections are configured, you’ll need to publish the library updates to make these changes available in other files.

Accepting the library updates will remove any previously set variable modes from your designs. You will need to reapply your variable modes again using the new extended collection.

Multi-collection migration workflow

If your brand themes are organized in individual collections, you can use the following workflow to migrate them to the extended collection format.

Step 1: Export all modes from brand-specific collections

Open the variables modal, then select a brand collection.
Right-click on each mode and choose Export mode. The variables will be exported to a JSON file.
Repeat this process for each mode.

Step 2: Create a new extended collection for each brand

Choose a collection to be used as the parent collection, then right-click on it and select Extend collection.
Double-click on the extended collection to rename it.
Repeat this process for each brand.

Step 3: Import your brand modes to their extended collection

Open the extended collection.
Select a mode column, then right-click on it and choose Import mode. Select the corresponding JSON file to import over the existing mode.

Step 4: Update the original brand collection

To prevent designers from accidentally using the original collection, do the following:

First, delete each mode in the brand collection except the original mode:

Open the original collection
Right-click on each mode except the first, then choose Delete mode.

Then, create an alias for each variable in the original collection that references the parent collection. Learn more about aliasing variables.

Finally, deselect the Show in all supported properties checkbox on the Scope tab of the variable settings. Learn more about scoping variables.

Step 5: Publish library updates and reapply modes

Once your extended collections are configured, you’ll need to publish the library updates to make these changes available in all consuming files.

Accepting the library updates will remove any previously set variable modes from your designs. You will need to reapply your variable modes again using the new extended collection format.