Taking The Stress Out Of Design System Management

In this article, Masha goes over five tips that make it easier to manage a design system while increasing its effectiveness. This short guide is aimed at smaller teams.

As a sole design system maintainer, I try to minimize the time I spend in Slack or meetings and maximize the time I spend in Figma or code (aka, focused and actually working).

For the past four years, I’ve been figuring out how to set up my workflow to achieve that goal. In this article, I want to share what did and didn’t work for me and what you can do to:

  • Stress less about design system management.
  • Reduce noise.
  • Maintain transparency in your process.
  • Minimize disruptions for your team and customers.

Let’s dive right in!

Invest Time To Create A Plan

Unless you are joining a company from the outset, you’re probably not starting a design system from scratch. It’s essential to take the time and analyze what’s there instead of jumping right in and treating it like a blank canvas.

When I joined Karat, we already had two web apps: a customer-facing one and an internal one.

Screenshot of our customer-facing app
The user interface felt visually cluttered, had multiple accessibility issues, and didn’t follow Gestalt principles. (Large preview)

They were both parts of the same repository, which also included a package for our design system (KDS). Some styles and components were coming from the KDS package and were used by both apps. Some were unique to each app and lived in that respective app’s package. Some, however, were duplicated in both apps’ packages (and sometimes the KDS package too).

Illustration showing the state of the codebase
Moving and removing code may not be as exciting as adding new stuff, but it is essential to maintaining a healthy codebase. (Large preview)

In addition to the existing codebase, we had designs in Figma with the new look and feel we wanted to pursue:

Figma design with the new vision
New designs felt much cleaner, calmer, and better organized. (Large preview)

My manager and fellow designer Mark already did the hard job of defining the core elements and patterns through exploring scenarios and flows (Scenario-Driven Design Systems talk by Yesenia Perez-Cruz takes a deep dive in this topic). My task was to take the new vision, create a sustainable component library for both code and Figma, and integrate it into our app. It was also up to me to figure out how to organize and communicate my work.

I spent the first two weeks auditing our apps, our codebase, and our new designs. Investing that time upfront helped me to figure out a logical (given our context) sequence for implementing and rolling out the design system. Later on, it ensured a smoother transition between our old and new interface.

I wrote my tentative plan in our company’s Notion space (here’s a copy of the plan). There are four pages there:

  1. Progress: Universal
    Tracking progress for foundations (colors, typography, breakpoints, and so on) and common components (buttons, inputs, breadcrumbs, accordions, and so on).
  2. Progress: Customer
    Tracking progress for our customer-facing app.
  3. Progress: Internal
    Tracking progress for our internal app.
  4. Other projects
    Tracking smaller projects and ideas for future enhancements.
Three screenshots of the plan. The first screenshot shows a table of contents. The second screenshot shows a table for tracking progress for our customer-facing app. The table includes columns for priority order, a description of what needs to be done, a ticket link to the Linear issue management software, a link to the Figma file or reference, and status. The third screenshot shows progress for universal components. Universal components are divided into sections, and this screenshot shows sections for data display, feedback, and overlay components. Each section has a table that includes columns for the component name, link to that component in the codebase, and link to that component in Figma
This setup might look too bare bones, but that’s intended. The goal is to have a quick summary, not to go into detail. (Large preview)

Allowing anyone at the company to access the plan made it easier to communicate and define what was being done and in what order. It helped to turn the infamous “When is the design system going to be done?” question into a concrete “When will we be able to do ?”, which was possible to answer.

It’s also important to note that I never treated my plan as fixed. I expected priorities to shift, and they did. The plan was just a rough draft, a single place to track progress at a glance. Looking at it this way made it much less intimidating.

More after jump! Continue reading below ↓
Smashing Email Newsletter with useful tips on front-end, design & UX. Subscribe and get “Smart Interface Design Checklists” — a free PDF deck with 150+ questions to ask yourself when designing and building almost anything.

Feature Panel

Post Frequent (Yet Short) Updates

The success of any project is half implementation and half communication. It’s harder for people to support your work and advocate for you if they don’t know what you’re doing.

Let’s Get Specific

Screenshot of our design systems channel in Slack
Our channel is simply called #design-systems and includes members from different teams (design, engineering, customer support, product, operations). (Large preview)
Two screenshots of check-in examples. In the first screenshot, I share an update on the state of our breakpoints and layout components. I also include a small game where I ask members of the channel to look at two designs and pick one that’s correct and follows our system guidelines. (This is a good way to get a pulse on the awareness of the system). In the second screenshot, I share that I started working on updating our loading screens with skeletons and that I’m also working on updating our HTML email templates
Emojis also help add to the context and make the updates more fun. (Large preview)
Two screenshots, showing our customer app before and after the design refresh
Occasional before/afters are the simplest way to illustrate the progress and highlighting everyone’s accomplishments. (Just remember to take screenshots of your product early and often.) (Large preview)

Potential Inhibitors

There are a couple of potential (mostly mental) blockers. Keep them in mind, and don’t let them get in the way!

Short Updates vs. Release Notes

In addition to these short updates, I also used to keep a Notion page with the release notes (an idea I borrowed from Carbon Design System changelog). That page was difficult to maintain, and no one even checked it. For our small team, short updates in Slack accomplished the same goal.

Screenshot of Release Notes page in Notion
Including myself, only three people ever visited the Release Notes page. (Large preview)

Takeaway: Just because a big company is doing something doesn’t mean you need to as well. Of course, it’s always worth testing out new ideas, but don’t be afraid to let them go if they don’t fit in.

Don’t Duplicate Documentation

A big part of design systems is to make sure that designers and developers don’t have to create the same components and styles over and over again.

So, why would we ever duplicate the same information in multiple places? This seems paradoxical, but it’s an easy trap to fall into.

