Selino V
UI Design + Development

Deprecating Components in a Design System

How I decommission design components in the LeadGen Design System

Image alt tag
This is what a Sr Product Designer looks like when her DesOps team pushes breaking changes.

This is what a Sr Product Designer looks like when her DesOps team pushes breaking changes.

The Problem

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.

3 Guiding Principles

Audit First

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!

Version Everything

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.

Some sketch notes while I was prepping for this article.

Some sketch notes while I was prepping for this article.

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.

Process
We don't have a Mobile kit yet but that's where it will go.

We don't have a Mobile kit yet but that's where it will go.

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. 🔥

A Scrum, Slack, and Jira bundle is common for staying in communication.

A Scrum, Slack, and Jira bundle is common for staying in communication.

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.

I avoid making

I avoid making "mega-components" with every possible variant. This makes it easier to push things silently and mitigate risk.

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.

MDX uses markdown so there's zero learning curve.

MDX uses markdown so there's zero learning curve.

Update Documentation

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.

An Example of Forced Archival

An Example of Forced Archival

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.

Zombie Relics

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. 🧟‍♀️

Forced Archival

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.