This is what a Sr Product Designer looks like when her DesOps team pushes breaking changes.
Deprecating Components in a Design System
How I decommission design components in the LeadGen Design System
Sometimes components in a UKit need to be replaced or destroyed. This can be a messy business when those designs have been imbedded in hundreds of layouts in hundreds of files across the Design System.
Simply deleting it from the source library can result in breaking changes and very agitated product designers.
Before I go in and change anything I like to take an informal/formal audit of the target component. Where is it being used, who is using it, and should it be touched at all? Sometimes an item can be removed without being replaced or it's already been replaced. Those are rare but easy wins!
Regardless of whether my design tool has semantic versioning built into it or not, I'm thinking in terms of versioning. It's a matter of "when" not "if" I will need to recover an older version. Just like engineering teams, design teams can archive rather than delete.
Adapt to the Organization
There's rarely a "one size fits all" solution to any process. This document details how I handle things at the moment but it will likely evolve and may not work for your team at all. Tools, culture, and history will shape how we approach deprecation.
All of this is hard
I'm oversimplifying these concepts for the sake of this case study but make no mistake, putting all of this into practice is work. Auditing, versioning, and adapting involves developing tools and processes that can get super complex. That's the point of developing a system to help stay on track.
Laying Down the Foundation
No amount of process can succeed if the foundation is not up to the task. In order to create an environment that enables us to safely remove design assets that are nested within countless files we needed to make sure to use a modular approach.
Use atomic design to create modular components
Create separate libraries for tokens (aka particles), the brand and platform UIKits, and individual project files
Use plugins but make sure their output is not proprietary (the file can open cleanly without the plugin)
Be consistent in naming, nesting, etc
None of this will prevent mistakes from happening but good foundational practice has reduced the number of fires. 🔥
Communicate Pending Changes
At Clariture we use a daily Scrum to keep ourselves in a collaborative state. Simply informing others before I push out any changes wins friends all around.
A dedicated channel can also work well if the team already invested in using channel based messaging platform. We use Slack at Clariture Health.
Most large scale issue trackers like Jira allow you to organize using tags, watchers, etc. I create tickets for deprecating items and keep them updated with the appropriate people tagged so that the system alerts automatically when the status of a deprecation order has changed.
Mark as In Progress
So far I’ve told the team what I’m going to do and started making my replacement component without touching any existing components. This has isolated risk away from stakeholders but we need to also start motivating them to divest in the old component.
By sending out a status update explaining that deprecation has been initiated and marking the original component with an indicator we can start easing everyone into change. Give stakeholders time to adapt their work at a pace that accommodates them.
Modify in Isolation
When refactoring or replacing an existing component I’ll typically leave the original in place and work on a “clone”. This prevents any accidental modifications from being pushed out and breaking things. Building and testing in parallel avoids issues before they can occur. You can’t break a layout if you don’t touch anything in it.
Push the New Version Silently
When refactoring an existing component I’ll typically leave the original in place and work on a “clone”. This prevents any accidental modifications from being pushed out and breaking things still linked to the target. Building and testing in parallel avoids issues before they can occur. You can’t break a layout if you don’t touch anything in it.
In a perfect world I would have been keeping documentation changes during the entire process. This could be in the ticketing system, a private notes app, or a team doc app like Notion or Craft. IRL I usually end up setting aside time toward the tail end to gather my thoughts, find all the corner cases, and document it all.
MDX for Guidelines
One of the stated goals is to simplify process for the sake of efficiency. This includes docs written and stored alongside the developer implementation docs. Using the native MDX format in Storybook allows for real code, inline images, and common markup.
Move everyone to the new component
At this point we have a target component that’s been marked as “pending” for some time, a series of verbal and written communications of changes coming, and now it’s time to actively try to get everyone using the new component exclusively. This can take a long time but that’s okay. Unless there’s a given imperative to force change across everyone’s design files, I found it best to gently nudge over time.
It’s also likely that there will be instances of the target component within files that no longer have an owner, floating around for months. Depending on the organization type, those will need to be ignored, changed, or archived as needed.
Decommission the Relic
There's a point when you have to move forward and finalize the deprecation. When it's possible we will visibly mark the target component so that all instances are clearly marked throughout the system. This is the last motivation for stragglers as they witness their designs display glaring deprecation marks. Again, nothing is “missing”. We have not deleted any components. We’ve made a new one and modified the target as little as possible.
Some teams allow deprecated components to live forever on a page dedicated as a “graveyard”. We can append the name with a version number and leave it to roam the design system for all eternity… lurking. 🧟♀️
Design files usually have size limits and an ever growing list of deprecated items can easily bloat the UIKits within a design system. My personal view is to prune unused items regularly and often by removing access to them altogether. We can copy the target to a dedicated file with a semantic naming convention. This keeps your living library files as lean and efficient as possible.