Storybook – more than a living style guide?
Krzysztof KaszanekReading Time: 6 minutes
What is Storybook?
Storybook is an open-source frontend tool for building and documenting UI components. It’s a form of a living style guide, that should help to keep designers' and developers' work in sync. It uses the actual component implementation to display the component documentation. The base element of Storybook is called a story. Each story represents a specific component state. It’s not static, like some of the other tools, so it allows you to check all the component variations in one place, without the need to even run the application.
Main goal and benefit of maintaining Storybook
The biggest advantage of having a well-maintained library of components is that you gain a single source of truth for everyone involved in the project, be that designers, stakeholders, or developers.
It also makes it much easier for new developers to jump into the project when they have this overview of all components, their variations, and properties all documented in one place.
Having Storybook in place should make the design process of new pages more structured, meaning that existing components should be reused whenever possible, and new ones should be created only when it is really needed. Here it just comes down to being consistent in using components across different pages on the same website and Storybook can be very helpful in achieving this. Especially, since it can be integrated with popular design tools like Figma.
On the other hand, it can happen that the developer is not aware that a similar component already exists, and instead of implementing it as just another variant, it is implemented as a completely new component. It can easily happen especially in bigger projects where some components are “hidden” deep in the app, or require a specific set of actions to enter the page where the component is actually visible. Storybook solves this problem by displaying all components in one place, where you can play with the properties and check all possible states by yourself, without the need of going through specific and complex scenarios in the actual application. In fact, you don’t even need the application running, you can just use Storybook.
Storybook is much more than just a documentation of components
Storybook describes itself as a “tool for UI development”, which is much broader than just a style guide. This is the most notable difference when we compare it with tools like the KSS style guide that I described in this blog post.
First of all, working with Storybook is much easier for developers, as we don’t need to copy and paste a ton of HTML for every component that we want to document. It avoids the big problem that we often have with all kinds of documentation - keeping it up to date. Storybook is auto-generated from the component’s code, which solves this problem.
Discover all component states easily
For me, one of the biggest advantages of Storybook is that I can check any component in any of its states anytime. Some elements that are only visible during specific scenarios (e.g. error messages) are often cumbersome to work with and require either repeating some specific flow in the app, mocking some state, or commenting out parts of code. In Storybook, you can modify all component properties directly from the style guide to check how it looks. This way you can quickly access all possible component states on demand, all in one place. It makes debugging much easier.
No data? No problem
This also comes in handy when you are working on a project that for some reason has no source of data yet. It may be because of the missing integration with ERP, the need to migrate the data from an older platform, and so on. Anyway, it can block you from starting the frontend development, or force you to spend time on creating mocked data and then working with that. With Storybook, you can decide to work on components in separation until the real data becomes available.
Storybook testing possibilities
Once you decide to use Storybook, you will get many testing possibilities almost “for free”. Storybook comes with add-ons that you can easily set up to enhance your Storybook instance with tests that will help to catch UI issues.
Using stories configuration for the tests
When you write tests for your components, you need to create the scenarios, feed the components with properties, and also take care of all the providers (theme, routing, translations) so that they render correctly. Well, if you use Storybook, you already did exactly that for your stories. So instead of repeating yourself, you can use @storybook/testing-react library. It allows you to reuse the setup from your stories in the React tests (there are also libraries that allow you to do the same in Vue and Angular).
Visual testing
There are two approaches to implementing visual regression tests for Storybook components.
One way is to go with Chromatic, which is a cloud service built for Storybook. Setting up visual tests in Chromatic is very easy and it offers much more than just that. On the other hand, this is a paid solution, and may not fit every project.
If you prefer a self-managed solution, you can follow the same steps as described in one of my previous blog posts: Front-end automated testing using BackstopJS and KSS style guide, you will just use Storybook instead of KSS, but the idea stays exactly the same - to run the visual regression tests against style guide components.
Snapshot testing
This type of testing is similar to visual testing, in a way. While visual tests capture images of components and compare them with image baselines, snapshot tests do the same, but on the DOM. It’s obviously more primitive, as it might not catch changes in appearance, but because of its easy setup, it’s worth considering. Running regularly during development will help to catch unintended changes in the DOM of other components.
Accessibility testing
This important sort of testing is often overlooked by the developers. Storybook offers a great a11 addon which you can use to spot accessibility issues in your components, directly in Storybook. It won’t catch 100% of issues, but it is a good place to start and keep an eye on your component's accessibility as you are implementing them.
If you want to automate the accessibility tests, you can employ Storybook’s test runner. It uses Playwright to run your Stories in the browser and runs the tests against them. You can see an example configuration of the test runner here.
Interaction testing
Modern components used in web applications can be very dynamic and significantly
change their appearance due to user interactions - clicking, typing, and so on. Interaction tests are an ideal tool to test this type of behavior. In short, interaction tests start from the component's initial state and once it is rendered, simulate the user interactions that you defined.
Just like the accessibility tests, they can be run both directly in Storybook, or via a test runner.
When is it worth implementing and maintaining Storybook?
As you can see, Storybook brings a lot of benefits and much more than just being a component library. On the other hand, implementing Storybook, maintaining all components and Storybook deployment requires additional work and time, and time is money. For some teams, it may be crucial to have a tool like Storybook, for some it will be just an additional burden. Let’s try to take a closer look at a few aspects that you should take into consideration when thinking about adding Storybook to your project stack.
The technology stack of the project
Storybook works best with the most popular component-oriented frameworks and libraries: React, Vue and Angular. They are all handled by Storybook Core, the integrations are well documented and there are a lot of add-ons and plugins that will help you integrate Storybook with your application.
Storybook also supports pure HTML, however, writing stories for HTML components is definitely more cumbersome. In case you are using some templating engine like Twig in Shopware 6, Storybook is not a feasible option.
Size of the team
Another aspect is the size of the team. I would say that the more people are involved in designing and developing the components, the more a tool like Storybook will pay off. Also, if the rotation of developers in the project is quite high, it will help newcomers to onboard quicker.
Type of project
Is it just a simple website developed by a small team and there are no plans to reuse its components in other projects? Storybook still can be helpful in this case, e.g. to keep the new designs consistent with existing components. Or is it one of many shops that belong to the same company and they should share the same elements? In this scenario, Storybook can serve as a base for the whole design system that will be used across different projects.
As with everything, there is no clear answer to the question. You need to assess the aspects discussed here and make a decision. Although working with stories from the beginning of a project is probably easier, it is also possible to incorporate Storybook at a later stage, so that is also a viable option.
Conclusion
I hope that after reading this article you have a better understanding of what Storybook is and what it isn’t. I’m sure that it can help in solving some of the issues that many front-end teams will run into sooner or later.
If you want to check out the source code of the demo app that was used to present some of the Storybook features in this blog post, check this repository on our GitHub.
