The difference between a component library and a design system, and how they can help bridge the gap between design and development

By Petter Andersson on 6 juli 2022

A while back, our former technology manager Roy Derks covered the subject of component libraries here on the blog. From a technical perspective, he spoke about when you need one (and when you don’t need one) and what to consider when building one. Since then, obviously a lot has happened at Vandebron. But one of the more interesting things to happen is that design became an integrated part of the digital department, as opposed to previously being attached to marketing. In this new setup, one of the first major projects the design team was involved in was the alignment of our component libraries. And no that’s not a typo, that’s libraries as in the plural form of library. Confusing? I thought so too. In this blog I’ll try to explain further why that was the case, how the work actually helped us bridge the gap between design and development, and dissect the work of unifying those component libraries into one single source of truth and ultimately what’s to become our design system.

A bit of a mess

Before we get into it, some background as to where we started out might be useful. As previously mentioned, the design team had just become a part of the digital department and one of the first tasks at hand was the creation of a design system. In the design team, we had previously worked with a certain set of brand guidelines, a style guide if you will, which had not necessarily been translated or aligned to the requirements of a digital product or development environment. Development had also created a set of stylesheets and libraries with reusable components which they used to reduce development time. Having it all separately might sound a bit counter-intuitive, but not very surprising if you consider designers and developers not being in the same department, working on a different timeline, different priorities and so forth. However, this only highlighted the importance of designers and developers working together and the need for a proper design system to help prevent creating a fence between the teams causing unnecessary and ineffective work on both sides. The result of this previous “unsynciness”, a rebrand in 2017, and a re-aligned techstack, was the existence of 3 different libraries and subsequently 3 different sources of truth within the development environment. To add to this, we also had separate design guidelines geared more towards brand/marketing purposes in the design team. Now came the rather massive task of unifying these and eventually, rather than having just a library, having a system.

Component library ≠ design system

Now, there’s a lot of terminology here that might be difficult to grasp if you’re new to the subject. So I thought I’d clarify what we mean when referring to these, how they fit into the context of our situation, and how many of them we had!

  1. Brand guidelines / style guide (design)

    A set of guidelines and examples outlining all the visual elements of a brand such as logos, color, typography, imagery etc. and subsequently in what - - manner they should be applied. It can also be expanded to include more things brand related such as tone of voice, brand values and so forth. Often with brand guidelines, they are created from a marketing perspective and the digital experience(or product) aspect of how the brand should be applied/represented is usually thought about in the second hand, or not included at all.

    Amount: 1

  2. Design kit/library (design)

    A designer resource file with all the available building blocks that make up the digital design language of a brand and/or the user interface of a product. This is usually only visual(no code) and lives in the design software of the designer's choosing. For us this used to be Sketch, but we recently moved to Figma. Can also include documentation and examples of how the different building blocks should be applied and utilized.

    Amount: 1

  3. Style sheet (front-end)

    A set of styling properties to be applied when rendering a web page, usually in the format of CSS. This can include things related to the brand guidelines such as font size, colors, etc. but also things related to web layout such as the margins and paddings of different web elements.

    Amount: 1

  4. Component library (front-end)

    A set of dynamic web components that can be used in a development environment in order to quickly build user interfaces. This helps to ensure consistency, to avoid rebuilding the same component more than once and to avoid changing said component in more places than one, and subsequently help reduce development time.

    Amount: 3

All of the above mentioned things, together with rigorous documentation, amount to what’s called a design system. Having it all combined in a structured way is key to getting the most out of such a system. In our case, most of these things were separate and not necessarily connected to each other. But what stands out most of the things above is probably the fact that we, over time, had amounted to 3 different component libraries. I mentioned earlier how that scenario had transpired so I won’t go into too much detail as to how that happened, but if you’re a developer in a small to medium-sized company and I mention “rebrand” and “new techstack” you can probably figure out how. However complex, this also proved to be an excellent opportunity for our developers and for us in the design team. We finally get to unify our component libraries into one, while simultaneously aligning it with our design kit and expanding the guidelines with new and updated documentation. Thus ensuring that designers and developers speak the same language and share the same single source of truth.

A guild forms

To kickstart this process we formed a project group(or ‘guild’) composed of 2 designers and 2 developers, each designer and developer from the two consumer-facing scrum teams. The idea was to let the developers work on the migration and unification of the component libraries in collaboration with us designers in the same project, making it easier to align and to create co-ownership of the product. Our first step was to decide on the structure of our component library, this way the developers could slot all the existing, reworked and new components into the right place in the new library. Easy enough right? Well, here comes our first challenge. We initially wanted to take an atomic approach and build our components from the well known and widely used atomic design principles. We also needed to consider the 3 different “product groups” which the library should apply to, all still utilizing the same style properties.

Vandebron has a wide range of products serving different platforms, with the visual language remaining the same but where the user interface might differ. This requires the top elements of the system(such as colors and typography) to be shared across all products, whereas the lower you get the more product-specific an element becomes. This is the reason why we wanted to structure the system according to the principles of Atomic Design first, in order to assign the components to a hierarchical structure.

