This post works through the similarities and differences between the 28 Storybook Examples listed on the Storybook website. The intention is to identify patterns which Storybook projects employ, and to ultimately form an opinion on the best ways to organize and architect a Storybook application.
π What is Storybook?
Storybook describes itself in the following manner:
Storybook is a UI development environment and playground for UI components. The tool enables users to create components independently and showcase components interactively in an isolated development environment. Storybook runs outside of the main app so users can develop UI components in isolation without worrying about app specific dependencies and requirements. ~ https://storybook.js.org/basics/introduction/
Storybook serves two main functions:
- UI development environment for creating components independently of application code (domain logic, routing etc.)
- UI playground for showcasing and exploring existing components
Depending on the use case and the architecture, these two functions are employed to varying degrees by each of the Storybook Examples. Understanding the patterns shared between these examples will inform answers to the following:
At the end of this post, I will offer my opinionated answers to these questions based on study of these examples.
I would love to hear other opinions, so feel free to tweet me.
#πΏ The Examples

The official Storybook website has a listing of Storybook Examples. Since the website's code is open source, any project can open a pull request, changing this file to include their project as an example. At this time, 28 projects have done so:
- Coursera Storybook
- Grommet Storybook
- Wix Style React Storybook
- Carbon Components Storybook
- Lonely Planet Storybook
- Airbnb Dates Storybook
- Uber React-Vis Storybook
- Buffer Components Storybook
- Algolia InstantSearch Storybook
- Artsy Force Storybook
- React Native Web Storybook
Griddle Storybookcould not find storybook- Tachyons Components Storybook
- Appbase Maps Storybook
- Quran.com Storybook
- TerraEclipse Storybook
- React Event Timeline Storybook
- Semantic-UI Storybook
- Hack Oregon Storybook
- TodoMVC with Specs Storybook
- React SVG Pan Zoom Storybook
- Fyndiq Storybook
- GumGum Storybook
- Lucid UI Storybook
- Trunx Storybook
- Cosmos Storybook
- MockingBot Storybook
- Vanilla React Storybook
By studying these Storybook Examples, patterns start to appear in the design, features, and organization of the projects. The projects implementations of these patterns also varies in quality.
Here are the patterns:
π° Cover Story Pattern

The first thing I noticed when I opened each of these projects in its own browser tab, was some pages implemented what I call a Cover Story.
The projects that implemented this pattern used in a few different contexts:
πΆπ» Getting Started Cover Stories
Developer instructions to use the components or the repository
Implemented By:

π About
General information about the project to varying levels of detail
Implemented By:

βΉ Playground
A playground page where components can be altered
Implemented By:

π― All Components
A demo page showing all of the components
Implemented By:

##π€ Thoughts
I was very surprised that only 8 projects implemented this pattern. This gives the page a much higher degree of polish, as well as often serving a functional use.
It's also very easy to implement. In Hack Oregon Storybook, they changed the default import statement in .storybook/config.js to pull in a single file instead of all of them:
β Implementing the π° Cover Story Pattern
//default storybook
const req = require.context('../src', true, /.stories.(j|t)sx?$/);
function loadStories() {
req.keys().forEach(req);
}
//HackOregon
function loadStories() {
require('../stories');
}
The index file of the stories
directory can then control the ordering of the files:
//component-library/stories/index.js
//https://github.com/hackoregon/component-library/blob/master/stories/index.js
...
import Welcome from './Welcome';
import scatterplotStory from './Scatterplot.story';
...
storiesOf('Welcome', module)
.add('to Storybook', () => (
<Welcome showApp={linkTo('Button')} />
));
scatterplotStory();
#π± Menu Structure Patterns

The next patterns I observed where those of how the Menu is structured.
π List of Components Menu Structure
The simplest menu structure a Storybook project can have. Components are simply listed as a list in the Menu. The list is often not even sorted, but displays in the order in which the files where resolved by the compiler. This is the most basic type of Menu Structure, where the components are dropped into the menu willy nilly, and sorted alphabetically.
Implemented By:
- Vanilla React Storybook
- Hack Oregon Storybook
- Coursera Storybook
- Semantic-UI Storybook
- Lucid UI Storybook
- Carbon Components Storybook
- Grommet Storybook
- Cosmos Storybook
- Fyndiq Storybook
- MockingBot Storybook
- Lonely Planet Storybook
- Buffer Components Storybook
- Tachyons Components Storybook
- Algolia InstantSearch Storybook
- Quran.com Storybook

π Categories Menu Structure
Menu Items are grouped into different categories. By far the most flexible and scalable solution, it also takes significantly more effort to organize the information architecture.
Implemented By:
- Wix Style React Storybook
- GumGum Storybook
- Trunx Storybook
- React Native Web Storybook
- Artsy Force Storybook
- TerraEclipse Storybook

