It can be a tough conversation to have, but reworking your design system can be what’s best for everyone.

Facing up

It’s a familiar experience that lots of us have shared — migrations to merging, refreshes and refactors. First, it was Photoshop to Sketch, then Sketch to Figma (for the most part). And now, if you are a Figma user, it’s improving the usability of your component libraries, with Auto Layout and currently with updates to the Properties panel for closer design/code parity.

When I joined Productboard as Design System Lead, my first task was to see what I was up against. The design system had a good foundation, but after thumbing through our libraries, I discovered a few things that could use some tweaking to help take the system to the next level.

At the top of my list was Figma. Although Component Properties would not be available for another couple of months, Auto Layout had been out since the end of 2020. However because our design system had been created two years prior to the introduction of Auto Layout, even that had not been incorporated into the components yet. As you can imagine, we had thousands of variants without Auto Layout that would need to be managed individually 😱 This was overwhelming and enough to raise the anxiety levels of many folks, let alone my own OCD jitters.

Limited props = 100s of unnecessary variants

We needed to get this under control. How could we expect designers to trust and use our components correctly if even we could not trust or understand them? It wasn’t just our core component library. Iconography, Illustration, and Brand were in similar conditions.

And what about in React?

It was déjà vu for the codebase. Our engineering team was aware that our React repo had multiple instances of the same component but used in various parts of the product. This was mainly due to contributions from engineers who needed to move at pace after the rapid growth of our product during Covid. Why did engineers contribute in this way? A big part was because designers were creating similar components or did not know what was correct, leading to all these other iterations. We needed to do some thorough housekeeping by merging multiple instances of the same component, doing health checks on what we then had, and finally deprecating a lot of legacy code that was not necessary.

Having too much makes it hard for discoverability and to support

Process of refactoring

Following the Component Properties update, the decision to refactor was a no-brainer. During the last two months of 2022, I began to plan how best to approach this task. I wanted to gather more information from the design team to learn more about major concerns involving the libraries and, more importantly, what to tackle first. We can make assumptions about which components should be reworked and released first, but are these actually that vital to the usability of the product for customers? A primary button, for example, may be widely used, but is it more important than, say, a form element or a menu that is more complex?

After a designer survey and general audit of components was collected, it was decided that our more detailed component patterns were in more need of rescuing. I started recrafting the card, modal, and menu components at the beginning of this year.

Introducing new properties

The audit showed me the most instances of individual components used across the product and just how much variety and discrepancy we had. By combining all the similarities, I was then able to create a master foundational component for each of these larger patterns that all subsequent variants could be created from.

Unifying the core parts of a larger pattern for a consistent outcome.

Because there are hundreds of unique modals, for example, I used the Component Properties to toggle various attributes, and then applied boolean and text properties where appropriate. Another big part of the refactor was including workable slots to nest other components from the library. We already had a legacy version of slots used in the core library, but this had become unusable since Auto Layout had not been added to all other components, meaning the resizing wouldn’t work in our new larger patterns.

Tease me

Making these changes is all well and good. It improves many facets of a component’s health and trims down the volume of variants to support, but I needed to make sure that the process we were following was understood by designers since they are our customers. If the adoption rate was to increase to levels hoped for, I wanted to provide explorations on how components were being crafted, as well as follow-up demonstrations on how to use them.

Clear guidance will increase curiosity, improving adoption.

Quick teaser videos were a great way to share what was being created and how. Not only did this give designers an opportunity to provide feedback on these developments, but it gave them good insight into how I approach creating a component that can have multiple usages. Up-skilling where you can!

Component demonstrations have an impact when it comes to their usage. Designers can include a component in their designs, but what’s the point when it is not being used as intended? For elements like a button or an avatar, there isn’t much to misinterpret, but for a menu in Productboard’s application, there is helpful guidance available. Video tutorials benefit the whole team, saving time in support requests.

Providing a greater level of detail

Once a component was refactored, typically we: 

• Reduced the number of component variants exponentially
• Applied the improved Figma functionality
• Addressed any accessibility concerns
• Tokenized correctly

