Figma components that survive updates: variants, auto layout and tokens

## Quick answer

A durable Figma component has a clear contract: defined states, predictable sizing, named properties and content that can grow. Variants alone do not make a system stable if auto layout, text limits and token roles are left implicit.

Before publishing a component, test the longest realistic label, the empty state, focus or disabled state and a layout change. Those cases reveal more than a polished default frame.

## Why components break down – and why it’s not an accident

Every designer who has worked with Figma for more than a year has gone through this. Open the file after updating the library and half of the layouts are in red icons. The buttons dispersed, the icons flew to default, the cards lost indentations, the text was cut off. Somewhere the instance fell away from the master, somewhere the auto layout collapsed, somewhere the variables ceased to resolve.

And the usual reaction is to fix it with your hands and move on. But if components break down regularly, it’s not a Figma bug. This is a symptom that the system is assembled without considering future changes. Experienced system designers build components so that the upgrade is a predictable event, not a half-day disaster.

Below are the principles that separate a living library from one that everyone is afraid to update.

## The main principle: the component is designed for changes, not for the current layout

Most components break down for one reason: they are made for a specific screen. The designer took a button from the layout, pressed the Create component, and put it in the library. A month later, there was a button with the icon on the right, then loading state, then size S, then danger option. Each addition is a scrap for those who are already using the old version.

Correct Framing: The component is the contract. You promise the team that this element has such-and-such properties, such-and-such states, such-and-such APIs. And when updated, the contract either does not change, or changes backwards-compatible.

### What does "reverse-compatible update" mean

• Properties are not renamed – even if the old name has failed
• Values in variants are not deleted or renamed
• The default values remain the same
• New properties are added with default that repeats old behavior
• Older layers retain the same names - instance with override in text should not fly off

If a contract needs to be broken (and sometimes needs to be broken), it’s a separate event: channel alert, version, migration. Not "I did a little hair on Friday.".

## The structure of the component: what to lay immediately

### Auto layout as a basis, not as decoration

A component without auto layout is a time bomb. Any text editing or icon addition will require manual alignment in all instances. With auto layout correctly configured – the component itself is reassembled.

Checklist for auto layout within the component:

• All containers have explicit resizing (Fill / Hug / Fixed) – not by chance
• Padding is defined by spacing variables, not magic numbers
• Min-width/max-width is placed where the component may not stretch properly
• Text layers – Fill container in width, Hug in height (for most cases)
• Icons - fixed size, Hug container around

### The layers are called as in the code, not as it should be

Frame ২৪৭, Rectangle 12, button copy 3 are all leaking chaos into the library. When a developer opens a component in Dev Mode, or when an MCP agent reads a structure, the layer names become names in the code or links in the hints. Garbage names = garbage withdrawal.

Minimum hygiene of names:

• The root frame coincides with the name of the component
• Containers: container, content, leading, trailing, label
• Text layers: title, description, not Text or Заголовок 1
• The icons are icon-leading, icon-trailing, not vector 28

These names also stabilize overrides. If the layer has the name label, and the user has changed the text in it, then when updating the master override will stick to the layer with the same name. Renamed the layer in the new version - override flew.

## Anti-pattern: One component for all occasions

The temptation is clear: make one universal card with twenty boolean properties - show image, show badge, show footer, show secondary action, show divider, has hover. It's flexible on paper. In practice, each instance looks unique, and updating such a monster hurts: any edit touches a dozen combinations that you do not hold in your head.

Signs that it is time to cut the component:

• More than 6-8 boolean properties
• Variants combinatorially explode (4 size × 3 type × 2 state × icon = 48 variants of which 6 are actually used)
• There are layers inside the component, which are half the time hidden
• No one remembers how to turn on the correct view

The solution is composition. Basic Card without extra, individual slot components (CardHeader, CardMedia, CardFooter) that are collected into specific patterns at the page level or pattern libraries.

## Workflow: how to update the component and not knock the team off track