Here’s How It Happens

Teams usually have different tools they use to manage their design or development assets. It’s normal. However, it doesn’t mean that everything should be everywhere. Constantly duplicating information leads to these two problems:

  1. Tons of repetitive work for which you don’t have the time.
  2. Discrepancies between sources which can result in loss of trust.

Here’s What You Can Do Instead

Two screenshots. The first screenshot shows the landing page for our design guide when the password is required: it’s an empty page with just an input field. The second screenshot shows the landing page for our design guide when the password isn’t required. You immediately land on the main page, which has expanded navigation for styles and components on the left and resources for different team members (designers, developers) on the right
Landing page without the password is much more welcoming. (Large preview)
Two screenshots. The first screenshot shows the documentation page for the Layout component, and the second screenshot shows documentation for the Alert component. While components are different, documentation maintains the same format. At the top is the parent group of the component (for example, Alert belongs to the Feedback group). Right below, the name of the component and the completion status tag. After, there’s a tab menu for different component variants (for example, Alert has a regular variant and a mini, Tip, variant). Each variant includes a link to the codebase, a link to Figma, and a link to any other supplementing documentation (for example, from a third-party library). It also includes a brief description of how to use the component and Figma (or code) embeds
We try to maintain the same format for all components, to the extent to which it makes sense. (Large preview)
Screenshot of our Slack design systems channel
Our design guide is the first item pinned to the design systems Slack channel. (Large preview)

I find that the biggest issue for both designers and developers is what’s available and where to find it. Having a simple documentation website helps solve that issue with minimum effort on your part. Once you have a central starting point, you can start building out more specific, relevant documentation in respective designers’ and developers’ tools.

One thing worth duplicating

The high-level organization of components and styles should be the same across different tools. For example, we have divided our styles and components into nine groups:

  1. Foundations;
  2. Forms;
  3. Navigation;
  4. Cards;
  5. Data Display;
  6. Feedback;
  7. Overlay;
  8. Brand & Media;
  9. Composition.
Three screenshots showing navigation in our Design Guide, Figma, and Storybook
(Large preview)

Each group has 2 to 9 components. Although component content inside of each group may vary depending on the tool (for example, we have three different table components in code and only one in Figma), the number of groups, their names, and group order is always the same. Having the same organization makes it easier to jump from tool to tool and find what you need faster.

Unlike specific components, the group names (or their order) are rarely updated. And even if something changes, it’s not difficult to realign all tools.

Reference Your Developers’ Component Library

If your engineers use a component library (for example, Chakra UI, tailwind UI, material UI, and so on), you should reference it. Most libraries are well-documented and have numerous examples you can play with. You don’t even need to know how to code (although getting familiar with the basics always helps).

Screenshot of Chakra UI documentation
Chakra UI includes editable examples and shows various ways you can customize the component. (Large preview)

Referencing the library will help you make tons of tiny decisions quickly whenever you have to figure out how a certain component should look and behave. It will also help to settle the naming debates (you can just go with the library’s component names to avoid confusion in the codebase). Lastly, it’ll then take less time for developers to implement the components.

Let’s look at an example.

Shown below are two filter menu components: one created in Figma by a designer and another one from the Chakra UI library:

Screenshot showing two filter menu components
Component in Figma places checkmarks on the right, but the Chakra one places them on the left. (Large preview)

When the designer created this component, they had no strong opinion of where the checkmarks should go. They also didn’t realize that the placement could create problems for engineering.

However, when the developer saw this component, they thought that the checkmark placement was purposeful and that’s how the component should be built. The developer then spent several hours tinkering with the component, only to realize that the change was not as trivial as it seemed. They ended up messaging the designer, who, at that point, switched to working on something else and really didn’t want to revisit the design. Also, other designers have already started using this component, which has pulled more people into the conversation.

Numerous back and forths lasted a couple of days, and eventually, the component was updated. A lot of valuable time was lost over something that didn’t deserve that much attention.

This situation (and many more like that) can easily be avoided if designers reference developers’ documentation from the start. Of course, you shouldn’t choose ease of implementation if it sacrifices user experience.

Keep Your Purpose In Mind

Take the time to think and write down why you love working with design systems. Personally, I do this because it reduces monotonous work for both designers and developers. It frees them to get more creative and spend more time thinking about their problems. And it helps them iterate through possible solutions faster.

While your answer might be different from mine, the overall theme will probably be similar.

So, why is it important to have a clear understanding of your purpose? Because it gives you something to lean on in moments of frustration.

Unfortunately, the nitty-gritty details of design systems work can turn anyone into a control freak. It’s easy to start feeling like your success depends on people using your system all the time just because you invest so much energy into it. What ends up happening is that you create a restrictive environment instead of a freeing, creative one.

I find that reminding myself of my purpose (rereading it or even occasionally rewriting it) helps me approach points of friction more calmly. It helps me figure out when I should step back and go work on something more substantial.

At the same time, it helps me figure out when I should push back. It gives me the confidence to speak out because I know I’m doing it in the interests of my team and not because I’m feeling defensive.


Another reason I love working with design systems is that I enjoy the process of work itself. Either playing in Figma or coding, that’s when I get into that sweet flow state. As the only person on the design systems team, though, I can’t spend all my time in the zone. I still need to organize, share, and communicate my work. Otherwise, no one will know about it, no one will use it, and it will be obsolete.

I can, however, manage the system in a way that lets me spend less time on the administrative stuff and more time doing what I love.

While I hope you find inspiration in the tips outlined here, I also hope that you will feel more comfortable questioning any established or common practices and only use them if they work for you and your team. Perhaps you will also feel more comfortable testing out your own ideas, no matter how unconventional they seem.

Smashing Editorial (vf, yk, il)

Posted by Contributor