When designing UI with a design system in Figma, most designers have probably experienced this at least once: After carefully refining the design, changing a single Component Property may cause everything to revert to the component's default state. When Overrides are lost after modifying an Instance's properties, designers must manually restore their work, and important changes can even be lost during handoff, leading to unexpected communication issues.
Although this problem can occur even in relatively simple components such as buttons, it becomes much more common in complex components composed of multiple nested Instances. To improve design efficiency, Components should be designed so that Overrides are preserved whenever possible. So how can we design complex Components that maintain stable Overrides?
Conditions for Preserving Overrides
Before looking at Override behavior in complex Components, let's first review how Figma officially describes Override preservation. In the official Figma documentation, Overrides are preserved when changing a Component Property on an Instance so that it references a different Variant:
- The layer names of the current instance and the variant or instance you’re selecting must match. This applies both when swapping instances and selecting variants.
- When selecting variants, Figma also checks if the layer properties you’ve changed originally matched between variants. If so, Figma will preserve your changes.
Let's see how these conditions apply using a simple Button Component. Starting with the Plain variant, change the button text to "Override", then change both the icon color and the text color to Cyan. When the Variant is switched from Plain to Critical, the Override applied to the icon is preserved, while the Override applied to the text is not.
For the icon, the original layer properties are identical between the Plain and Critical Variants, so the Override is preserved. For text, however, Figma uses the displayed string as the text layer name unless the layer is renamed manually. Because the two Variants contain different strings and the text layers were not given explicit names, their layer names also differ between the Variants. As a result, after changing the Property, the Override is not preserved, and both the text content and its color are reset to the values defined by the Critical Variant.
These general rules work well for relatively simple Components such as buttons. However, as a Component becomes more complex and contains multiple nested Instances, Overrides become much more likely to behave differently from what designers expect.
To understand why, we first need to understand how these general rules are applied when nested Instances are involved.
Instance identity across Component boundaries
A nested Instance inside a Component behaves differently from other layers. Unlike a regular layer such as a Frame or a Vector, it references a separate Component and, more specifically, a particular Variant of that separate Component.
This behavior becomes apparent when a Component containing nested Instances is itself used as an Instance. Although the documentation does not explicitly mention nested Instances, my testing suggests that the same layer property checks also apply to them. As a result, two nested Instances that appear identical may preserve Overrides differently if they reference different Variants.
In other words, once a Component references another Component through an Instance, determining whether two objects are considered "the same" becomes more complex than it is for ordinary layers. Based on my observations, Figma appears to determine whether an Instance is considered the same based on the following three factors.
Factor 1: Properties
In Figma, every unique combination of Properties identifies a specific Variant. Even if two Instances reference the same Component, they are considered different if they reference different Variants.
This difference does not matter unless the nested Instance has been overridden. However, once the nested Instance has been overridden — either in the Component itself or in an Instance of that Component — changing the Component's Properties may cause the Override to be discarded and reset to the nested Instance defined by the target Variant.
This issue is particularly noticeable when the nested Instance contains a text layer. Designers who build a Group–Item hierarchy using the same design approach as for simple Components often encounter the following situation: every time the Group Instance changes size or switches to an error state, every overridden label is reset to the default text defined by the Item Component.
- If a RadioGroup contains RadioOption Instances and each RadioOption contains a RadioButton Instance, the Overrides applied to the text are preserved as expected.
- If a RadioGroup contains RadioOption Instances without a nested Instance and the Label is exposed as a Text Property, the Overrides applied to the text are also preserved as expected.
- If a RadioGroup contains RadioOption Instances without a nested Instance and the Label is not exposed as a Text Property, the Overrides applied to the text are unexpectedly reset.
Factor 2: A single consistently named layer
This corresponds to one of Figma's official conditions for preserving Overrides. However, when Instances are involved, satisfying this condition requires more than maintaining consistent layer names within a single Component. Components that are intended to replace one another must also share a single consistently named layer across their Variants.
For example, only then can Figma recognize that an Icon Component referenced across a Component boundary has merely changed its shape rather than becoming a completely different object.
If those Variants or Components use inconsistent layer names or structures, switching an icon inside a Button may unexpectedly reset the icon color to black instead of preserving the color Override defined by the Button.
- When each Icon Component contains a single vector layer with the same name, the color Override is preserved.
- When each Icon Component contains a single vector layer but the layer names differ, the color Override is not preserved.
- When an Icon Component contains multiple vector layers, the color Overrides are not preserved. The exception is when every vector layer in the target nested Instance can be matched to a vector layer with the same name in the current nested Instance.
- When the Icon Component contains a separate color layer in addition to its vector layers, the color Override is preserved.
Factor 3: Parent–child relationships
For objects directly contained in a Component, Overrides are preserved as long as Figma can identify corresponding layers by name, regardless of where those layers appear in each Variant.
However, once an element such as a Vector or a Button Instance belongs to a specific nested Instance, the element's parent Instance also becomes part of the object's identity. Even if two layers have identical names, Overrides cannot be preserved if they belong to different nested Instances across Variants.
For example, to preserve the Override applied to "Button A" inside "Layout A", "Button A" must remain inside "Layout A" in every Variant.
This limitation becomes particularly noticeable when building responsive layout Components. Because Auto Layout direction cannot be changed on an Instance, designers should create and use dedicated layout Components for different responsive layouts. As Components become more complex, the desired layout may need to move across the boundaries of these layout Components. However, Figma's Override matching stops at those Instance boundaries.
- When an element remains under the same nested Instance across Variants, the Overrides are preserved.
- When an element belongs to different nested Instances across Variants, the Overrides are not preserved.
Designing Complex Components for Stable Overrides
To preserve Overrides even after changing the Properties of a Component Instance, Components should be designed so that corresponding nested Instances are recognized as the same object across every Variant. The following design principles help achieve that goal.
Keep the same Property combinations across all Variants
Figma distinguishes nested Instances based on their Property combinations. If the Properties differ, Figma treats them as different objects. If they are identical, Figma treats them as the same object.
Therefore, nested Instances that are expected to preserve Overrides should reference the same Property combination in every Variant of the Component.
If different Property combinations are unavoidable, redesign the referenced Component so that the parts requiring different Properties are extracted into referenced Components, while the referenced Component itself remains a single-variant Component.
Manage text at the Component level rather than the Variant level
Text Overrides can be preserved in another way: Expose the text as a Text Property.
When a text layer is linked to a Text Property, its value is managed at the Component level rather than by the individual Variant. As a result, the text remains unchanged regardless of Property changes, as long as the nested Instance itself is not replaced.
Share a single consistently named layer
Overrides are preserved more reliably when interchangeable Components share a single consistently named layer across all of their Variants.
For icon Components, this means creating a consistently named parent layer and placing the actual vector artwork beneath it.
This consistent layer can be implemented in several ways. For example, you can combine all vectors into a single Union layer and give that Union the same name across every icon. Alternatively, you can create a color layer and mask it with a group containing the icon vectors.
Detach nested Instances to access individual elements directly
For Components that contain layout Instances whose child elements appear in different positions, it can be advantageous to detach the layout Instance so that the Component can directly identify each element by its layer name.
One trade-off is that Properties which cannot be replaced with Variables are lost when an Instance is detached. These values should therefore be documented separately so they can still be referenced during development.
In my own workflow, I found that preset Components built from detached layout Instances allowed Overrides to be preserved while freely switching between presets and responsive layouts. This significantly reduced the amount of repetitive rework required for each layout or viewport, resulting in a more efficient design workflow.