Updating a component is not a “save wizard” action. It's a small release. The release has preparation, verification and announcement. If a team lives at least three or four products in one library, “quick fix” turns into dozens of overrides and angry messages in the chat.

### Cycle of change: six steps

1. **Describe the intention in words. What changes, why, whose script it closes. If it is not possible to formulate in one sentence - the change is raw, early.
2. ** Check existing instances.** Find instances in Figma, or run through the main layouts. How many places are affected, what overrides are there, what variants are there.
3. ** Make a change in the branch. ** Not in the main library file. A branch is a staging where you can break without crashing the product.
4. ** Run on real layouts.** Substitute one or two pages for a new version, see what happened to overrides, leaut, auto sizes.
5. **Announcement and publication. ** To the command channel - what changes, what is backwards compatible, what requires migration, whether there is a deprecated branch.
6. ** Measurement of consequences.** A day or two passed through the products: where it was normal, where developers complained, where there were "strange" instances.

The fifth step is often missed. And it is because of it that the design system ceases to be treated as a product.

### Versioning without formal SemVer

Full SemVer for a library in Figma is usually too much. Three categories of changes that you honestly put in the description of the publication are enough:

• patch - visual editing, does not touch the API: moved by 1 pixel, corrected the shadow, replaced the icon with an equivalent
• new properties, new variants, new states; everything old works as it was
• major - breaking: renaming properties, removing variants, changing defaults, restructuring the structure of layers

major isn't done quietly. Never.

## Diagnosis: how to know if the component has already rotted

Symptoms can be seen with the naked eye if you know where to look. The review run takes twenty minutes.

### Signs of a rotting component

• In Assets is Button, Button new, Button v2, Button-final – no one remembers which one is actually used
• On the Components page, the master hangs more than a dozen detached copies around - so he is regularly "disassembled" because it is uncomfortable
• Variants have grown to forty to fifty, but there are six in the product
• Every second use is from overrides to size, indentation, color; the component is no longer the source of truth
• Developers have implemented their component in code and ignore layouts – the loudest signal

### Quick audit of the library

Once in a sprint two go through the library with this list:

• Each component has a description – what it is and when to use it
• No duplicates with similar names
• All published components are actually used (Library analytics or manual search)
• The names of variants are consistent: size=sm/md/lg, not size=small in one and size=L in the other
• Colors and indentations inside - through variables, not hard code
• Documented which components are deprecated and what are replaced

## Common Mistakes That Break Case

### Renaming layers for the sake of order

Friday’s refactoring of names within the component is a major source of silent disasters. All overrides on text, fill, visibility are tied to layer names. Switched label to Label and dozens of instances in products lost their text. If you really want to restore order - do it with one release, major, with a warning.

### Remove variant instead of deprecation

In the component there is type=ghost, which is no longer “by guides”. The temptation is to remove. Reality – the instance that stood on it, will turn into red plaques missing. Right: leave the option, in Description mark deprecated, through a sprint-two when the products moved, remove.

### Hidden layers instead of boolean property

The layer is simply hidden by the eye – it’s not part of the component API. The user will not know that it can be turned on. Any state that is actually used should be a property with an understandable name, not “if you look closely, the wizard has the divider turned off.”.

### Variables past collections

He scattered spacing tokens in different collections because “it happened.” When you change a theme or breakpoint, half of the components do not switch. Before publishing, run the component in all modes you have: light/dark, desktop/mobile, brand A/brand B.

## How to apply this in a real layout

The designer is comfortable thinking on two levels: the page level (product layout) and the system level (library). There must be a border between them.

At the layout level, you collect the screen from ready-made instances, make overrides only for content (texts, images, visibility of optional parts). No "move the indentation to 4", "change background color to similar", "turn off auto layout to fit in". If you want to do this, it is a signal that the component lacks a property or pattern, and it must be conveyed to the system.