Here is the breakdown of the projects with custom categories, patterns are bolded:
Wix Style React Storybook | GumGum Storybook | Trunx Storybook | React Native Web Storybook | Artsy Force Storybook | TerraEclipse Storybook |
|
|
|
|
|
|
Layout Category Pattern
Implemented By:
Components within this item include:
- Grid
- Page
- Column
- Row
- Footer
- Section
- Titles
Components
This is where all of the building blocks for the site typically go.
Implemented By:
Utilities
These are used by different components for different things, as such it seems improperly named.
Implemented By:
π‘ Page Sections Menu Structure
Menu is broken into sections of the page.
Implemented By:

π Single Component Menu Structure
Components with a small footprint (a single component) usually use Storybook as a live demo or playground. As such, the menu is usually flat, and simple.
Implemented By:
- Airbnb Dates Storybook
- Uber React-Vis Storybook
- React SVG Pan Zoom Storybook
- React Event Timeline Storybook

##π€ Thoughts
The type of menu structure depends largely on the application. However, it does seem that higher quality projects tend to use the Categories section. This is certainly the most scalable and flexible solution that can be employed on the menu, so if you are not sure go with this.
π Button Audit
Lastly, I wanted to compare the layout of a basic component.
I picked Button
because most projects implement a form of button.
I did not expect there to be much variance in how the different projects presented the component. However, I was pleasantly surprised to find many patterns being implemented by the various projects.
Here are the results (scroll to see more). Descriptions each each pattern follow the table.
Site | Variation Patterns | Context | Release Status | Testkit |
---|---|---|---|---|
Trunx Storybook | β¨οΈWith Code | β trunx-custom | β | β |
Wix Style React Storybook | πΈ Fanned, πΌSidebar, βΉ Playground | β wix-style-react | β | β |
React Native Web Storybook | πΈ Fanned | β react-native-custom | β | β |
Coursera Storybook | πΈ Fanned, βΉ Playground | β Info Addon | β | β |
Vanilla React Storybook | π Knobs | β Info Addon | β | β |
GumGum Storybook | π Knobs | β Info Addon | β | β |
Hack Oregon Storybook | πΌSidebar | β Info Addon | β | β |
Semantic-UI Storybook | πΌSidebar | β Info Addon | β | β |
MockingBot Storybook | πΈ Fanned | β Info Addon | β | β |
Tachyons Components Storybook | πΈ Fanned | β Info Addon | β | β |
Appbase Maps Storybook | π Knobs, βΉ Playground | β | β | β |
Carbon Components Storybook | π Knobs | β | β | β |
Lonely Planet Storybook | π Knobs | β | β | β |
Grommet Storybook | πΌSidebar | β | β | β |
Cosmos Storybook | πΌSidebar | β | β | β |
Fyndiq Storybook | πΌSidebar | β | β | β |
Buffer Components Storybook | πΌSidebar | β | β | β |
Artsy Force Storybook | πΌSidebar | β | β | β |
Quran.com Storybook | πΌSidebar | β | β | β |
Variation Pattern
The example projects employed a few patterns for communicating variation in a story.

The simplest, and most common strategy is Sidebar Variation Pattern. In this pattern, variation is included in the menu.

Another simple option is to use the Storybook Addon Knobs, which is a straightforward configuration.

Fanning out a component within a story is also a common variation technique. However, it could get complicated depending on the way it is implemented.

Some projects implemented custom variation patterns, like Trunx Storybook which combines Fanning alongside its code examples.

Wix Style React Storybook also has a custom variation pattern which combines Sidebar, Fanning, and Playground
Context Pattern
Some projects display context about the component. These include attributes like:
- Description
- Source Code
- Props
About half of the projects implement some sort of Context Pattern. The most popular is the default Storybook Info Addon which offers the attributes listed above. However, some of the projects implemented their own version of the Context Pattern:
###π€ Thoughts
I see lots of value in using the Info Addon. I think custom context could be overkill unless you have the use case for it (e.g. Wix).
Release Status Pattern
Both Trunx Storybook and Coursera Storybook implemented custom code to display the release status of each component.
###π€ Thoughts This is seems really valuable for big teams.
Component TestKit Pattern

Wix also implemented a new pattern TestKit
, which provides React test snippets.
https://github.com/wix/wix-style-react/tree/master/testkit
Conclusions
Quality Tiers
In my opinion there are 3 tiers of Storybook projects within these 28 examples:
- Incomplete - missing basic patterns that are easy to configure
- Standard - following the basic patterns
- Progressive - pushing the envelope with custom attributes
Features
The Incomplete projects where missing some of the following items:
- Cover Stories - Seems too easy to not have
- Info Addon - Seems too easy to not have
- Categories Menu - Requires some thought, but allows for a more mature project in the future
- Partial Fanning of Component Variations - A personal preference, but it has lots of benefits to the user
The following features are nice, but seem impractical given the effort required:
- Release Status
- Playground
Examples
Here is how I break the examples down by category (bolded my personal favorites):
Progressive
Standard
- GumGum Storybook
- Lucid UI Storybook
- Hack Oregon Storybook
- Vanilla React Storybook
- React Native Web Storybook
- Tachyons Components Storybook
- Artsy Force Storybook
- Semantic-UI Storybook
- Fyndiq Storybook
- MockingBot Storybook