Storybook Architecture Audit
Publish Date2019-01-29

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

2019 01 31 storybook 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

2019 01 30 starting stories chart

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:

2019 01 31 wix cover
Wix's 'Getting Started' Cover Story

πŸ’ About

General information about the project to varying levels of detail

Implemented By:

2019 01 31 lucid ui cover
Lucid-UI's 'About' Cover Story

β›Ή Playground

A playground page where components can be altered

Implemented By:

2019 01 31 coursera cover
Coursera's 'Playground' Cover Story

πŸ’― All Components

A demo page showing all of the components

Implemented By:

2019 01 31 grommet cover
Grommet's 'All Components' Cover Story

πŸ€” 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

2019 01 31 menu structure chart

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:

2019 01 31 algolia cover
Algolia Storybook lists all of its components in the base level of the menu

πŸ“š 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:

2019 01 31 wix cover
Wix's Menu Structure

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
  1. Foundation
  2. Layout
  3. Inputs
  4. Selection
  5. Buttons
  6. Navigation
  7. Tooltips
  8. Notification Bars
  9. Modals
  10. Tables
  11. Pickers and Selectors
  12. 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:

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:

2019 01 31 todo mvc menu
TodoMVC Menu

πŸ’ƒ 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:

2019 01 31 react event timeline cover
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.

2019 01 31 vanilla react variation
Vanilla React's 'Sidebar' Variation Pattern

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

2019 01 31 vanilla react variation
Lonely Planet's 'Knobs' Variation Pattern

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

2019 01 31 react native variation
React Native 'Fanned' Variation Pattern

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.

2019 01 31 trunx variation
Trunx's 'With Code' Variation Pattern

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

2019 01 31 wix variation
Wix's Mixed Variation Pattern

Wix Style React Storybook also has a custom variation pattern which combines Sidebar, Fanning, and Playground

Context Pattern

2019 01 31 vanilla react context
Vanilla React Addon Info Component Context
2019 01 31 trunx context
Trunx Custom Component Context
2019 01 31 react native context
React Native Custom Component Context
2019 01 31 wix context
Wix Custom Component Context

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

2019 01 31 wix testkit
Wix's TestKit

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