Content uploaded by Tuomas Nummela
Author content
All content in this area was uploaded by Tuomas Nummela on May 07, 2024
Content may be subject to copyright.
Aalto University
School of Science
Bachelor’s Programme in Science and Technology
Using Storybook.js for component-driven design
system web development
Bachelor’s Thesis
May 7, 2024
Tuomas Nummela
Aalto University ABSTRACT OF
School of Science BACHELOR’S THESIS
Bachelor’s Programme in Science and Technology
Author: Tuomas Nummela
Title of thesis: Using Storybook.js for component-driven design system web
development
Date: May 7, 2024
Pages: 40
Major: Computer Science and Engineering
Code: SCI3027
Supervisor: Professor Lauri Savioja
Instructor: Doctoral Researcher Juho Veps¨
al¨
ainen (Department of Computer
Science)
Building web application user interfaces has become increasingly complex due to
heightened expectations and requirements in interface customizability, visual appeal,
performance, and accessibility. This has given birth to frontend tools like Storybook.js
that help developers manage the development complexity through component isolation
and test automation. Storybook is mainly used by developers to build and maintain
design systems that can be used to construct UIs across applications regardless of the
different application contexts.
This thesis explores developer experiences with using Storybook to build and maintain
design systems, identifying some benefits and drawbacks of the tool in the process. The
developer experiences are inspected from the task viewpoints of designer-developer-
handoff, component programming, and component testing. For each task, the
Storybook way of approaching it is explained first. That is followed by a case study
of using Storybook to help with that task in a software company. Finally, some
observations are made from the experiences of using Storybook for that specific task.
The final discussion presents and argues for four observations about Storybook. Firstly,
Storybook offers approachable component workshopping. Secondly, Storybook doubles
well as rich component documentation. Thirdly, there exist numerous add-ons to
further leverage the use of Storybook. Finally, to fully leverage the capabilities of
Storybook, developers must spend quite a lot of effort first configuring the tool and later
creating and maintaining all of its content. The consensus of the developer experiences
on building design systems using Storybook was positive.
Keywords: component-driven web development, developer experience, design
system, Storybook.js, user interface
Language: English
2
Aalto-yliopisto KANDIDAATINTY ¨
ON
Perustieteiden korkeakoulu TIIVISTELM ¨
A
Teknistieteellinen kandidaattiohjelma
Tekij¨
a: Tuomas Nummela
Ty¨
on nimi: Komponenttil¨
aht¨
oisten suunnitteluj¨
arjestelmien kehitt¨
aminen
Storybook.js:ll¨
a
P¨
aiv¨
ays: 7. toukokuuta 2024
Sivum¨
a¨
ar¨
a: 40
P¨
a¨
aaine: Tietotekniikka
Koodi: SCI3027
Vastuuopettaja: Professori Lauri Savioja
Ty¨
on ohjaaja(t): Tohtorikoulutettava Juho Veps¨
al¨
ainen (Tietotekniikan laitos)
Websovellusten k¨
aytt¨
oliittymien kehitt¨
aminen on monimutkaistunut 2000-luvulla k¨
ayt-
t¨
oliittymien mukautuvuuteen, ulkoasuun, suorituskykyyn sek¨
a saavutettavuuteen koh-
distuvien odotusten ja vaatimusten my¨
ot¨
a. Monimutkaisuuden vuoksi on samal-
la kehitetty ty¨
okaluja kuten Storybook.js, jotka auttavat kehitt¨
aj¨
a¨
a hallitsemaan
monimutkaisuutta komponenttien erist¨
amisen sek¨
a testiautomaation keinoin. Suun-
nitteluj¨
arjestelmill¨
a viitataan sovelluskontekstista riippumattomiin, uusiok¨
aytett¨
aviin
k¨
aytt¨
oliittym¨
akomponentti- ja tyylikirjastoihin. Frontend-webkehitt¨
aj¨
at k¨
aytt¨
av¨
atkin
Storybookia suunnitteluj¨
arjestelmien rakentamiseen, yll¨
apitoon sek¨
a dokumentointiin.
T¨
ass¨
a tutkielmassa k¨
asitell¨
a¨
an websovelluskehitt¨
ajien kokemuksia Storybookin k¨
ayt¨
os-
t¨
a suunnitteluj¨
arjestelmiss¨
a sek¨
a raportoidaan havaintoja kyseisest¨
a ty¨
okalusta ja sen
k¨
ayt¨
ost¨
a. Kehitt¨
aj¨
akokemuksia tarkastellaan komponenttien suunnittelun, ohjelmoin-
nin, ja testauksen n¨
ak¨
okulmista. Jokaista kehitysaluetta taustoitetaan Storybookin ta-
valla l¨
ahesty¨
a sit¨
a ja t¨
at¨
a seuraa raportoitu tapaustutkimus Storybookin k¨
aytt¨
amisest¨
a
yksitt¨
aisess¨
a ohjelmistoyrityksess¨
a kyseisen kehitysalueen teht¨
aviss¨
a. Lopuksi muodos-
tetaan havaintoja sek¨
a Storybookista ett¨
a kehitt¨
aj¨
akokemuksista.
Loppukeskustelussa ja -p¨
a¨
atelm¨
ass¨
a esitet¨
a¨
an ja perustellaan nelj¨
a havaintoa Story-
bookista ty¨
okaluna. Ensinn¨
akin Storybook mahdollistaa l¨
ahestytt¨
av¨
an komponenttien
ty¨
ost¨
amisen. Toisekseen Storybookista saa my¨
os monipuolisen komponenttidokumen-
taatioalustan. Kolmannekseen Storybookille l¨
oytyy laaja lis¨
aosakokoelma jolla ty¨
oka-
lun ominaisuuksia voi rikastaa. Nelj¨
anten¨
a havaintona todetaan ett¨
a Storybookin laa-
jamittainen k¨
aytt¨
o vaatii kehitt¨
aj¨
alt¨
a merkitt¨
av¨
a¨
a ty¨
opanostusta sek¨
a k¨
aytt¨
o¨
onotto-
ett¨
a yll¨
apitovaiheessa. Kehitt¨
ajien yleisvaikutelma Storybookista oli my¨
onteinen.
Avainsanat: kehitt¨
aj¨
akokemus, komponenttil¨
aht¨
oinen webkehitys, k¨
aytt¨
oliitty-
m¨
a, Storybook.js, suunnitteluj¨
arjestelm¨
a
Kieli: Englanti
3
Contents
1 Introduction 6
2 Storybook.js 8
2.1 An overview of Storybook .......................... 8
2.2 Storybook-supported frontend web frameworks and libraries ....... 8
2.3 Brief history of Storybook .......................... 10
2.4 Storybook add-ons .............................. 10
2.5 A note on design system development tasks and Storybook ........ 11
3 Designer-developer-handoff using Storybook 12
3.1 Designer-developer handoff .......................... 12
3.2 Embedding designs into Storybook ..................... 13
3.3 Case Universal Avenue: improving designer-developer handoff ...... 13
3.4 Summary of using Storybook with design tools ............... 14
4 Component-driven programming using Storybook 15
4.1 Isolated component-driven web development ................ 15
4.2 Case Eficode: implementing design system components .......... 19
4.3 Summary of component programming with Storybook ........... 25
5 Component testing using Storybook 26
5.1 Design system as a single point of failure for an organization ....... 26
5.2 Testing in Storybook ............................. 27
5.3 Visual tests .................................. 27
5.4 Functionality tests .............................. 28
5.5 Accessibility tests ............................... 28
5.6 Case Stratio Automotive: optimizing approval time of UI tests ...... 29
5.7 Summary of component testing with Storybook .............. 30
6 Discussion 32
6.1 Approachable component exploration .................... 32
4
1 Introduction
Modern design systems1were initially born from the idea of establishing consistent visual
styles and uniform typography in the early era of graphic design [41]. Through intensive
corporate branding and the revolution of digital platforms in the mid-20th century,
design systems now had to accommodate web technology development and scale better
than before [41]. This gave traction to web development frameworks such as Bootstrap,
Foundation, and Material Design that offered pre-defined code components2, layouts and
styling that anyone could use in their development [41].
Meanwhile as design systems were becoming more digital, component-driven programming
tools like React, Vue, and Angular emerged. These tools helped developers break down
their user interface development into simpler reusable elements, components. Identifying
and aggregating user interface designs, code, and tests into components with manageable,
limited responsibilities allowed developers to maintain and scale their user interfaces
more easily. It soon became clear that design systems had to become compatible with
component-driven web development.
However, as user interfaces and design systems continued to grow in complexity, so
did the number of their components. Mature projects can even contain hundreds of
components [29]. Even more distressingly, modern user interfaces have to work in a wide
variety of execution contexts, such as different device viewports and browsers, but also
simultaneously meet accessibility and performance criteria [29]. The already overextended
design system component collections now had to support multidimensional component
variants to account for these use contexts. Especially in larger projects it quickly became
difficult for developers to organize their components effectively and to pay individual care
to each component and its variants.
This rising complexity in design system development called for more effective tools.
Currently, Storybook.js (also plainly referred to as Storybook), is one of the most popular
web development frameworks for building component-driven design systems. Storybook
is based on the idea of bringing together every aspect of design system development from
design previewing to automated code component testing, while limiting development
complexity by isolating each component and its variants into a separate development
context.
This study will introduce Storybook as a tool to the reader in Section 2, report on web
developer experiences on using the tool in Sections 3,4and 5, and finally argue for the
1Design systems are collections of reusable components, guidelines and assets for user interface
development. They help develop consistent and cohesive UIs.
2In this thesis the term ’component’ always refers to a JavaScript function component that returns
JSX, such as a React component.
6
utility of Storybook in component-driven design system web development based on the
tool study and the developer experiences in Section 6. The thesis will thus answer the
following research questions:
1. What is Storybook and what features does it offer?
2. How have web developers used Storybook?
3. What reasons are there to use or to not use Storybook?
I hypothesize that Storybook can help control and maintain especially larger-scale design
system development, as well as improve designer-developer handoff. This hypothesis is
based on my personal experiences using Storybook for a small hobby project. During
that project, I saw a lot of potential in using Storybook for detailed frontend component
development. However, I also felt that Storybook took too much effort to configure for
my smaller web application of five components.
7
2 Storybook.js
This section briefly introduces Storybook and its history to the reader before the following
sections expand the tool study. This section also lists some of the web programming
frameworks and libraries that Storybook supports and introduces the add-on-concept of
Storybook that largely defines the tool’s capabilities.
2.1 An overview of Storybook
As characterized by Chromatic, some of the developers behind Storybook themselves [19]:
”Storybook is a frontend workshop for building UI components and pages in isolation.
It helps you develop and share hard-to-reach states and edge cases without needing
to run your whole app. Thousands of teams use it for UI development, testing, and
documentation. It’s open source and free.” At its core Storybook is simply a code library
available as an npm package. However, as opposed to the React library which is used
as a framework to program JSX components, Storybook is not used to directly write
component code but rather as a separate rendering and showcasing environment for the
components, separated from the React application context. In fact, Storybook supports
components written in many other frameworks than React. Figure 1showcases the
Storybook environment briefly.
2.2 Storybook-supported frontend web frameworks and libraries
Storybook is a relatively young developer-oriented frontend workshop, so it is no wonder
that it supports many modern frontend web frameworks and libraries. At the time
of writing in May 2024, the latest stable Storybook version 8.0 provides support for
practically all of the popular frontend development technologies. This includes but is not
limited to the relatively older React, Vue, and Angular but also the newer Svelte, Qwik,
and Solid [29]. Even though Storybook is more naturally used with component-driven
web programming libraries like React, it also supports plain HTML [29].
Likewise, Storybook is not selective regarding the supporting tools or libraries used to
facilitate component development. For example, Storybook offers support for TypeScript,
hot module replacement3, and various CSS tooling such as TailwindCSS, Sass, and
Bootstrap [22]. To render components correctly, Storybook might, however, require the
developer to customize the configuration and setup options manually [22]. Many of the
most common configuration processes have already been documented.
3Hot module replacement enables updating code modules instantly in a running application without
a full reload, thus also retaining application state [51].
8
Figure 1: The Storybook environment runs in a port separate from the frontend
application hosting it. It features a graphical UI for component exploration,
workshopping, and running tests. The sidebar on the left is used to search and navigate
subpages of Markdown documentation and component views. In the example view above
[12], the developer has selected to inspect the ’No selection’ variant of the TimeFrame
component, which is rendered on the right, isolated against a blank white canvas. The
addon panel at the bottom features additionally configured inspection and testing tools
[13].
9
2.3 Brief history of Storybook
Storybook was initially developed and launched by Kadira, a Sri Lankan startup in April
2016 [45]. Kadira as a startup was known for its active contribution in the Meteor4
open source community [45]. After the release of version 1.0, Storybook matured from
a React-bound tool to a framework-agnostic development platform that featured add-
ons for component design, testing, and documentation, developed by the open-source
community [45]. Storybook enjoyed great technical and popularity growth during the rest
of 2016 [45] until Kadira shut down in December 2016 due to ”personal and professional
circumstances [45]”.
The closing down of Kadira resulted in stagnation in Storybook development as there
was no one to manage and coordinate the Storybook development by the open-
source community [45]. Shortly after, the community took charge of the development
maintenance, led by Norbert de Langen and Michael Shilman [45]. The five top
maintainers, including de Langen and Shilman, form a steering committee of engineers
at Chromatic5, JetBrains and ClimaCell that oversees the Storybook open-source
development [21]. Fueled by the revitalized open-source community, Storybook has
grown to support multiple frameworks and featured performance and user experience
improvements [45]. The most recent version, Storybook 8.0, featured among other
improvements faster builds, and React Server Component support [44].
2.4 Storybook add-ons
A key feature of Storybook is its extensibility through open-source-developed add-ons [13].
Add-ons are separately installed code dependencies that can be configured to customize
and extend the default Storybook view and inspection features. Add-ons help developers
with component programming, data, and state handling, testing, and styling as well as
organizing the Storybook content [14]. The three types of add-ons are essential, core, and
community add-ons [13]. Essential add-ons are developed by the Storybook core team and
they ship by default for new Storybook installations [13]. Core add-ons are developed by
the core team and they are thus kept in sync with Storybook development [13]. However,
the core add-ons have to be installed and configured separately. Finally, community
add-ons are all other add-ons that are developed by the open-source community [13].
4Meteor.js is a full-stack JavaScript platform offering integrated tools and libraries for application
development [49].
5Chromatic is the open-source-driven software company that most notably maintains Storybook.
10
2.5 A note on design system development tasks and Storybook
Typically the whole process of implementing a design system includes the tasks of creating
an interface inventory, designing and defining layouts, styles, and components through
style guides, building matching code components, and documenting both designs and
written code [50]. Often separate designers define style guides which developers then
implement in code resulting in a distinct designer-developer-handoff task. As Storybook
is not a design tool, this thesis will only inspect the tasks of designer-developer-handoff,
component programming, and documentation and the additional task of component
testing.
11
3 Designer-developer-handoff using Storybook
Most often design system component development is based on separately created design
files. These designs, which are created by designers using distinct design tools like Figma6
have to be converted into program component code in some manner. The process
of equipping developers with the required knowledge of the component requirements
and designs is called a designer-developer handoff. A vital tool and approach choice
in design system development thus concerns facilitating a smooth designer-developer
handoff. This section explores Storybook’s compatibility with design tools and reports on
issues a Swedish software company called Universal Avenue encountered in their designer-
developer handoff and how they could use Storybook to improve their handoff process.
3.1 Designer-developer handoff
Feng and Zhang [32] define designer-developer handoff as the process in which designers
prepare their graphical work for developers to implement in code. Software companies
that employ designers and developers as separate people, might organize a distinct handoff
to export design files and share knowledge. However, in the case of a single person acting
both as a designer and a developer, a handoff can still be considered present in the form
of a transition from the design environment into the programming environment.
Common design tools such as Figma and Sketch additionally support a smoother handoff
with features such as precise, CSS-quantifiable graphical specifications and interactive
prototyping [32]. Most notably Figma is tackling the handoff process head-on with their
togglable Developer Mode. Developer mode allows frontend programmers to explore
Figma designs akin to browser inspection, generate program code snippets for styling,
and to organize the handoff process itself [34].
Despite the handoff features design tools offer, Feng and Zhang [32] argue that distinct
handoffs always present fundamental risks for issues such as duplicated work, diverging
designs and implementation, and collaborative breakdown. Thus, they propose a more
collaborative approach in which the designers and developers co-create the user interface
components in a common tool platform. Feng and Zhang [32] do encourage the use of
interactive frontend development platforms such as Storybook and note that designers
are beginning to experiment with Storybook when building design systems. However,
Feng and Zhang [32] still find Storybook in particular developer-centered, even if it is a
step in the right direction for the future of developer-designer collaboration.
6Figma is a collaborative design and prototyping software that offers features for content styling,
alignment and design reuse through componentization [33].
12
3.2 Embedding designs into Storybook
Storybook does not strongly advocate any specific component design approach or tool.
In their Introduction to Design Systems tutorial, Chromatic even focuses solely on the
component programming, testing, and documentation tasks and does not account for
component designing [16]. The Storybook maintainers have, however, developed a Designs
add-on that allows developers to embed their static design previews into the add-on panel
[5]. The designs can be images, iframes, or web links. One of the most common uses
is embedding Figma files, pages, or frames through links which is why the add-on even
offers a specific ”figma”-design type [5].
3.3 Case Universal Avenue: improving designer-developer handoff
In 2020, Davidsson and Hennings [30] investigated design system implementations at a
company called Universal Avenue (currently known as Velory) in their Master of Science
thesis ”Designing an Implementation Support Framework for Design Systems”. The
authors used constructive design research to examine the current design system working
processes through employee interviews, workshops, benchmarking, and observations [30].
As a result, they provided Universal Avenue with insights to improve the developer
experience on design system projects and revised guidelines for future design system
development [30].
Universal Avenue is a Swedish medium-sized web development company that provides
a digital platform service for business-to-business companies and small to medium-sized
enterprises [30]. In 2020, at the time of the research, Universal Avenue consisted of 50
people located in the cities of Gothenburg and Stockholm [30]. The product teams were
divided into five subteams, each including a designer, at least two frontend developers,
a backend developer, and a product owner [30]. Most designers additionally had some
programming skills [30].
To support their product development, Universal Avenue had already implemented a code
component library hosted in Storybook, but they had not integrated its development with
the design process [30]. This led each product subteam to update the component library
in their own, unstructured manner, resulting in component inconsistencies and working
inefficiency, eliminating the Storybook’s purpose as a single source of truth [30]. The
designers at Universal Avenue were using Sketch with a consistent design component
library, but their issue was that they had not identified tools to help synchronize the
Sketch design library with the Storybook code component library. They had noticed that
as the complexity and the size of the product development work grew, the difference gap
between the graphical and the code libraries grew as well [30]. These observations are
13
very similar to the ones the Storybook maintainers have made to motivate the use of
Storybook [29], as mentioned in Section 1of this thesis.
As one of their main findings regarding designer-developer handoff, Davidsson and
Hennings identified that Storybook was not utilized in its intended manner as a single
source of truth [30]. For example, not all UI library code components were previewable
in the library Storybook. This meant that designers viewing the Storybook did not
always have direct access to the visual presentation of the code components. Another
issue the authors identified was that the UI library code components had evolved too
specific to support the needs of different products [30]. The components were thus not
reusable and crowded the library Storybook. Combined with the lack of automated
Sketch design integrations, these factors made it tiresome to maintain the Storybook.
Inactive Storybook maintenance further led to evolved inconsistencies in the Storybook
and decreased usefulness of the code component library.
In their revised design system suggestion, Davidsson and Hennings proposed that
Universal Avenue could use their Storybook as common component documentation for
both designers and developers [30]. They also suggested that the Sketch designs and
Storybook documentation must be synchronized to avoid diverging design and code
libraries. To reduce the maintenance work required, Universal Avenue could leverage
the Storybook Designs add-on, which also supports importing Sketch designs, and/or the
storybook-addon-sketch, which exports Storybook stories as a Sketch file [37].
3.4 Summary of using Storybook with design tools
The Universal Avenue case example goes to show that Storybook is only truly useful when
it is synchronized and kept up-to-date with the design environment, which often requires
additional effort. However, Storybook does offer support for design documentation and
importing design previews using the Designs add-on. Finally, while Storybook is still very
developer-centered, it is a step in the direction of developers and designers sharing a tool
platform in design system development, which according to Feng and Zhang could be the
future of designer-developer-collaboration [32].
14
4 Component-driven programming using Storybook
This section explains on a general level what isolated component-driven web development
is and how Storybook can support this approach to frontend development. The section
concludes with a report on developer experiences on programming React components in
the Storybook platform. The experiences are drawn from a design system project by the
Finnish software company Eficode.
4.1 Isolated component-driven web development
One popular way to build web user interfaces is the component-driven approach. First,
the developer identifies reusable atomic components such as buttons and inputs in the
user interface design [6]. Next, they combine them to create more complex composite
components, such as forms and tables [6]. Using the atomic and composite components
the developer finally assembles the service pages and connects them to the business logic,
backend APIs, and other services [6]. Figure 2highlights two example components within
a web application user interface.
Figure 2: This example user interface of the web commerce platform Shopify contains
identifiable components such as the circled Navigation and DataTable components [46].
In this figure, the circled component variations reside in the Shopify ’Search & Discovery’
subpage application context.
The main motivations for component-driven development lie in its flexibility, efficiency
15
through reusability, and eased debugging as the application logic is separated from
the user interface [6]. In addition, the approach allows developers to implement tests
on various levels in the user interface, ranging from unit tests for atomic components
to interaction tests for service subpages. Component-driven web development is also
straightforward to parallelize, as different components can often be developed by different
independent subteams simultaneously [6]. It is important to note that though popular,
component-driven development is not the only approach to frontend web development.
The development process could instead follow a page-based approach, in which case
common elements across pages are not as reused or there might not be any [6]. Some
popular content management systems7like WordPress and Drupal do not entertain the
idea of component-driven development either [6].
More often than not, however, these kind of code components are developed in the
application context, such as rendered on an application page. Within a page context,
however, reusable components naturally display only a subset of their possible states.
For example, some pages might only contain ’cancel’-variations of an atomic button
component, while on some other pages, there exists ’submit’-variations of the same
component that are styled and labeled differently. The developer then has two choices to
implement both component variations: they can a) work on the variations separately on
their respective page contexts, or b) temporarily create an instance of the sibling variant
on either page to work on them simultaneously. Neither of these approaches comfortably
supports context-free component development. What if instead of two variations there
were 20, located across 10 distinct pages? Moreover, the application render context
and residing business logic often influence the development of purely presentational
components, which become tainted with application logic and lose their reusability.
To tackle the issue of development context tainting component reusability, Storybook
offers an isolated component-driven development environment. By rendering the code
components in a separate environment during development, the developers can focus
on first creating application context-free components, and then plant them into their
service-specific frontend application. Examples of isolated component development views
in Storybook are showcased in Figure 3.
7Content management systems abstract away the technical infrastructure and programming tasks of
website development. The developers can instead focus on creating and organizing the website content.
16
Figure 3: In the Shopify Polaris design system Storybook environment, the components
are rendered isolated from the application context presented in earlier figure 2. The left
subfigure showcases the development view for a variation of the Navigation component.
The right subfigure presents the view for the default variation of the DataTable
component. The developer-programmed components themselves are circled in red, and
everything else, including the component navigation on the left-hand side and the
accessibility testing tool, are set up by Storybook according to the configuration files
[48].
The rendering of components in Storybook is controlled through implementing stories
[23]. Storybook recommends defining stories in separate files, so for example the stories for
the Shopify DataTable.tsx component would be defined in DataTable.stories.tsx. A
story file usually imports the component code, defines a meta object to configure necessary
rendering, and exports all the variants of the component as separate instances [23]. The
story thus acts as the render context of the component in the Storybook environment and
provides a customizable, isolated sandbox environment in which to develop, document,
and test the component variants. Examples of what story-files contain on code-level are
presented in Figures 4and 5.
17
1impo r t R ea ct , { u s eC a ll ba c k , u se S ta t e } f ro m ’react’;
2impo r t t yp e { C om p on e nt M et a } f r om ’ @ s t or y bo o k / r ea c t ’ ;
3impo r t { Leg a c yCard , D ataTa b le , Link , P a ge } f rom ’ @ sh o p if y / p o la r i s ’;
4
5expo r t d efault {
6c om p on en t : D at a Ta bl e ,
7parameters: {
8a 11 y : {
9c on fi g : {
10 r ul e s : [{ i d : ’ s c r ol l ab l e - r e gi on - f o c us a b le ’ , e n ab le d : false}] ,
11 },
12 },
13 },
14 } as C o mp on e nt M et a < t y peof DataTable >;
15
16 e xp or t f un cti o n D ef au lt (){/ * . . . * / }
17 expo r t f u nction So r t a bl e ( ) { /* .. . */ }
18 expo r t f u nction WithFooter() {/ * ... */ }
19 // . . . etc
Figure 4: An extract from the Shopify Polaris DataTable.stories.tsx file that is used
to set the Storybook environment shown in Figure 3[47]. The file first imports necessary
React and Storybook modules, as well as some of the components themselves. The
default export for story-files is reserved for configuring the Storybook component-specific
meta settings. The rest of the exports correspond to the component variations which are
defined using the imported components.
18
1e xp or t f un cti o n D ef au lt ( ) {
2con s t rows = [
3[’ E me r a ld S il k G o wn ’ ,’ $ 87 5 . 00 ’ , 1 24 68 9 , 1 40 , ’ $ 122 , 50 0.0 0 ’],
4[’ Mauve C a s h m ere Sca r f ’ ,’ $ 23 0 . 00 ’ , 1 24 5 33 , 8 3 , ’ $19 , 09 0. 00 ’]
5];
6
7retu r n (
8< P ag e t i t le = " S a le s b y p r od u c t " >
9<LegacyCard >
10 <DataTable
11 columnContentTypes={
12 [’ t ex t ’ ,’numeric ’,’numeric’,’numeric’,’numeric’]
13 }
14 h ea di ng s ={
15 [’ P ro d u ct ’ ,’Price’,’ SK U N um be r ’ ,’N et q ua nt ity ’ ,
16 ’ Ne t s al es ’ ]
17 }
18 r ow s ={ r ow s }
19 t ot al s = {[ ’’,’ ’ ,’ ’ , 2 55 , ’ $1 55 , 83 0. 00 ’ ]}
20 />
21 </LegacyCard >
22 </ P ag e >
23 );
24 }
Figure 5: A closer look into the ’Default’-named function export of the
DataTable.stories.tsx shows that the component variations that appear in the
Storybook environment are simply exported instances of the components. As the default
variation of the component should be its most basic essence, only the necessary data
props are passed to the DataTable component.
4.2 Case Eficode: implementing design system components
In 2021 Kalermo [36] showcased the implementation process of a Storybook design system
development environment at a company called Eficode in his Bachelor’s thesis. The thesis
discussed the importance and role of design systems in general, but more importantly, it
focused on depicting how to approach creating a Storybook from a ready-made Figma
design system [36]. The Eficode design system project was intended to produce three
main products [36]:
1. A Figma design library for designers
2. A React-based Storybook for developers and designers
19
3. Documentation to help new project members set up the Storybook design system
Eficode Oy is a Finland-originated software company that at the time of Kalermo’s thesis
employed over 300 people across seven countries [36]. The company sells digital services,
and software consulting and specializes in DevOps. The design system, however, was
intended for internal use to support frontend development work indirectly in customer
projects [36]. The design system project included two employees: a design system-
experienced designer and a code component developer [36].
The design system project began by deciding on a technology and tool stack. The project
team chose React supported by Next.js due to the familiarity of React and the server-
side-rendering capabilities of Next.js [36]. Additionally, the team decided to build the
design system on top of an existing component library. This decision was driven by
the desire to save time in component programming by simply customizing ready-made
components [36]. The team chose the Material UI component library for this purpose,
mainly due to its high scoring in WCAG-criteria 8accessibility testing when compared to
other component libraries such as Carbon and Polaris [36]. The team opted for the styled-
components library to style React components similarly to the MaterialUI’s sx-prop and
styled()-utility [40].
Before beginning component development, the team decided to implement the design
system primitives in the Storybook and migrate the design tokens from Figma to the
development environment [36], as showcased in Figure 6. Design primitives define the
constant values and characteristics of a design system theme. The primitives include,
for example, the fonts, spacings, and colors used in the design system. To support the
consistent reuse of primitives, they are expressed as key-value pairs such as primaryColor
-#0000FF called design tokens. Design tokens are located on both the design and
programming levels of design system development and keeping them synchronized is vital
to maintain a one-to-one match of the designs and the component implementations. The
Eficode team decided to migrate the Figma design tokens to the development environment
as a JSON file [36], which appeared a natural choice given that JSON is a key-value data
format at heart and easy to work with in JavaScript code. Moreover, although Figma does
not support design token exporting out-of-box, there are multiple community plugins to
export tokens in JSON format, such as the Design Tokens Manager [52].
8Web Content Accessibility Guidelines are versioned international standards to enforce web
application accessibility [35].
20
Figure 6: The team additionally created separate Storybook documentation pages for
describing the design system primitives, such as the color palette displayed above. The
pages were written using Markdown with JSX [36].
After importing the design tokens, the team began implementing code components based
on the Figma designs. Kalermo identified three steps in migrating a Figma-designed
component into a Storybook-previewable MaterialUI component extension [36]:
1. Inspect both the visual look and the CSS styling of the component thoroughly
2. Locate a suitable MaterialUI component to use as base and identify the required
theming customizations
3. In a new component file: import the MaterialUI component and export a customized
copy of it using the withStyles-method and possible component property changes
Using a ready-made component library as the base for design system development
is especially efficient when creating new design systems that mainly introduce visual,
substantive, or other static extensions to the base system. In fact, the example Button
component code provided by Kalermo includes only 28 lines of code [36], of which 15
lines are non-avoidable custom CSS-styling. Considering that the Material UI Button
component includes 15 possible props to customize its by-default accessible visual look
and interactivity [39], this is a significant amount of frontend work abstracted away from
the design system developer using this approach. The approach also results in manageable
and limited-size component files. However, using a ready-made component library also
requires the developers to become familiar with the library to be able to use it. This can
present challenges especially when more detailed interaction changes or new states are
introduced to a custom component. These changes have to be supported by the Material
UI component default implementation, which is not located at the development level
21
where the custom changes are implemented. Additionally, the more a developer leans
on ready-made library solutions and stylings when building their components, the more
dependent the resulting design system is on the used libraries and how they are kept
up-to-date.
When defining the Storybook stories for the design system components, the Eficode team
also utilized the Storybook Controls add-on [36]. The Controls add-on offers developers
a graphical UI to tinker with the different component property values within a story
environment without modifying the story source code or adding new stories [7]. According
to Kalermo, the Controls add-on was intended to be used for manual testing of the
different component property values [36]. Additionally in his thesis, he proposed that
the Controls interface add-on could also help showcase component functionality to non-
programmers such as designers or clients who are not equipped to modify the story code
configurations to explore component variations [36]. While the Storybook documentation
also advocates some manual testing of components [25], the more consistent approach is
to test for component property variations through automated testing. On the other
hand, Kalermo’s argument that it is easier for designers to explore Storybooks using
the Controls add-on [36] appears justifiable and could be helpful in developer-designer
collaboration and maybe even early stage within-Storybook component workshopping.
Figure 7illustrates how Eficode configured the Controls add-on for a specific component
and Figure 8showcases what the add-on looked like in their Storybook environment.
1expo r t d efault {
2t it le : ’ C o m po n e nt s / B u tt o n ’ ,
3c om p on en t : P ri m ar y Bu tt o n ,
4argTypes: { children :
5{ c on t ro l : ’ t ex t ’ } , d is a bl e d : { c on t ro l : ’boolean’ }
6},
7};
8expo r t c o ns t P r im a ry = ( a r gs ) = >
9< P r im a r y Bu t t o n { . .. a r gs } > < / P ri m a ry B u tt o n >;
10
11 P ri m ar y . a rg s = {
12 children: ’ T e xt ’ ,
13 disabled: false
14 };
Figure 7: The Eficode team configured the Storybook controls for the Button component
by first defining its argument types in the default-exported Meta object, and then setting
a default-valued object for the args-property of the Primary-story [36].
22
Figure 8: This is the Controls addon interface for the Button component within the
Eficode Storybook [36]. With the Primary Button story open, the developer could then
freely alter what is displayed inside the button through the children argument as well
as toggle its disabled state. The ’Actions’ and ’Accessibility’ subpages contain other
Storybook add-ons which are touched on in Section 5.
For Kalermo, the overall impression of using Storybook for design system implementation
was positive [36]. He was especially enthusiastic about the Storybook-provided component
isolation and he argued that developing in isolation can help avoid breaking the
application context by accident [36]. Kalermo additionally highlighted the documentation
capabilities of Storybook, which combine JSX-supported Markdown, component rendering,
and interactivity to depict how the components behave [36]. Kalermo also appreciated
the add-ons available for Storybook [36]. He proposed that the Accessibility add-on,
which automatically flags any WCAG accessibility criteria violations, should be included
in the Essentials add-ons that are configured by default for Storybook [36]. He argued for
this by stating that fully accessible websites are rapidly becoming the new norm [36]. For
the Eficode design system project, Kalermo stated that the Accessibility add-on helped
make sure that the accessibility of the MaterialUI components was not broken as they
were customized [36].
Even though the basic elements of a Storybook, such as the component navigator
and the accessibility add-on do not require additional configuration, it is clear from
the Eficode case study that the Storybook environment can be customized in many
ways. For example, Figure 9showcases the Eficode Storybook which contains paginated
documentation for the design system primitives as well as for getting started. These are
followed by the component directory which is organized and named by the story-files the
developers themselves create. Developers also choose the Storybook add-ons they find
meaningful to include in their workspace and configure them to support their individual
development. In Eficode’s case, these were the Controls and the Accessibility add-ons. It
is thus important to note that there are different ways to set up Storybooks.
23
Figure 9: The Eficode design system Storybook with the Primary Story of the Button
component open [36]. The left-hand side displays the documentation and component
navigator as specified by the developers and the bottom add-on toolbar showcases the
add-ons configured for the environment.
The Eficode team could have also benefited from the Designs add-on mentioned in
Section 3as Kalermo stated that the Figma designs needed to be inspected thoroughly
throughout the development process [36]. He did mention, however, that inspecting the
CSS attributes of the designs was equally helpful [36], which the Designs add-on does not
support.
24
4.3 Summary of component programming with Storybook
The number of web frameworks and libraries Storybook supports [29], combined with all of
the add-ons, story configuration, and content arrangement possibilities, make Storybook
a flexible, functionality-rich programming environment that can also take time to set
up and document thoroughly. The only real requirement for the design system code
implementation is that the system must be divisible into code components, each connected
to a story export, which is then rendered in isolation within the Storybook. The rest of the
environment often naturally conforms to the design system content and its development
requirements, such as testing, documentation, and design criteria. However, freedom
of configuration also introduces the possibility of difficult-to-navigate or to-understand
Storybook development environments. Additionally, the more add-ons, controls, or
content pages are included in a Storybook, the more work it is to set it up and maintain
it. It also takes more effort to become familiar with the development environment and
Storybook itself.
25
5 Component testing using Storybook
This section first discusses the importance of testing design systems which act as single
points of failure in software development organizations. Then the section presents
tools Storybook offers for component testing. Following this, visual, functionality, and
accessibility tests in Storybook are inspected in further detail. The section concludes with
an analysis on developer experiences of using Storybook as a user interface component
testing tool at a Portuguese software product company Stratio Automotive.
5.1 Design system as a single point of failure for an organization
Testing components to assure quality and consistency is vital in design systems that are
heavily visual, interactable and often represent the digital brand of the service to the user.
While frontend bugs are generally not considered service-breaking, the business costs
and the security risks that appear in poorly designed and implemented user interfaces
are considerable [43]. For example, an e-commerce site with a convoluted checkout
process or pages that load slowly can lead to customers abandoning their shopping carts,
directly decreasing user engagement, resulting in loss of sales [43]. Other monetarily
harming consequences of poor user experiences include increased customer support costs,
negative word-of-mouth, reduced user conversion rates, and increased development and
maintenance costs [43]. There also exist many frontend security vulnerabilities such
as cross-site scripting, cross-site request forgery, and using outdated dependencies that
malicious attackers can exploit.
Dominic Nguyen, one of the founders of Chromatic, also highlighted in his blog post
back in 2018 how design systems act as single points of failure for many organizations
[42]. He describes design systems as double-edged swords, in that they allow for cheaper,
consistent, and scalable UI delivery through component reuse while also exposing every
application using a design system to its bugs [42]. Especially in widely used design
systems a single bug, unnoticed in isolated development, can quickly manifest itself in
multiple applications. As the applications using the design system are complex the bug
can cause unexpected and varying application behavior, making it much more difficult to
track down the bug for the application developers than the design system developers [42].
Additionally, if a bug slips through the design system testing process and into applications
using the system, it is also likely being tracked down by multiple independent teams
concurrently, resulting in duplicated working effort.
26
5.2 Testing in Storybook
To combat software faults, Storybook supports a variety of automated testing tools and
types of tests [25]. Often the first step in implementing tests is to replicate the component
and/or the application context of the test. As these are readily defined within stories,
Storybook supports developers running their tests against stories. One of the most
important testing tools is thus the story format itself. This allows developers to focus on
writing the testing scenarios instead of the contexts. The Storybook testing guide infers
three main test types to use: visual tests, functionality tests, and accessibility tests [25].
5.3 Visual tests
Visual tests focus purely on pixel-level-appearance bugs. They work by capturing a visual
screenshot of a story and comparing it to an earlier screenshot that has been accepted as
the visual baseline for the story [27]. Storybook maintainers have developed a separate
tool called Chromatic for this visual testing [27]. After first configuring visual tests as
an add-on, developers have to sign up for Chromatic as well and create a project there
[27]. This is to say, while developers do not write visual tests themselves, they need
to set up a Chromatic project and Chromatic users for each developer. Visual tests do
not, however, require developers to write or maintain any code. The Chromatic tool can
help developers spot even the smallest visual changes and force them to pay attention to
changes in the appearance of the component as showcased in Figure 10.
Figure 10: After running visual tests, the developer is shown the current component
(orange bars) versus the most recent visual baseline (green bars) and asked to either
accept the new baseline or modify the story to match the most recent baseline [27].
27
5.4 Functionality tests
Functionality tests that Storybook supports include unit tests for functionality, Storybook-
instrumented Interaction tests that simulate actions and inspect state, and end-to-end
tests for simulating actual user scenarios and flows [25]. For unit tests (Jest, Testing
Library, etc.) defined separately from stories, the developers can import and render their
full stories using the composeStory and composeStories -helper methods [26]. Likewise
separately defined end-to-end-tests (Cypress, Playwright 9) can access the rendered stories
as iframes [18]. Story and test integrations are also supported the other way around. The
developer can define a play method for a story that will execute after the component
has rendered [18]. The play method can thus be used to configure interaction testing
[18]. Interaction tests are defined directly in the play method of a story, and they use
the @storybook/test-library. There also exists an Interactions-add-on to run interaction
tests visually within the Storybook environment [20]. The add-on also enables step-by-
step running of the tests both forward and backward [20]. Additionally, Storybook offers
a Test runner that runs all defined stories as executable tests by checking that each story
renders without errors and that the assertions in their play functions pass [24].
Through tools like the story play function, Test Runner, and Interactions-add-on,
Storybook makes an effort to support multiple testing frameworks and ways of writing
tests. It does however appear that the most Storybook-compatible tests are the
Interaction tests. This is because they are written within the story files themselves, using
the @storybook/test-library, and can be inspected both visually through the Interactions
add-on or run in CLI with the Test Runner [20]. However, also supporting story imports
in separately defined unit- and end-to-end-tests probably helps avoid rewriting tests in the
case that a component library project migrates into using Storybook mid-development
when some tests have already been created. The fact that Storybook testing can be
conducted within stories or in separate tests also adds another layer of complexity,
learning, and decisions to make in the configuration process of Storybook.
5.5 Accessibility tests
In Storybook the a11y accessibility testing add-on allows developers to catch accessibility
violations in the rendered DOM of a story [2]. The Storybook accessibility testing
documentation defines accessibility as ”the practice of making websites inclusive to all.
That means supporting requirements such as keyboard navigation, screen reader support,
touch-friendly, usable color contrast, reduced motion, and zoom support.” [3]. With 1.5
million downloads [14], the a11y accessibility testing add-on is in fact one of the most
9Cypress and Playwright are common end-to-end testing frameworks for modern web applications.
28
popular add-ons outside the Essentials-add-ons which are included in every Storybook
by default. The accessibility violations are flagged by the add-on based on some set of
universally recognized WCAG (Web Content Accessibility Guidelines) rules [3]. Out-
of-box the a11y add-on uses the Axe-core accessibility testing engine, which reportedly
detects on average 57 % of WCAG issues [31]. The default Axe-core accessibility rules
can also be overridden in Storybook by defining some rules explicitly in the a11y add-on
configuration either globally, on a component-level or story-level [3].
Configuring the a11y add-on is a simple but effective way of paying more attention to
accessibility violations during development. Configuring the add-on with the default
WCAG rules is as easy as installing the add-on and adding it among the other add-ons
in the global Storybook configuration file [3]. After that, the accessibility testing appears
in the add-on panel and the tests are automatically run whenever a component changes.
The more difficult part is knowing how strict of a WCAG ruleset to use for flagging
accessibility violations, and when is it necessary to override some of the default rules set
by the underlying Axe-core testing engine.
5.6 Case Stratio Automotive: optimizing approval time of UI tests
In 2023 Marques [38] from the University of Coimbra, Portugal, streamlined the user
interface testing process at a software company using Storybook [38]. The company in
question was Stratio Automotive, a software product company that develops a digital
platform for predictive vehicle fleet maintenance [38]. Their Foresight platform is a web-
based dashboard application in which bus, coach, and truck fleet managers can monitor
the metrics and maintenance needs as well as the driver performance of each vehicle [1].
In his Master’s dissertation, Marques set out to cut down on delays in web UI testing for
the Foresight platform by introducing new testing tools and a revised acceptance process
[38]. As a result of his thesis research, Marques integrated his proposed testing changes
into the Stratio Automotive quality assurance process [38]. The improved testing process,
which also featured Storybook, resulted in up to ten times faster test approval times at
Stratio Automotive [38].
Marques found Storybook useful for specifically component-level testing of the Foresight
Platform [38]. The UI of the Foresight application was located in two repositories: one
for storing the common frontend Angular components (akin to a design system), and one
for building the app itself using these components [38]. Marques went on to identify and
compare two alternative tools for conducting component-level testing in the component
library repository: Cypress and Storybook [38]. To choose a component testing tool
between the two, Marques conducted a frontend team meeting in which Storybook was
preferred over Cypress ”since it also displayed advantages not only for component testing
29
but also as a form of documentation for each component and accessibility analysis.” [38]
Ultimately the frontend team had reason to choose Storybook over Cypress based purely
on the testing attributes of the tools, as illustrated by Table 1. However, the comparison
between Storybook and Cypress highlights how the large add-on collection of Storybook,
consisting of integrations for documentation and diverse testing approaches increases the
tool’s attractiveness to developers [38].
Cypress Storybook
Setup Complexity 6 to 8 hours (2/5) 4 to 6 hours (3/5)
Development Cost 2 to 3 hours (3/5) 1 to 2 hours (4/5)
Documentation
Quality
Frail documentation with
only basic examples (2/5)
Covers most of the frequent
issues and theoretical
elements (4/5)
Table 1: Summary of component testing tool comparison and scoring on a scale from 1
to 5 between Cypress and Storybook conducted by Marques and the Stratio Automotive
frontend team [38].
After choosing Storybook as the driving component testing platform, Marques took note
of the diverse testing add-ons Storybook offers. In the initial Storybook environment
setup, Marques enabled the Controls add-on to allow for manual testing of UI components
by developers [38]. Next, Marques wanted to test simulated user behavior and configured
the Interactions add-on to run interaction testing based on the play functions defined
in stories [38]. After implementing interaction testing, Marques set up the Storybook
Test Runner and test coverage add-ons to automate test execution [38]. After thorough
configuration, Marques then went on to define 43 test cases across the components
[38], which undoubtedly took a long time. Marques did however find the add-on
installation processes themselves straightforward, apart from setting up the coverage add-
on which required some additional configuration to enable code instrumentation due to
the repository using Angular with Webpack [38].
5.7 Summary of component testing with Storybook
Overall Storybook offers a test-rich environment that can, however, be tedious to configure
and to maintain. The stories, in which components are in any case rendered, are a
natural place to define tests as well. Storybook supports this with its play function
which is a block of code that runs after the component has rendered [20]. One of the
main advantages of using Storybook for testing is that there are plenty of add-ons to
support diverse testing needs. Some of these are supporting add-ons like Interactions,
30
Test Runner, and story (test) coverage [14] which enhance the Interaction testing process.
In addition to these, there are add-ons to support completely different types of testing
outside traditional functionality testing such as the a11y accessibility testing and the
visual testing add-ons [14]. Even the Controls add-on that allows developers to modify
the props passed to a component directly in the Storybook environment eases manual
testing of the components.
The extensive add-on collection was something that also Marques appreciated while
streamlining the component testing at Stratio Automotive [38]. Additionally, Marques
took note of the parallelized testing efficiency, CI-pipeline compatibility using the Test
Runner and the added benefit of Storybook doubling as component documentation [38].
Marques did however consider that complex applications with many components can
birth uncertainty about the testing responsibilities of each story [38]. I believe this
becomes even more apparent when implementing atomic components that have little to
no interactivity and are used in other composite components. In these cases, it might not
be clear what testing should occur in the atomic and what in the composite component
story. Relating to this, Marques mentioned that ”The process of integrating Storybook
into an already existing project with a lot of applications might be challenging since there
may be some migrations to be done.” [38] I believe this applies outside testing as well
in that Storybook is more straightforward to configure and upkeep for new projects, but
much more tedious to migrate into mid-development since each existing component must
be written a story file that defines multiple variants and tests for the component.
31
6 Discussion
This section brings together observations on the Storybook tool based on its capabilities
and the developer experiences using it. There were four main observations. Firstly,
the graphical user interface of a Storybook environment offers approachable component
workshopping and documentation. Secondly, Storybook doubles well as rich component
documentation. Thirdly, there exist numerous different developer-appreciated Storybook
add-ons to further leverage the use of the tool. Finally, to fully leverage the capabilities
of Storybook, developers must spend quite a lot of effort first configuring the tool and
later creating and maintaining all of its content.
6.1 Approachable component exploration
One of Storybook’s main roles in frontend development is to offer a graphical user
interface in which to workshop on components. Rendering component variations in
isolated story subpages allows for quick browsing of the different component use cases.
This is further enhanced by the Controls add-on which allows Storybook users to directly
change the property values. Case Universal Avenue showed that even though Storybook
is a developer-centered tool, Storybooks can definitely be used by designers as well due
to the tool’s approachable graphical user interface. Storybooks can also be published
online as static web applications [12] so that anyone can inspect them without having to
set up a codebase locally or having to install any dependencies. Kalermo from Eficode
also appreciated how the components are inspected in isolation, which helped him avoid
breaking the context application itself [36].
6.2 Rich component documentation
In addition to acting as a workshopping environment, Storybook doubles well as a
documentation platform. Instead of simply showcasing how the components look visually,
Storybook environments actually render the components which allows developers to
interact with the components and try them out. While some documentation on the
properties and variants available is generated automatically by Storybook Autodocs [15],
Storybook also supports customizing the documentation with JSX-infused Markdown
[17]. Storybook’s usefulness for documentation was recognised across all case studies.
Davidsson and Hennings proposed that Storybook could be used at Universal Avenue
as the single source of truth documentation by both designers and developers. Kalermo
also stated how he appreciated the diverse and interactive component documentation
approach of Storybook. Finally, Marques and the Foresight frontend team at Stratio
Automotive were enthusiastic about Storybook doubling as a documentation tool in
32
addition to testing; this was one of the key reasons they chose Storybook over Cypress.
6.3 An extensive add-on collection
There is a large, diverse collection of add-ons to introduce extra functionality into a
Storybook which developers appreciate. The Storybook Integrations catalog showcases
community-created add-ons for coding, data, and state management, testing, styling,
and designing as well as for organizing the Storybook content and customizing the
environment appearance [14]. While most add-ons must be installed and configured
separately, the Essentials add-ons come pre-installed when first configuring a new
Storybook. They include the Actions, Docs, Viewport, and Controls add-ons among
a few other add-ons [10]. These and all other add-ons mentioned in this thesis and their
descriptions are listed in Table 2. While the listed add-ons include some of the most
popular ones [14], they are still a small subset of all available add-ons [14] developed by
the Storybook open-source community.
Especially the Eficode and Stratio Automotive projects also accepted and took advantage
of the aforementioned add-ons. While implementing the Eficode design system, Kalermo
even went on to propose that the Accessibility testing add-on should be included in default
add-ons. He also felt that Controls add-on can help non-programmers test UI components
manually as the add-on offers a graphical user interface to set component property values.
When setting up the Stratio Automotive UI component library Storybook, Marques
configured the Controls add-on for easier manual testing but also additionally set up
the Interactions, Accessibility, Test Runner, and Coverage add-ons. Neither mentioned
any major trouble in installing or setting up these add-ons [36;38].
6.4 Additional configuration and maintaining effort
Fully-utilized Storybook environments are rich in content and functionality, making
Storybooks somewhat tedious to configure and maintain thoroughly. There exists thus
a trade-off between achieving a fine-grained Storybook component library and spending
component development effort on purely maintaining the whole Storybook infrastructure.
Based on the Universal Avenue and Stratio Automotive case studies the extra effort
required stems mostly from having to write separate story-files and render variations for
each component variations. Additionally, Marques, working with Stratio Automotive,
speculated that integrating Storybook to deep-into-development projects can become
especially tedious [38]. I can see this being the case especially if developers choose to
rewrite their existing component tests as Storybook Interaction tests or if they must
reorganize their component structure.
33
Official description Pre-configured
Essential add-on
Actions ”Get UI feedback when an action is performed on
an interactive element” [4]
Yes
Docs ”Document component usage and properties in
Markdown” [9]
Yes
Viewport ”Build responsive components by adjusting
Storybook’s viewport size and orientation” [28]
Yes
Controls ”Interact with component inputs dynamically in
the Storybook UI.” [7]
Yes
Designs ”Storybook add-on for embedding your design
preview in addon panel.” [5]
No
storybook-
addon-sketch
”Get the sketch files for your stories in
Storybook.” [37]
No
Accessibility ”Test component compliance with web
accessibility standards.” [2]
No
Interactions ”Automate, test and debug user interactions.”[11] No
Test Runner ”Run component tests on stories via the command
line or CI.” [24]
No
Story
Coverage
”Generate code coverage reports for your stories.”
[8]
No
Table 2: A list of all of the Storybook add-ons that appear in this thesis and their
descriptions from the documentation pages of the add-ons.
34
7 Conclusions
In this thesis I set out to investigate the possibilities and limitations of the component-
driven design system development tool Storybook.js. I wanted to answer three research
questions:
1. What is Storybook and what features does it offer?
2. How have web developers used Storybook?
3. What reasons are there to use or to not use Storybook?
I carried out the research by combining a tool documentation study with a literature
review on developer experiences using Storybook in web software development companies.
I examined Storybook from the design system development task viewpoints of designer-
developer-handoff, component-driven programming, and component testing. I drew
developer experiences from two software product companies [30;38], the Swedish
Universal Avenue and the Portuguese Stratio Automotive, as well as from the Finnish
software consulting company Eficode [36]. All of these Storybook projects were carried
out in a web development context.
I believe this thesis answered the first research question well and the other two adequately,
although the research on questions two and three could have been expanded. I first
introduced Storybook as a tool in Section 2and later inspected it in more depth at the
beginning of each Section on a design system development task. The answers to the
second and third research questions are largely based on only three developer experience
case studies, which are written by individuals. I thus cannot argue for general answers
regarding how Storybook is used and perceived by developers globally, based on the
experiences of individuals in three software companies. Instead I present four observations
of the tool, recapped in Table 3. Through this thesis I also hope to evoke discussion about
Storybook, as not much has been written about it though the tool is widely used in the
industry.
Much further research could be conducted about Storybook as a tool. The observations
presented here could be validated or invalidated by a more extensive, perhaps more
quantitative study on Storybook experiences. Additionally, I did not inspect how custom
add-ons are built or how Storybooks are published online as documentation sites or as
npm component library packages. Some other unanswered questions that arose during
the study were:
35
•What alternative design system development tools are there to Storybook and how
do they compare?
•Would it be possible to replace the one-way designer-developer handoff with two-
way designer-developer collaboration on Storybook?
•Are there any use cases for a Storybook add-on that would use generative artificial
intelligence?
Universal Avenue Eficode Stratio Automotive
Approachable
component
exploration
Possibility: a common
workshopping
platform for
developers and
designers
Isolated development
was useful for
avoiding breaking
the application
-
Rich component
documentation
Possibility: a single
source of truth
through component
documentation
Diverse
documentation
valued: markdown,
rendered components,
interactivity
Documentation
tooling gave
Storybook an edge
over using Cypress
Use of extra
add-ons
- Controls and
Accessibility
Controls,
Accessibility,
Interactions, Test
Runner, Coverage
Experienced
configuration
and
maintenance
effort
Writing separate story
files and syncing with
designs takes effort
- Integrating Storybook
into existing projects
can be tedious
and story testing
responsibilities can
become blurred
Table 3: Summary of how the observations on Storybook were reflected in the case studies
of software companies using Storybook.
36
References
[1] Stratio Automotive. The world’s no. 1 predictive fleet maintenance platform [Online],
2019. Available at https://stratioautomotive.com/about/. Accessed on
15.4.2024.
[2] Chromatic. Accessibility [Online], 2022. Available at https://storybook.js.org
/addons/@storybook/addon-a11y. Accessed on 21.4.2024.
[3] Chromatic. Accessibility tests [Online], 2022. Available at https://storybook.js
.org/docs/writing-tests/accessibility-testing. Accessed on 11.4.2024.
[4] Chromatic. Actions [Online], 2022. Available at https://storybook.js.org/add
ons/@storybook/addon-actions. Accessed on 21.4.2024.
[5] Chromatic. Designs add-on [Online], 2022. Available at https://storybook.js.o
rg/addons/@storybook/addon-designs. Accessed on 18.2.2024.
[6] Chromatic. Component Driven User Interfaces [Online], 2024. Available at https:
//www.componentdriven.org/. Accessed on 7.3.2024.
[7] Chromatic. Controls [Online], 2022. Available at https://storybook.js.org/doc
s/essentials/controls. Accessed on 10.3.2024.
[8] Chromatic. Story coverage [Online], 2022. Available at https://storybook.js.o
rg/addons/@storybook/addon-coverage. Accessed on 21.4.2024.
[9] Chromatic. Docs [Online], 2022. Available at https://storybook.js.org/addon
s/@storybook/addon-docs. Accessed on 21.4.2024.
[10] Chromatic. Essentials integrations [Online], 2022. Available at https://storyboo
k.js.org/integrations/tag/essentials. Accessed on 21.4.2024.
[11] Chromatic. Interactions [Online], 2022. Available at https://storybook.js.org
/addons/@storybook/addon-interactions/. Accessed on 21.4.2024.
[12] Chromatic. Storybook home page [Online], 2022. Available at https://storyboo
k.js.org/. Accessed on 28.4.2024.
[13] Chromatic. Storybook addons [Online], 2022. Available at https://storybook.js
.org/docs/configure/storybook-addons. Accessed on 28.4.2024.
[14] Chromatic. Integrations [Online], 2024. Available at https://storybook.js.org
/integrations. Accessed on 11.4.2024.
37
[15] Chromatic. Automatic documentation and Storybook [Online], 2022. Available
at https://storybook.js.org/docs/writing-docs/autodocs. Accessed on
21.4.2024.
[16] Chromatic. Design Systems For Developers [Online], 2022. Available at https:
//storybook.js.org/tutorials/design-systems-for-developers/. Accessed
on 18.2.2024.
[17] Chromatic. How to document components [Online], 2022. Available at https:
//storybook.js.org/docs/writing-docs. Accessed on 21.4.2024.
[18] Chromatic. End-to-end testing [Online], 2022. Available at https://storyboo
k.js.org/docs/writing-tests/stories-in-end-to-end-tests. Accessed on
11.4.2024.
[19] Chromatic. Get started with Storybook [Online], 2022. Available at https://stor
ybook.js.org/docs/get-started. Accessed on 28.4.2024.
[20] Chromatic. Interaction tests [Online], 2022. Available at https://storybook.js.o
rg/docs/writing-tests/interaction-testing. Accessed on 11.4.2024.
[21] Chromatic. Maintainer team [Online], 2022. Available at https://storybook.js
.org/community/#maintainer-team. Accessed on 5.5.2024.
[22] Chromatic. Setup Storybook [Online], 2022. Available at https://storybook.js
.org/docs/get-started/setup. Accessed on 7.3.2024.
[23] Chromatic. What’s a story? [Online], 2022. Available at https://storybook.js.o
rg/docs/get-started/whats-a-story. Accessed on 7.3.2024.
[24] Chromatic. Test Runner [Online], 2022. Available at https://storybook.js.org
/docs/writing-tests/test-runner. Accessed on 11.4.2024.
[25] Chromatic. How to test UIs with Storybook? [Online], 2022. Available at https:
//storybook.js.org/docs/writing-tests. Accessed on 18.2.2024.
[26] Chromatic. Unit tests [Online], 2022. Available at https://storybook.js.org/d
ocs/writing-tests/stories-in-unit-tests. Accessed on 11.4.2024.
[27] Chromatic. Visual tests [Online], 2022. Available at https://storybook.js.org
/docs/writing-tests/visual-testing. Accessed on 3.4.2024.
[28] Chromatic. Viewport [Online], 2022. Available at https://storybook.js.org/a
ddons/@storybook/addon-viewport. Accessed on 21.4.2024.
38
[29] Chromatic. Why Storybook? [Online], 2022. Available at https://storybook.js
.org/docs/get-started/why-storybook. Accessed on 4.2.2024.
[30] Elin Davidsson and Theodor Hennings. Designing an Implementation Support
Framework for Design Systems. Master’s thesis, Chalmers University of Technology,
2020. Available at https://odr.chalmers.se/items/05df690d-10e1-4466-86b
d-1dcd6bf31092. Accessed on 7.3.2024.
[31] Dequelabs. axe-core GitHub repository [Online], 2024. Available at https://gith
ub.com/dequelabs/axe-core. Accessed on 11.4.2024.
[32] K.J. Kevin Feng and Amy X. Zhang. From handoffs to co-creation: Deepening
collaboration between designers, developers, and data science workers in ux design.
Proceedings of the InContext: Futuring User-Experience Design Tools Workshop at
CHI Conference on Human Factors in Computing Systems (CHI’22), 2022. Available
at https://hcibook.net/incontext/wp-content/uploads/sites/5/2022/04/F
rom-Handoffs-to-Co-Creation-Deepening-Collaboration-between-Designe
rs-Developers-and-Data-Science-Workers-in-UX-Design-1.pdf. Accessed on
7.3..2024.
[33] Figma. Figma Design [Online], 2024. Available at https://www.figma.com/desi
gn/. Accessed on 5.5.2024.
[34] Figma. Developers, meet Dev Mode [Online], 2024. Available at https://www.fi
gma.com/dev-mode/. Accessed on 7.3.2024.
[35] Shawn Lawton Henry. WCAG 2 Overview [Online], 2024. Available at https:
//www.w3.org/WAI/standards-guidelines/wcag/. Accessed on 2.5.2024.
[36] Tatu Kalermo. Building a Design System. Bachelor’s thesis, Metropolia University
of Applied Sciences, 2021. Available at https://www.theseus.fi/bitstream/han
dle/10024/503045/Kalermo_Tatu.pdf?sequence=2&isAllowed=y. Accessed on
8.3.2024.
[37] Andrew Lisowski. storybook-addon-sketch [Online], 2019. Available at https:
//storybook.js.org/addons/storybook-addon-sketch. Accessed on 7.3.2024.
[38] Pedro Marques. Optimization of approval times in web UI tests. Master’s thesis,
University of Coimbra, 2023. Available at https://estudogeral.uc.pt/retrieve
/260778/MSc_Dissertation_Pedro_Marques.pdf. Accessed on 15.4.2024.
[39] MaterialUI. Button API [Online], 2024. Available at https://mui.com/material
-ui/api/button/. Accessed on 10.3.2024.
39
[40] MaterialUI. How to customize [Online], 2024. Available at https://mui.com/mate
rial-ui/customization/how-to-customize/. Accessed on 8.3.2024.
[41] Kapil Moon. The History of Design Systems [Online], 2023. Available at https:
//bootcamp.uxdesign.cc/the-history-of-design-systems-158141b94609.
Accessed on 8.2.2024.
[42] Dominic Nguyen. Why design systems are a single point of failure [Online], 2018.
Available at https://medium.com/@domyen/why-design-systems-are-a-singl
e-point-of-failure-ec9d30c107c2. Accessed on 20.3.2024.
[43] Mohit Sharma. The Cost of Bad User Experience: Impact and Examples [Online],
2023. Available at https://medium.com/@mohituxer/the-cost-of-bad-user-e
xperience-impact-and-examples-edfbbba070. Accessed on 20.3.2024.
[44] Michael Shilman. Storybook 8 [Online], 2024. Available at https://storybook.js
.org/blog/storybook-8/. Accessed on 28.4.2024.
[45] Michael Shilman. The Storybook Story [Online], 2017. Available at https://stor
ybook.js.org/blog/the-storybook-story/. Accessed on 28.4.2024.
[46] Shopify. Shopify Search & Discovery [Online], 2022. Available at https://apps.s
hopify.com/search-and-discovery?locale=fi. Accessed on 8.3.2024.
[47] Shopify. Polaris GitHub repository [Online], 2017. Available at https://github.c
om/Shopify/polaris/tree/main?tab=readme-ov-file. Accessed on 8.3.2024.
[48] Shopify. Shopify Polaris React [Online], 2017. Available at https://storybook.js
.org/showcase/shopify-polaris-react. Accessed on 8.3.2024.
[49] Meteor Software. Why Meteor.js? [Online], 2023. Available at https://www.mete
or.com/. Accessed on 28.4.2024.
[50] Sarrah Vesselov and Taurie Davis. Building Design Systems. Springer, 2019.
Available at https://link.springer.com/book/10.1007/978-1-4842-4514-9.
Accessed on 18.2.2024.
[51] Webpack. Hot Module Replacement [Online], 2024. Available at https://webpac
k.js.org/concepts/hot-module-replacement/. Accessed on 5.5.2024.
[52] @wenjuli. Design Tokens Manager [Online], 2024. Available at https://www.fi
gma.com/community/plugin/1263743870981744253/design-tokens-manager.
Accessed on 8.3.2024.
40