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:

1. UI development environment for creating components independently of application code (domain logic, routing etc.)
2. 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:

1. How can Storybook be used?
2. How can Storybook stories be organized?

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:

1. Coursera Storybook
2. Grommet Storybook
3. Wix Style React Storybook
4. Carbon Components Storybook
5. Lonely Planet Storybook
6. Airbnb Dates Storybook
7. Uber React-Vis Storybook
8. Buffer Components Storybook
9. Algolia InstantSearch Storybook
10. Artsy Force Storybook
11. React Native Web Storybook
12. Griddle Storybook could not find storybook
13. Tachyons Components Storybook
14. Appbase Maps Storybook
15. Quran.com Storybook
16. TerraEclipse Storybook
17. React Event Timeline Storybook
18. Semantic-UI Storybook
19. Hack Oregon Storybook
20. TodoMVC with Specs Storybook
21. React SVG Pan Zoom Storybook
22. Fyndiq Storybook
23. GumGum Storybook
24. Lucid UI Storybook
25. Trunx Storybook
26. Cosmos Storybook
27. MockingBot Storybook
28. 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:

• Trunx Storybook
• Wix Style React Storybook

💁 About

General information about the project to varying levels of detail

Implemented By:

• Hack Oregon Storybook
• React SVG Pan Zoom Storybook
• Tachyons Components Storybook
• Lucid UI Storybook

⛹ Playground

A playground page where components can be altered

Implemented By:

• Coursera Storybook

💯 All Components

A demo page showing all of the components

Implemented By:

• Grommet Storybook

##🤔 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
Introduction Getting started Usage Without Yoshi Foundation Layout Inputs Selection Buttons Navigation Tooltips Notification Bars Modals Tables Pickers and Selectors Other Components WIP Styling Tests	Atoms Layout Molecules Utilities	Overview Modifiers Columns Layout Form Elements Components	Components APIs Example apps	Apps Components Onboarding Publishing SSR Router StaticCollapse Styleguide Typography	Decorators Utilities Components

Layout Category Pattern

Implemented By:

• Wix Style React Storybook
• Trunx Storybook
• React Native Web Storybook

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:

• Wix Style React Storybook
• Trunx Storybook

Utilities

These are used by different components for different things, as such it seems improperly named.

Implemented By:

• Wix Style React Storybook
• Trunx Storybook

🍡 Page Sections Menu Structure

Menu is broken into sections of the page.

Implemented By:

• TodoMVC with Specs Storybook
• Appbase Maps Storybook

💃 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:

• Trunx Storybook
• Wix Style React Storybook
• React Native Web Storybook

###🤔 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:

1. Incomplete - missing basic patterns that are easy to configure
2. Standard - following the basic patterns
3. 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

1. Trunx Storybook
2. Wix Style React Storybook
3. Coursera Storybook

Standard

1. GumGum Storybook
2. Lucid UI Storybook
3. Hack Oregon Storybook
4. Vanilla React Storybook
5. React Native Web Storybook
6. Tachyons Components Storybook
7. Artsy Force Storybook
8. Semantic-UI Storybook
9. Fyndiq Storybook
10. MockingBot Storybook

Incomplete

1. Grommet Storybook
2. Carbon Components Storybook
3. Lonely Planet Storybook
4. Buffer Components Storybook
5. Cosmos Storybook