At the system level, you don't think about a specific screen. You think about the contract: what scenarios this component closes, what properties are needed, how it behaves in extreme cases (long text, no icon, two lines, RTL).

### Questions for pre-publication review of the component

• What happens if the text inside becomes three times longer?
• What happens if the content is empty?
• How does a component behave at minimum and maximum container width?
• Are all states (default, hover, focus, disabled, loading, error) described?
• Do property names match what developers call it?
• Is there a description and example of use in the description?
• What will break the existing instance after publication?

The last question is the main one. If the answer is “don’t know,” go back to step 2 of the update cycle.

## Segment summary

The component lives longer than the layout in which it was born. Therefore, the rules of the game are not “beautifully collected”, but “not broken by those who already use”. Auto layout as a foundation, meaningful layer names, explicit API through properties, backward-compatible updates, release with an announcement and audit once in a sprint. Everything else is derivative.

## When AI and MCP come into play

AI assistants in and out of Figma aren’t a “magic button to make beautiful,” but another user of your library. If the components are assembled normally, the AI receives a clear contract: variant names, descriptions, states – and assembles a layout from them. If the components are a bag of hardcode frames, the AI will start inventing its own buttons next to yours, and five “primary buttons” of varying degrees of similarity will appear in the layout.

### What Changes When You Connect an AI/MCP Agent

• The description of the component ceases to be “someday write”. This is an instruction that not only the new designer reads, but also the model: what it is, when to use, how it differs from the neighbor.
• Properties are no longer an internal joke. state=hover/active/pressed is clear to everyone. state=foo/bar is guaranteed garbage at the exit.
• Variants with the same meaning, but different names (size=md and Size=Medium in neighboring components) AI mixes in an arbitrary order. The consistency of naming becomes not a matter of taste, but a matter of generation quality.
• All the “unofficial” components in the file — drafts, experiments, old versions — are legitimate. Either take it to a separate _drafts page or delete it.

### Anti-patterns when working with AI

• Connect the MCP to a project that has half the hardcode variables and wait for the model to figure it out. I don't know. First cleaning the library, then automation.
• Generate the screen with the assistant and publish new components directly from it. Frame 482, Button copy 3 will appear in the library, and in a week someone will buy them in the product.
• Entrust AI with editing existing components without review. Any change to the wizard = a potential broken instance in dozens of files.

The rule is simple: AI speeds up the assembly of layouts from the finished system, but should not silently change the system itself.

## Team context: how to negotiate

Components break not from bad tools, but from the fact that three designers and frontenders have different understandings of what a “button” is.

### Minimum set of arrangements

• Who owns the library. One person or a small circle, without which the master does not change.
• Where changelog lives. This can be a page in Figma, a channel in Slack, a page in Notion – the main thing is that a release without a record in changelog is not considered a release.
• What properties are called. Agree once: size, variant, state, icon. Not type, kind, style mixed.
• As marked deprecated. A prefix in the name, an emoji tag, a separate section — anything but uniform.
• What is considered breaking change? Removing variant, renaming property, removing layer from overrides – all this requires an announcement.

### How to explain the decision to the team

Designers and products don’t like to hear, “You can’t do this, it will break the library.” That sounds like a whim. Another wording works: show the price.

• "If I rename the layer now, we'll have text in buttons in three products." Fixing is a day of work. Let's do it in the next major release along with the rest of the edits
• “This version of the button is used on checkout. If removed, payments will have missing components. Label deprecated, sprint out
• The property is called kind because developers have it in their code. If we change the name to type, it will cease to match the code and in manual development will begin to confuse

The argument in terms of “break this product” works better than “this is against the guides.”.

## How to check the quality of the system

Once in a sprint two, it is useful to do a short audit - not a global redesign, but hygiene.

### Sprint audit checklist

• Read more about Library Analytics: Are there zero-use components per quarter?
• I opened 3-5 product files: how many detached instances? If so, what is missing in the system?
• Checked that all published components switch between all variable modes without visual surprises.
• I went through the deprecated list: what can I delete?
• Compared property names between similar components (button, icon button, link) – is the same name?
• Descriptions of new components in place?

