Storybook: a powerful tool for developing and documenting your design system

A programmer and a designer working (Generated by Bing Chat)

Many times when we embark on the development of a digital product, we reach a point where we need to create a design system that allows us to maintain the visual and functional coherence of our product. Basically, the design system forms part of the brand identity of our digital product. But, the task of designing design systems is one of the most complex in the world of digital product design. The complexity resides in the need to create a system that is flexible enough to adapt to the needs of different products, but consistent enough to maintain a coherent brand identity. In addition, the system must be easy to maintain and update as product and brand needs change.

Let's not fool ourselves, designing design systems is hard work and requires a lot of time and effort, and we, as programmers, are not exempt from this task (despite the eternal fight between designers and programmers 🫣). Therefore, it is important that we have tools that allow us to design systems design in a modular and scalable way.

There are many tools and methodologies that allow us to design design systems, but in this article we are going to focus on a tool that allows us to design design systems in an amazing way: Storybook 🤩.

What's a design system?

Before getting into the subject, it is important to understand what a design system is. A design system is a set of patterns, components and guidelines that allow us to design and develop digital products in a coherent and efficient way. In addition, a design system allows us to design and develop digital products faster and more efficiently, since it allows us to reuse components and design patterns. In other words, a design system is the DNA of our digital product.

It is also important that we understand that a design system is not a set of static components and design patterns, but rather a set of components and design patterns that evolve over time. That is, a design system is a set of components and design patterns that adapt to the changing needs of our digital product and our brand. For this reason, let's keep in mind that a design system will affect all departments of a company, not only the design and development department, since it represents the identity of its products.

Keep in mind that a digital product must have a coherence, far beyond aesthetics. It is not just a matter of a button having the same border radius or its different states looking the same for the same action. No, it goes much further than that. We have to define a language, how we are going to address the user, what tone we are going to use, what personality our products will have. Do we capitalize the button labels or not? Do we inform the events with a toast or with a modal? What kind of feedback do we give to the user? In conclusion, deciding all this and more, is what makes up a design system.

Some examples of design systems are: Google's Material Design, Microsoft's Fluent, IBM's Carbon Design System, Atlassian's Atlassian Design System, Shopify's Polaris, among others. These design systems are used by thousands of digital products around the world and are a fundamental part of the brand identity of the companies that use them. Surely, when using digital products from these companies, you immediately recognize that you are using one of their products before seeing the logo or the company name.

What's Storybook?

Well, we already understood in a very general way what a design system is, but what is Storybook? Storybook is an open source development tool that allows us to design, document and test components in isolation. It is an excellent tool for designing design systems in a modular and scalable way, allowing collaboration between all members involved in the development. In their own words:

"Storybook provides a workshop to build UIs in isolation. It helps you develop hard-to-reach states and edge cases without needing to run the whole app."

It allows integration with different development tools such as React, Vue, Angular, Vite, Tailwind, etc. It has a large community of developers behind it and a large number of add-ons that allow us to extend its functionality. In its latest versions, Storybook has greatly improved its performance and usability, which makes it a very attractive tool for designing design systems.

The main attributes that make Storybook a very good tool for designing design systems are:

• Modularity: Allows us to design components in a modular way, which allows us to reuse components and design patterns.
• Scalability: Allows us to design systems in a scalable way, which allows us to adapt the components and design patterns to the needs of the brand.
• Documentation: Allows us to document components and design patterns automatically, which allows us to maintain an updated documentation of our design system.
• Testing: Allows us to test components and design patterns in isolation, allowing us to ensure that the components and design patterns work properly before integrating them into our digital products. It contains different tools to perform accessibility tests, visual tests, performance tests, among others.
• Collaboration: Allows collaboration with other members of the development team, sharing the components and design patterns with other members of the team, which allows us to work in a more efficient and coordinated way.
• Extensibility: It allows us to extend its functionalities through add-ons, which allows us to adapt Storybook to the needs of our digital products and our brand.
• Community: It has a large community of developers behind it, which allows us to find solutions to our problems and share our solutions with other developers. In addition to a very complete and updated documentation that allows us to start working with Storybook quickly and easily.

Stories, the heart of Storybook

Imagine Storybook as a library of components, where each component is a book and each book has different stories. A Story is a visual representation of a component in different states and with different data. For example, if we have a button, we could have a story for the button in normal state, a story for the button in hover state, a story for the button in active state, a story for the button in disabled state, and so on. A very simple concept, but very powerful😎.

The stories are written in Component Story Format (CSF), a standard based on ES6 modules for writing component examples. CSF is currently in version 3 which, in combination with improvements over version 2, allows stories to be written in a simpler and clearer way. Story files have the extension .stories.js, .stories.ts, .stories.jsx or .stories.tsx, and are usually located in the same folder as the component they represent. Although Storybook allows us to organize stories in any way we want, we can even make use of MDX files to write documentation about our stories.

Integration with different development tools

The way Storybook integrates with different development tools is through addons. Addons are complements that allow us to extend Storybook's functionalities. These addons allow us to perform different tasks such as accessibility testing, visual testing, among others. In addition to changing the way you interact with the stories, such as changing the Storybook theme, changing the font size, among others. All these addons are developed both by the Storybook team and by the community of developers who use Storybook. In addition, Storybook has an API that allows us to develop our own addons easily and quickly.

A powerful integration that Storybook has is with Chromatic. Chromatic is a tool that allows us to perform visual tests automatically. Chromatic takes screenshots of Storybook stories and compares them with previous screenshots, allowing us to detect visual changes automatically. It also allows us to share screenshots with other members of the development team, allowing us to collaborate remotely. Chromatic is a paid tool, but it has a free layer that is quite considerable, especially for small projects or those just starting out.

Conclusions

If you are thinking about designing a design system, Storybook is a tool that you should consider. I invite you to give it a try and see for yourself all the features it has. I'm sure you won't regret it. If you want to learn how to use Storybook, I recommend you to read Storybook's official documentation, which is very complete and updated. But if you prefer a more practical approach, you can visit the different guides they have on their official website, especially this guide that will teach you how to design systems design with Storybook in a practical way.

That's as far as this article goes. I hope you liked it and that it has been useful to you. All feedback is always welcome, if you have any questions or comments, don't hesitate to contact me through my LinkedIn @jagcruz.

Happy coding!🚀