Storybook 5.2

World-class design systems infrastructure

Storybook powers component development for design systems like Shopify Polaris, IBM Carbon, Salesforce Lightning, Auth0 Cosmos, Airbnb Lunar, and more than 25,000 public GitHub projects.

Storybook 5.2 streamlines component documentation for all Storybook users. Our goal is to make best practice documentation — like the kind found in the high profile design systems above — easy for all Storybook projects. Our first steps are:

📚 DocsPage: Zero-config component documentation

📝 MDX: Unifying stories and long-form documentation

📦 Component Story Format: Simple, portable component examples

🖼 Storybook Design System: Best practices put into practice

It also brings hundreds more improvements at every level, including new addon APIs, native TypeScript types, new presets, custom story sorting, first-class hooks support, performance wins & much more.

Read on for a tour of improvements, upgrade instructions, and a project update.

Design system docs, here we come

Earlier this year, we set an ambitious vision to radically improve component documentation.

“With Storybook Docs, you can quickly generate design system documentation, customize it to your liking, and share best practices to your team.”

5.2 introduces official support for Storybook Docs. Like the rest of Storybook, Docs supports every major framework including React, Vue, Angular, HTML Web Components, Svelte, and many more.

DocsPage

The centerpiece of 5.2 is DocsPage, a zero-config template for auto-generating best-practice component documentation from your existing stories.

Storybook’s value proposition is that it enables you to develop UI components in isolation. Developers build out stories (examples) to capture a component’s key states without having to worry about complex dependencies or flaky data APIs.

The key insight behind DocsPage is that these stories, which modern frontend teams already produce by the hundreds as a natural byproduct of development, can be used to generate amazing documentation. Unlike traditional docs, which go out of date the instant they’re published, stories are executable, testable, and always in sync with the production code.

DocsPage takes your stories, automagically combines them with code comments and component props tables, and generates beautiful pages that incorporate design systems best-practices … with no extra configuration required on your part!

Learn all about it in the DocsPage announcement post:

MDX

DocsPage is an amazing way to get great documentation for free. If you want more control, MDX is a way to flexibly author stories and long-form documentation side by side in the same file.

Here’s what it looks like to write stories in MDX. These stories are fully compatible with the entire Storybook ecosystem:

MDX combines the convenience and brevity of markdown documentation with arbitrary JSX, meaning that you can configure your component docs with arbitrary content and layout. We also provide a rich library of “Doc Blocks” for common documentation tasks, such as displaying component props, color palettes, typography samples, and other design tokens.

MDX support is available today in 5.2, with the official release currently available in Storybook 5.3-rc. To learn more, see the Storybook MDX release post.

Component Story Format

To support MDX stories, we completely reinvented Storybook’s story format. Component Story Format (CSF) is a portable, open standard for authoring Storybook stories in pure ES6 modules.

If you’ve used earlier versions of Storybook, you’re probably familiar with the “classic” storiesOf API:

import { storiesOf } from '@storybook/react'; storiesOf('atoms/Button', module)

.add('text', () => <Button>Hello</Button>)

.add('emoji', () => <Button>😀😎👍💯</Button>);

In CSF, the same example looks like this:

export default { title: 'atoms/Button' }; export const text = () => <Button>Hello</Button>;

export const emoji = () => <Button>😀😎👍💯</Button>;

CSF supports every affordance of the storiesOf API, but it’s… SO. MUCH. BETTER. It’s a clean, standard format you already know and love. CSF stories have no Storybook-specific dependencies, meaning that these stories are portable to any environment that supports ES6. Imagine being able to reuse component examples seamlessly across the entire design/development stack: in your design tools, in your documentation, and even in your test suites! We’re actively working to make that happen.

As a purely declarative standard, higher level formats, such as MDX or Github-flavored Markdown (GFM), can be transparently compiled into CSF. This allows the Storybook community to experiment with alternative ways of authoring stories while retaining compatibility with the entire ecosystem.

CSF is the default in Storybook 5.2. When you add Storybook to a new project, it now generates template code in CSF instead of the old storiesOf format. Of course, with tens of thousands of projects relying on storiesOf , we will continue support for the foreseeable future.

To learn more, see the CSF announcement post:

Storybook design system

Tying all of this work together is Storybook Design System (SDS). Built to improve component reuse across three high-traffic Storybook websites, the Design System is also ground zero for consuming, dog-fooding, and ultimately demonstrating what’s possible with Storybook Docs.