In a previous post I wrote about how I organise Figma for a small design team. One thing I deliberately left out was component lifecycle - specifically, what to do when a component needs to change in a significant way.
This isn't about tweaks. Changing a button's corner radius or updating a colour token - that's just maintenance, and Figma handles it cleanly. What I'm talking about is when a component changes so fundamentally that the old version and the new version can't really coexist under the same name. A button that gains a new structure, new props, new variants. A card that gets rebuilt from scratch to support a new layout system.
When is something actually deprecated?
This is the question worth sitting with before reaching for a solution. Not every significant change warrants deprecation - sometimes you genuinely can update a component in place and push the change out across the board.
A good rule of thumb: if updating the component would break or meaningfully change existing designs that are still correct, it's a deprecation. If it just improves things uniformly, it's an update.
One thing worth noting before getting into examples: what counts as a deprecation from a design perspective doesn't necessarily mean the same thing for development. Developers may be able to update the underlying component in code without it being a breaking change on their end. That's fine - but it's still worth raising with them early. They may have context that changes how you approach the rollout, and a conversation upfront avoids surprises later.
A few examples of when I'd consider something deprecated:
- A button component gains an icon slot and restructures its internal layout - technically the existing instances shouldn't break, but you can't check every usage across every file. A designer may have detached it, tweaked it, or built something around it in a way that causes unexpected side effects when the component updates. When you can't be confident, deprecating is the safer option.
- A form input is rebuilt to align with a new design language, changing its visual appearance significantly
- A card component splits into multiple variants that don't map cleanly onto the old single component
In each case, the old version still reflects a valid design decision at the time. You're not correcting a mistake - you're moving forward. That distinction matters, because it shapes how you treat old instances.
The naming convention
The simplest and most effective thing you can do is rename the old component with a [deprecated] suffix. So Button becomes Button [deprecated], and the new component takes the clean name Button.
This sounds small but the effect is immediate and useful. Figma propagates the name change across every file that uses the library - so any designer opening an older exploration file or a shipped spec will see Button [deprecated] on their canvas without you having to touch those files. It's a passive signal that does the work for you.
A few things to keep in mind:
- Keep the deprecated component exactly as it was. Don't modify it once it's been renamed. It needs to stay accurate as a record of what was designed with it.
- The new component gets the clean name with no suffix. It should feel like the obvious, default choice.
- If you have multiple related components being deprecated at once - say, a whole set of form inputs - rename them all in the same session so the changeover is clear and consistent.
Where deprecated components live
Don't delete them. Removing a component from the library breaks every instance that hasn't been updated yet, which can cause quiet chaos across working and handoff files.
Instead, move deprecated components to a dedicated space within the design system file. Two approaches work well:
A Deprecated page - a separate page in the file that acts as a holding area. Clean, obvious, easy to find if someone needs to reference it.
A section divider - Figma's --- separator in the pages panel lets you create a pseudo-section. So you can move the entire page down into here.
Either way, the goal is the same: out of the way, but not gone.
Rolling out the new component
It's worth noting that the new component often doesn't start life in the design system. A common workflow is to extend or adapt an existing component inside your working file as part of designing new work - getting it right in context first, then taking it back to the design system once you're confident. At that point you'd deprecate the old one and publish the new version.
The thing to be aware of: once it's published, it's available to everyone. Another designer might pick it up for a completely separate project before the work it was originally designed for has even shipped. That's not necessarily a problem, but it's worth keeping in mind - especially if the component was shaped by specific design decisions that might not hold in other contexts.
From there, you'll want to start rolling it out across active files. Figma lets you accept library updates per page rather than per file, and I strongly prefer doing it that way.
Updating an entire file at once risks silently changing designs that were correct at the time - old explorations, approved specs, shipped screens that you might need to refer back to. Updating page by page means you're making a conscious decision about what gets migrated, rather than a blanket sweep.
In practice this means:
- Update pages in the handoff file where work is active or in development
- In working files - as covered in the Figma organisation post - multiple designers are likely sharing the same file. You won't always have the full picture of how something was built or intended on someone else's page. Only update your own pages, and leave the library update warning on pages you don't own. Let those designers choose whether and when to update on their own terms.
- Leave old exploration pages as they were - they're a record, not a live document
- Don't feel pressure to migrate everything immediately. The deprecated component will keep working; the name change is enough to signal intent
Communicating it to the team
Even on a small team, a silent deprecation is a bad deprecation. When you rename and publish, take thirty seconds to let people know - a Slack message or a quick mention in standup is enough. Something like: "I've deprecated the old Button component and published a new version - update pages as you work on them, no rush to migrate everything at once."
The name change handles the passive signalling. The heads-up handles the human side.
The end state
Over time, as active files get updated page by page, the deprecated component quietly fades out of use. At some point - usually when you're confident nothing active is referencing it - you can remove it from the library entirely. There's no fixed timeline for this; it depends on the pace of your team and how much old work is still being actively referenced.
The key thing is that you never have to do a big, disruptive migration all at once. The [deprecated] suffix keeps things honest in the meantime, and the new component earns adoption gradually through the normal flow of work.
When you do eventually delete it, any remaining instances will lose their component link - Figma will show a small "component not found" indicator, but the frame itself stays intact. Nothing breaks visually. It's a clean end to the lifecycle.