### Questions for a review before merge library

• What instances in product files will change after publication?
• Is that breaking change? If so, where's the announcement?
• Did artifacts (frame copy, hidden layers, local styles instead of variables) appear in the file?
• What is deprecated and when is it removed?
• If connected, will AI/MCP tools see a consistent picture?

## Short summary

Advanced component work is less about Figma and more about communication: with the future self, with the team, with the model that will read your library. Descriptions, names, changelogs, deprecations are boring things that save you weeks trying to figure out why the button went on sale. If the system can withstand AI-assembly, moving between topics and a new designer without a brief – it will withstand a normal working day.

## Anti-patterns that break the library slowly

The most dangerous bugs in the components are not the ones that drop the file today, but the ones that turn the system into a landfill in six months. They're not visible on one PR, but they're visible when a new designer comes in and says, "I don't know which button to take." Below is a list of patterns that should be caught on the review before they take root.

### Matryoshka component

One component contains another, which contains a third, and each with its own variants. On paper, powerful. In practice, instance in a product has 14 properties, half of which do not work in the current combination. If there are more than two layers of nesting, ask yourself whether this is overuse or just a fear of duplication.

### Lifetime button

Variants: primary, secondary, ghost, link, text, outline, tonal, subtle, flat. After six months, no one remembers how ghost differs from subtle. A sign of trouble is when the team at the review is asked: "What button is this?" and the answer requires the wizard to open.

### The layer that holds the entire component

In the wizard there is a layer of bg, without which the auto layout falls, padding breaks and radius is lost. No one knows until someone hides him in overrides. If a component has a “magic” layer, it is a tech debt, not a feature.

### Properties that do nothing

isLoading, hasIcon, showBadge – added “for the future”, but visually do not change anything. The review looks harmless, in the product - generates false expectations: the designer checks the box, the spinner is waiting, and he is not.

### Local styles "only in this file"

"I'll paint the header here with a local fill, then put it into the system." We won't. In a month, this will be in the screenshot for development, and in another month - in the product.

### Quiet renaming

Property variant has been renamed kind because it’s “more understandable.” Published. In three product files, overrides defaulted. Any renaming of a property or variant is a breaking change, even if the letter is one.

## Checklist before publication of the component

• The name corresponds to the convention of the team, without copy, new, v2.
• All properties actually affect visual or behavior.
• Auto layout does not depend on the hidden "magic" layer.
• The component is tested in all variable modes that the system supports.
• The description is filled: for what, where to use, what to avoid.
• There are no local styles, only tokens/variables.
• If it's a replacement for an existing one, the old one is deprecated, not deleted.
• Changelog has a record marked breaking/non-breaking.

## Questions to Ask at a Review

• If this component gets to the new designer without a brief, will he be able to assemble a typical screen from it?
• What happens to instances in product files after publication—specifically, which ones?
• What is the most incomprehensible property here and can it be removed or renamed now, while no one uses it?
• If tomorrow the theme changes (dark, brand, dense), what will break first?
• Is there something in this release that the frontend needs to know so as not to part with the code?
• What do we deprecate with this release and when will we finally delete it?

## One-line summation

Components do not break with updates – they break from unlived solutions: unnamed layers, superfluous properties, quiet renaming and “temporary” local styles. Discipline in small things - descriptions, single names, explicit deprecation, transparent review - is cheaper than one analysis of why the button left for sale.

## FAQ

How many variants should a component have? Only the states the product can explain and support. Extra variants create naming and maintenance cost.

Why does auto layout break after updates? Usually because sizing, constraints or nested content assumptions were not defined.

What should be documented for developers? Properties, states, tokens, responsive behaviour and a small set of approved examples.

### What to read next

• Figma, Claude Code and React: a traceable design system
• WCAG 3 and AI-generated interfaces
• Figma and layouts