Back to blog

Storybook Docs sneak peak

Turning stories into living documentation

loading
Michael Shilman
โ€” @mshilman
Last updated:

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?

Storybook provides the story construct that captures key component states. With low effort you get basic component documentation, so they are fantastic for nimble teams.

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

What if you could press a button and export a beautiful standalone design system ready for your team/users to consume?

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

  • ๐Ÿ“ฆ Doc Blocks: A set of documentation components that serve as the building blocks for your docs, available in Storybook and embeddable in any documentation system.
  • ๐Ÿ“• 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.

Doc Blocks

The first phase of Storybook Docs is building a core set of components for documenting components and stories. Specifically:

  • 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

Storybookโ€™s current story format exposes Storybookโ€™s data structure (the โ€œstory storeโ€) as part of the authoring experience. This makes the authoring experience more cumbersome than it needs to be. It also makes it harder to embed stories in other documentation systems.

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

The third aspect of Storybook Docs is MDX support. MDX is Markdown for the component era. MDX embeds JSX in Markdown, allowing you to use Markdownโ€™s terse syntax (such as # heading) and JSX for more advanced components. And Storybookโ€™s MDX is compatible with all the view layers we support, including Vue, Angular, and many others.

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

Doc Blocks, Component Story Format, and MDX support give developers versatile tools to solve any number of documentation-related use cases.

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

Storybook is maintained by amazing open source contributors and guided by a steering committee of top maintainers.

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.

Join the Storybook mailing list

Get the latest news, updates and releases

6,615 developers and counting

Weโ€™re hiring!

Join the team behind Storybook and Chromatic. Build tools that are used in production by 100s of thousands of developers. Remote-first.

View jobs

Popular posts

Storybook 5.1

React Native โ€ข Accessibility โ€ข Context โ€ข Presets โ€ข Docs update
loading
Michael Shilman

Component Story Format

Simple, portable, future-proof component examples
loading
Michael Shilman

Storybook 5 Migration Guide

A hop, skip, and jump to a beautiful new developer experience
loading
Michael Shilman
Join the community
6,615 developers and counting
WhyWhy StorybookComponent-driven UI
DocsGuidesTutorialsChangelogTelemetry
CommunityAddonsGet involvedBlog
ShowcaseExploreProjectsComponent glossary
Open source software
Storybook

Maintained by
Chromatic
Special thanks to Netlify and CircleCI