In addition to all this was information about discoverability. Since we had a two-year legacy of component contributions in our libraries, we had accumulated many types of similar components, and it was confusing to know which ones were correct.

Provide as much useful detail as possible for components.

We needed to archive all these in Figma and merge their usages in code with our refactored component variants. This, as you can imagine, is quite time-consuming when we are dealing with many usages across different domains. As part of the update, components now receive the correct configuration details for better discovery and link to Storybook and our Nucleus documentation.

Announcements

We now have the component ready in design and fully tested in code, along with the relevant documentation on how to use it properly. Announcing a new component would be relatively straightforward, but because we were replacing old with new, I needed to provide a softer landing for designers to experiment with these updates and replace any old instances in current designs.

*It’s worth mentioning we did not request designers swap every instance of a component in legacy designs, only current flows and screens that were deemed necessary to change.

Release plan

To keep track of what status each component was in and what we had finalized for each, a release list was created in Notion and embedded in our docs site for visibility. Plans can change depending on business needs, so we needed to be reactive to this and plan accordingly.

An announcement message explaining the updates and how to provide feedback.

Tiering structure

Although the process of creating a component in our design system is consistent, (naming conventions, styling consistencies) the complexity of each varies considerably. A button has even more usages arguably than a modal but has far fewer props to configure and limited customization. Swapping a button like-for-like should therefore be an easy process for designers, whereas a modal requires more time for discoverability and understanding.

We gave a four-week deadline for changes to be implemented in designs.

Placing each component into a three-tier level release system gave an appropriate time frame between announcement and deprecation for designers to make their changes. However, once a deprecation date arrived, the old component was placed in an archive library that was still accessible should additional time be needed. During this time-frame window, I encouraged more feedback on the design, code, and documentation contribution, so the Nucleus team could make changes before the final feedback loop closed.

Results

Looking at the analytical data, we saw an increase of core components from 31 to 42 (+35%), which seemed like we were adding even more to support. But in fact, we were taking these away from domains, as they were being used in multiple parts of the product, and we could now maintain them correctly. Alternatively, there was a need, in some cases, for a new component addition to the library, such as Date Picker or Pagination, that wasn’t previously supported.

The biggest wins for us were the decrease of variants supported in Figma, down from 3192 to 879 (-72%), and the sizable code deprecation from the React repo. With all this removal of legacy design and code, our parity between both has increased to more than 84% (at the time of this writing). This is what really matters, as both design and engineering can now be confident when working with our components, reinforcing that React as our source of truth.

Survey and key takeaways

Each quarter we provide product teams with a design system survey based on our performance over the last three months. Sentiment questions on satisfaction and usability and open-ended questions on challenges and improvements are asked to gather insights that help us understand the pros and cons we are currently working with.

Asking specific questions helps gain a more honest answer. Further explanation can be asked for later.

From these results, we are able to provide some key takeaways for the teams, so they know exactly what the Nucleus team is going to take action on next. Examples of key takeaways include further explanation of slot usage, complexities with the UI selection framework and library housekeeping improvements. For visibility, all this data is collated into a quarterly newsletter that I add to our docs site, with further information on component usage, what’s on the roadmap and feedback summarization.

Our lessons for the Nucleus team

Refactoring will feel like (and probably rightly so) a daunting task, especially if you are working with an established component library. You can make this process smoother, however, by being transparent about the job at hand and how long it may take. There is no perfect way of doing it, but making a solid plan of attack will help guide your team on its progress by providing a detailed process to follow.

Giving your users visibility on this process is vital. It is one of the biggest things I have learned while at Productboard. It’s important to demonstrate and carefully explain any changes to the product and therefore your customers.

I was lucky to have a team that had bought into the process and what it meant for the design system. Not all teams are like that. So try to be calm and pragmatic when it comes to questions, it will almost always come from a good place. 😃

Would you like to join us? 

If you’re looking for an exciting and complex tech initiative with a real-world impact, here’s your chance. Head over to our careers page, it could be the start of an amazing adventure, and we’d love to hear from you.