Building and maintaining the component library of a design system

Mikael Sukoinen
Mikael Sukoinen
On Nov 12, 2020 2:25:36 PM


The main purpose of adopting and using a design system is to ensure consistency with minimal time and effort in the long run.

However, there’s no such thing as a “free lunch”. The trade-off of a design system is the time and effort required to implement and maintain it. It’s an investment, but you can minimize the cost and maximize the return on your investment by planning ahead and building repeatable processes that keep day-to-day activities easy.
Planning the building, testing, versioning, documentation and maintenance of the component library of the design system is key to ensuring its smooth operation and future scalability. This is the vital step that will make the trade-off worth it.

This article provides an overview of the planning process, together with suggestions on how to tackle the challenges along the way.

Are you new to design systems? Then our introduction to design systems article is for you!

What are design systems and why do you need one?

A design system is composed of a component library, along with corresponding visual assets for designers and documentation on recommended usage of each component. The system helps designers and developers work together to create consistent UIs that deliver a great UX across applications. Furthermore, the consistency accelerates development and eases maintenance. 

However, a design system is never fully complete: It's a living system that evolves constantly to suit the changing needs of the organization and to stay up to date with the latest demands. Keeping the system alive and healthy does require consistent effort. 

To minimize the effort and maximise the gains from a design system, the initial set up needs to be complemented by small but steady steps to keep it moving forward. 

Continue reading for suggestions on how to build and maintain the component library at the core of your design system.

Building and maintaining a component library

A component library consists of pre-made UI components, such as buttons, text fields and so on. These are used to build web apps in a reusable and consistent way. 

Building your component library

To successfully implement and effectively utilize a design system, it must be built on components that can be updated and scaled throughout its lifecycle. You can build your component library from scratch or adopt, adapt and expand an existing library. Either way, you need to ensure the technologies that form the foundation are stable and can be molded to fit current and future development projects. Choosing proven technologies that are known to scale well and can be customized to fit your needs will help to keep your library relevant.

Read the previous post in our Design System blog series to learn why you should use Web Components as the building blocks for a stable design system!

Testing your library

Just like testing the UI of an application, individual UI components should be extensively tested, especially for the aspects the end user comes into contact with. Visual elements should render correctly on all platforms, functionality should operate as intended, and performance and accessibility should meet expectations. Testing can, and should, be performed:

  1. Manually: Have a developer run end-to-end tests in the browser and/or monitor a user testing the UI.
  2. Automatically: Simulate use with automated visual regression testing tools that measure performance and assess compatibility with different platforms.

Successful test results reveal any bugs needing to be crushed before deploying the component. The advantage of testing on a reusable-component level, as opposed to a finished-application level, is that the tested code is ready to be reused and applied across multiple apps. If you are testing a component that is used in three different applications, one test serves all of them. More testing means fewer bugs!

It is also easier to update the apps using the component across the board; when the component is replaced with a newer version, the changes are automatically applied to every application that uses it.

Documenting components

Providing clear and accessible documentation on how the components are built, maintained and used, is vital when implementing them in the design system. This typically requires a documentation tool and a place to host the documentation, along with guidelines on how to write the documentation. 

Documentation for each component often includes, but is not limited to:

  • Overview: Detailing the name and primary features of the component.
  • Instructions: On how to install and include the component in an application.
  • Visual examples: Showing the component in use. 
  • Code samples: Demonstrating how to use the component’s API. 

Every time a component is updated, so should its documentation. Having good documentation for the library, helps users find and use the correct component, and aids the effort of maintaining it.

Educating your team

The infrastructure that is required to maintain a component library promotes fluent and agile communication throughout the organization and should ideally narrow the gap between stakeholders. However, it’s not enough to only build the infrastructure and put it in place. You also need to introduce your users to it and guide them on how to use it. Consider educational workshops or webinars to strengthen the message in the written guidelines. 

Versioning your components

Software versioning is an effective way to announce and track changes when updates to the components in your library are rolled out. Versioning can be done by simply adding a version number and release notes for each version. The release notes should detail any changes and their intended impact, such as new features, performance improvements or security fixes.

The latest version of the component should replace the previous version to avoid duplicates, unless it's experimental or unfinished. It is good to include these kinds of components in the library for large-scale testing of new features etc. A suffix to the version name that indicates the version is a work-in-progress, such as an alpha or beta tag, sets expectations and helps users adopt the version that best suits their needs.

You should always archive old versions of the components in the interests of decreasing fragmentation. However, it’s handy to save them somewhere for their documentation and the option to “roll-back” if a critical issue surfaces in the latest version.

Maintaining your library

Good maintenance takes effort, but doing it consistently will keep your system running smoothly. Building the library on scalable and modular technologies, providing useful documentation, running thorough tests before deployment, and educating your users all ease the maintenance burden and allow the designers and developers to self-service the components. However, you still need support channels and a maintenance schedule for your  component library, just as you do for the apps it’s used for.

Learn more about design systems

Our Design System blog series serves as an entry point for adopting the upcoming Vaadin design system. Read about the business case for adopting a design system by the product owner to learn more details!

If you’re already familiar with the Vaadin design system, then keep an eye on our blog for further announcements.

Mikael Sukoinen
Mikael Sukoinen
Mikael has a passion for writing text, code and music. He’s currently utilising his skills to explain difficult concepts in plain language at Vaadin Ltd.
Other posts by Mikael Sukoinen