Atomic Design

With this approach the atoms would work like design tokens and the molecules would be components general enough that they’d be shared across all product groups, this CORE part of the library would essentially be the stylesheet that impacts all visual aspects of the digital brand experience. Only on organism-level do we start to differentiate what product group the component belongs to. So a change to the CORE parts of the library(atoms or molecules) would impact all components in all product groups.

However, this approach actually made less sense from a development perspective. Not that it wouldn’t work or that the categorization didn’t make sense, but it would require us rewriting all the already existing components. Components that are actively in use. We deemed this approach a bit too high-risk and high-effort for the time being and started looking into alternatives, while still keeping the atomic structure as a more long-term goal. Another thing our initial idea didn’t take into account was the experience of the future main user of the library, the developer! Organizing a design system after the brand properties and product groups makes a lot of sense from a designers or a marketeers perspective, and it should probably still be presented outwards that way, but a component library is something else(remember?). So based on our development environment and the way we build our websites and apps our developers suggested a different structure:


In this structure, similar to the previous one, the components are instead categorized and sorted by how they should be applied to the page or application that’s being built. Styles, layouts and inputs are general enough to be applied to all product groups whereas from the surface level the components start becoming more specific in their use case. That way, the components can be separated into specific or even several product groups. In this format the components themselves are not as intertwined as in the atomic structure, albeit still connected by the style element. So while it’s a bit more resistant to overall changes the main idea of having the same style properties applying to everything still works, and it helps us designers to better relate and contextualize what we’re designing from more of a development perspective, thus helping bridge the gap between development and design even further. The main insight we drew from this experience is to not let industry standards and certain trends dictate what you should do. Sure they’re important to keep an eye on, but do it with carefulness and always apply an asterisk to it. Figure out what works best for your specific situation and what’s realistic in the short-term vs. in the long-term. There’s no one-size-fits-all.

Speaking the same language

With the component library migration now underway, we started looking into ways to improve our system from the designers' side of things. As previously mentioned, we had just gone from using Sketch to using Figma and with that came a good opportunity to rebuild, adjust and expand our design kit also. We did that by removing, adding, simplifying and renaming a lot of what was in there since before and with the design kit now adjusted to match the component library we were now also speaking the same language. We can actually now compare this side-by-side with the tools we’re using. In Storybook we have attached the Figma design of every component, simply by activating the feature and pasting the link to its page or artboard in the Figma file. This will refresh in almost real-time if any changes are made so we can easily spot any differences and inconsistencies between what’s live and how the design looks. In Figma, we try to document all our components and give some context as to how it works and should be applied. This is now also directly visible to the developer in the context of the component library. Expanding on our documentation and exposing our digital design guidelines like that has been a great way to create a shared understanding of our designs. Rather than just an image being tossed over a fence, there is now quite literally a direct connection between design and development and therefore also more of a shared ownership.

Storybook & Figma

Further defining the process

As all the alignment on the design side and the migration neared completion, we started seeing a lot of things that could be improved upon or even added to our component library. When we started logging these things down on our project backlog we quickly realized that the scope of our project had quickly been growing into something beyond what was initially intended, and that rather than giving us focus this guild format was instead at risk of creating an isolated bubble of knowledge surrounding the design system. This prompted us to gauge the opportunity and capacity among our development teams to instead tackle these tasks together, either alongside or within their respective day-to-day tasks. In order to do so we needed the buy-in from key stakeholders such as the product owners from the respective development teams. It’s obviously a big ask to get 1 developer from each team to work on improving a component library, especially when they’ve already given us a quarter on migration and have other important business and/or user needs to tend to. So instead, we looked into how we can embed the improvement and further development of our design system into the developers current processes and primary day-to-day work. We structure this by linking our component library improvement/addition tickets to relevant tickets in their respective sprints. In defining the workflow like this, our 2 designer 2 developer guild in effect rendered unnecessary and instead we opened up the co-ownership and contribution to all developers in all customer-facing development teams and in the process of it preventing isolating knowledge too much. In opening up the process like this, another positive side effect we see is the involvement, engagement and subsequent use of our component library going up. With the product designers now also actively a part of the front-end guild meetings, we have an ever bigger forum and bigger opportunity to build a world class component library and design system while also having more hands on deck to work on maintenance and improvements. We still have a long way to go, but all parts are now even more aligned and the future is looking bright!

What’s next

In the newly formed designer+developer guild, the work of defining requirements and improvements on the design system continues. From the design side we’re also looking to constantly improve on the documentation and the presentation of our system. This is something we imagine we’ll keep on doing continuously and iteratively for as long as it’s needed, if not even forever. After all, “design is never done” and a design system can and should be a living thing constantly evolving along with the products and the brand it serves, and in extension even the promise the brand and it’s products. In our case, that’s to aid in accelerating the energy transition towards 100% renewable energy. More on how we exactly do that, and how we always aim to design for impact, in the next blog post. Thanks for reading and stay tuned!

Petter Andersson, Product Designer at Vandebron

If the type of work mentioned in this blog post sounds interesting to you, take a look at our job openings here.