Storyblok Raises $80M Series C - Read News

Skip to main content

SftB#2 Recap: Lessons learned from building a customizable UI library

Christel Forey
Try Storyblok

Storyblok is the first headless CMS that works for developers & marketers alike.

As part of our live event for our second Stories from the Blok, Vue Storefront’s CTO & Co-Founder, Filip Rakowski, presented lessons learned from building a customizable UI library that Vue Storefront customers can use.


Vue Storefront is a headless and backend-agnostic eCommerce Progressive Web App (PWA) written in Vue.js. Using a headless architecture allows Vue Storefront to connect with any eCommerce platform and headless CMS.

Vue Storefront’s framework is designed to build eCommerce storefronts (based on Vue.js and Nuxt.js), providing seamless integrations, architectures, and ready-to-use boilerplates to create the best possible eCommerce experience. In addition, Vue Storefront provides the necessary dedicated UI library to create reactive, mobile-friendly online stores with a customizable design interface.

Storefront UI is a user-interface (UI) library containing Vue.js components that are specially built for eCommerce. Its user interface includes dedicated Figma designs, for example, that can be used as a white-label design system for eCommerce usage. Building it from scratch, the team at Vue Storefront had all the designs ready, with an estimation of the project to span over just 3 months, yet one year later, the reiteration process of the library is still taking place.

Section titled The beginnings of Storefront UI

It takes an idea to grow into something greater than thought. The team at Vue Storefront started exactly with such an idea: to create a customizable library of Vue.js components in order to aid users in skipping the bootstrapping process and avoid rookie mistakes when building their eCommerce storefronts. Such an idea on the drawing board can as well be underestimated in its complexity. Why is that?

The first task looked through the designs available at hand, and essentially, moving them to a library where Filip estimated that it would not take more than 3 months maximum from its ideation to the finished product.

Section titled Things they wished they knew when they started Storefront UI

It turned out that the building process of the library was much more complex than originally thought, in that having built something as complex as Vue Storefront itself, certain details and specifications that were still unseen or not yet known were undermined and needed to be addressed over time as they appeared. Here are some lessons that the team at Vue Storefront learned from building Storefront UI, and what they wished they knew beforehand:

Section titled 1. Don’t reinvent the wheel

Component libraries and components themselves are already widely explored. The best thing to do is to take what is already known and improve on what already exists in what you don’t like. A tip that was found was to look to fellow competitors, regardless of whether you liked their ideas or not, yet to figure out how they got to their final product, their thought processes, and the story behind their decisions.

It was a fact that the team at Vue Storefront was not satisfied with how they worked, performed, and handled customizability. The fact by not being satisfied created an assumption that nothing could be learned - a contributing mistake that led to multiple reiterations that could have been avoided at the beginning of the process if only research, exploration, and understanding of other UI libraries and how users interacted with them had taken place.

Section titled 2. Don’t release too early

A key factor that was found amongst component libraries was not to release too early. This was because everything inside component libraries lay upon a public API. A public API is essentially a customer-facing API that customers regularly use that in theory, should be versioned. The reason behind this is due to the nature of what makes up a component library, such as HTML, CSS, Javascript properties, and such. If changes are made to any of those elements, breaking changes are introduced - ie. once you ship the components to your users, you lose freedom in making any changes, without introducing breaking changes.

Section titled 3. Start small

Vue Storefront wanted to ship the library as fast as possible, adding components each day thinking they were achieving prime productivity in doing so. The truth was, they did not. When the team shipped the first version of the library quickly, they were forced to rewrite all the components multiple times and with each time, needed to establish relevant conventions to tackle each every single time - having such conventions established since the beginning of the creation process, would have avoided the team the hassle that they incurred.

The learning here is to start small and experiment with the most generic components of different types such as tabs, lists, or hero sliders. This could then be applicable and replicated on more specific components such as carousels being built upon hero sliders, or tabs built to become an accordion component and such.

Section titled 4. Test your ideas extensively

Testing goes beyond just writing tests, but more so into testing against real use cases, such as doing a PoC of your new idea and testing it with use cases that can be measured and learned from.

In the case of the UI library, the team did not like that every update in the UI library was a breaking change and wanted to overcome this by making the API layer stricter - allowing changes to be made inside a component. The idea was to allow customizability of components through CSS variables as it is a native API with flexibility and customization in real-time (making it perfectly compatible with Storyblok’s Visual Editor) through a WYSIWYG editor.

The team thought they had nailed it down and accomplished the customization needs they were looking for. In reality, this was far from the truth. Once the API was used in a project that was complex enough, it was too late for the team to go back and make changes. Developers were then made to go through a chain of CSS variables, resulting in users not using the intended CSS variables and overriding instead.

After revisiting the issue, it was found that in fact, the CSS variables were not the issue, but the complexity of the chain of CSS variables developers would need to go through. The learning is to not get too excited - learn the downsides, test extensively, and see whether your idea is in fact, a good idea.

Section titled 5. Think about progressive enhancement from the beginning

From the beginning, thinking about a strategy that leads to progressive enhancement is vital to providing the baseline functionalities of your website, then enhancing those functionalities and experiences to those who support it.


Progressive enhancement is a strategy for web design focused on emphasizing loading core webpage content first, that then progressively adds more nuanced and technically rigorous layers of presentation and features on top of the content

The lesson learned here was to try not to use Javascript to achieve component interactivity, but instead to use pure HTML or CSS over Javascript whenever possible. This was because when your Vue components were not properly ‘hydrated’ or with the potential of your Javascript breaking, the overall experience and components would still work.

Another lesson to this is the usage of native features over third-party libraries - native features are not only more reliable but also improve your performance for optimization. In all, test your components and site with Javascript disabled, and if that is too much, make sure your components regardless if it is in HTML, CSS, or Javascript at least look the same. This not only brings in the factors of being SEO-friendly but pays off with Google’s developer Lighthouse score tool.

Section titled 6. Use visual regression testing tools

When we are talking about how things look overall, the components are part of the UI layer of your application that makes visual regression testing tools vital.


Visual regression testing is a comparison of screenshots that highlight the difference between them. In this way, a user can spot the difference between components with broken user interfaces, and catch elements that a regular test would not be able to detect. Such tests can are great at spotting in the UI a line-break, misalignment in texts, images, and such

In the case of Storefront UI, the team used to conduct visual regression tests.

Section titled 7. Test a11y and performance regularly

Continuously test the impact of your component’s accessibility and performance. Components play a major role in the performance of your application, and without the ease of performance and accessibility, will become the bottleneck in your process. For example, if you are building a library of components and want to ship it somewhere, the lack of performance and accessibility will impact multiple pages and websites. Thus, making it vital to test with cases common to your component library (in an eCommerce context, testing the product page, check out page, and home page and testing it against those pages), using sources such as or Google’s Page Speed Insights.


Accessibility (a11y) is a measure of how accessible a computer’s system is to users and how the software and hardware are configured to enable a disabled or impaired person to use that computer system specifically.

In regards to accessibility, check each component against the common rules with plug-ins such as Storybook (storybook-addon-a11y) to test basic a11y.