Selino V
Full-stack Product Designer

Deprecating Components in my Design System

How I decommission design components in the Clariture Health 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 UI Kit need to be replaced or destroyed, which can be a messy business when those designs are embedded in hundreds of layouts in hundreds of files across the Design System.

Deleting it from the source library can break changes and agitate 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? Sometimes I can remove an item without swapping it out, or it's already swapped. Those are rare but easy wins.

Version Everything

Whether my design tool has semantic versioning built into it or not, I'm thinking about 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. Tools, culture, and history will shape how I 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 involve developing tools and processes that can get super complex. That's the point of creating a system to help stay on track.

Process

Laying Down the Foundation

No amount of process can succeed if the foundation is not up to the task. Therefore, I needed to use a modular approach to create an environment that enables us to remove design assets nested within countless files safely.

  • 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, but a good foundational practice has reduced the number of 🔥.

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

I use a daily Scrum at Clariture Health 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 has already invested in using a channel-based messaging platform. For example, I use Slack.

Most large-scale issue trackers like Jira allow you to organize using tags, watchers, etc. For example, I create tickets for deprecating items and update them with the appropriate people tagged so that the system automatically alerts when a deprecation order's status 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, which isolates risk away from stakeholders. Still, I must motivate them to divest from the old component.

I can start easing everyone into change by sending a status update explaining that deprecation is underway and marking the original component with an indicator. Then, 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, preventing accidental modifications from being pushed out and breaking things. In addition, building and testing in parallel avoid issues before they occur. For example, you can’t break a layout if you don’t touch anything.

Push the New Version Silently

When refactoring an existing component, I'll typically leave the original in place and work on a clone, which prevents accidental modifications from being pushed out and breaking things still linked to the target. In addition, building and testing in parallel avoid issues before they occur. For example, you can't break a layout if you don't touch anything.

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

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 kept documentation changes throughout the process. Docs can be in the ticketing system, a private notes app, or a team doc app like Notion or Craft. IRL, I usually set aside time toward the tail end to gather my thoughts, find all the corner cases, and document everything.

MDX for Guidelines

One of the stated goals is to simplify the process for efficiency. Examples include docs written and stored alongside the developer implementation docs. In addition, using the native MDX format in Storybook allows for code, inline images, and standard markup.

Move everyone to the new component

At this point, I have a target component marked as “pending” for some time, a series of verbal and written communications of changes coming, and now it’s time to try to get everyone using the new component exclusively actively. This process 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 nudge over time gently.

There will also likely be instances of the target component within files that no longer have an owner floating around for months. But, again, depending on the organization, they will be ignored, changed, or archived as required.

An Example of Forced Archival

An Example of Forced Archival

Decommission the Relic

When possible, I will visibly mark the target component so that all instances are propagated throughout the system. This is the last motivation for stragglers as they witness their designs display glaring deprecation marks. Again, nothing is "missing." I have not deleted any components. I've made a new one and modified the target as little as possible.

Zombie Relics

Some teams have deprecated components to living forever on a page dedicated as a "graveyard." I 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 quickly bloat the UIKits within a design system. My personal view is to prune unused items regularly and often by removing access to them altogether. Instead, I can copy the target to a dedicated file with a semantic naming convention, which keeps your living library files as lean and efficient as possible.