Storybook Docs sneak peek

Turning stories into living documentation

Michael Shilman
Apr 16, 2019 · 5 min read

Storybook is the world’s favorite UI component workshop. It enables structured UI development and testing for every major view layer including React, Vue, Angular, React Native, and Ember.

Now we’re supercharging Storybook’s documentation features. Stories already capture key states of your components. Storybook Docs makes it easy to automatically turn these stories into world-class documentation.

Wait, but why?

But what if you want in-depth component documentation? Or to create a design system site to scale UI library adoption?

Currently, you’d have to cobble together docs from addons and docgen libraries. Or you’d build a separate docs site using Gatsby, Docz, Styleguidist, etc. That means Storybook users end up spending more time on documentation tooling than actually writing docs.

Storybook makes it dead simple to create design systems

How to scale UI libraries

With Storybook Docs, you can quickly generate design system documentation (with intuitive defaults), customize it to your liking, and share best practices to your team.

How it works

  • 📕 Component Story Format: A new format for authoring stories that is more user-friendly and makes it easier to embed Stories in other contexts.
  • 📄 MDX support: Expressive doc authoring, integrated with Storybook’s UI and tooling.
  • 📤 Templates & Static Export: Best practice design systems implemented in Storybook, and templates that make it easy for anybody to document using their component libraries effectively.
Canvas, Props, Type, Preview, Colors, Icons

Doc Blocks

  • Canvas. Embed the Storybook Canvas with the toolbar and source
  • Props. Document component inputs in a table
  • Type. Show typography scaling and usage
  • Preview. Embed arbitrary stories
  • Colors. Show your color palette
  • Icons. Document your icon set

Beautifully crafted by Storybook 5.0 designer Dominic Nguyen, Doc Blocks are embeddable in Storybook’s UI, and will also be compatible with other static site frameworks like Gatsby and Next. Storybook Docs will generate these blocks from React, Vue, and Angular stories; we plan to extend them to other view layers with the community.

As a first deliverable for this project, we will re-implement the Info addon as part of SB Docs, but it will display in the addons panel support multiple view layers.

Component Story Format

Tom Coleman designed an alternative story format and prototyped it in SB5. Docs builds on this format to enable a smooth authoring experience that’s portable to other documentation systems.

MDX Support

Docs builds on Norbert de Langen’s improvements to the Notes addon and MDX prototyping by Igor Davydkin. It will attempt to be backwards compatible with existing notes in stories.

The Docs equivalent to the Info addon will be just a specific template instance of a note that’s automatically generated for each story.

Screencast of SB Docs proof-of-concept

Templates & Static Export

The final piece of Storybook Docs is to combine these tools into a streamlined best practice workflow that makes authoring docs easier for every Storybook user. To this end we will:

  1. Research/prototype: Study existing design systems, catalog best practices, and implement those in the documentation for Storybook’s own component library
  2. Template-ize: Build those features into an off-the-shelf template that encodes best practices for everybody to use.
  3. Export: Make it easy to statically export a standalone documentation site, build-docs that mirrors build-storybook usage. Specifics still TBD.

This is necessarily part of a longer design cycle that is currently in progress.

Get involved

If you’d like to help bring Storybook Docs to life, come work with us to help build and theme Doc Blocks. Or make sure SB Docs supports your favorite view layer. Or simply give feedback on the design as it evolves— we’d love to have you involved!

Join us in the Storybook’s Discord chat #docs-mode and on GitHub. We welcome contributions from new developers and experienced veterans alike.

And sign up to the mailing list to get Storybook updates delivered to your inbox.


The UI development environment you'll ♥️ to use.

Medium is an open platform where 170 million readers come to find insightful and dynamic thinking. Here, expert and undiscovered voices alike dive into the heart of any topic and bring new ideas to the surface. Learn more

Follow the writers, publications, and topics that matter to you, and you’ll see them on your homepage and in your inbox. Explore

If you have a story to tell, knowledge to share, or a perspective to offer — welcome home. It’s easy and free to post your thinking on any topic. Write on Medium

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store