storybook-mdx-for-design-system-docs

Components & documentation in harmony at last

Michael Shilman

Storybook is the standard tool for UI component development. It’s used to build the most popular design systems on the web, including Shopify Polaris, IBM Carbon, Salesforce Lightning, Auth0 Cosmos, and Airbnb Lunar.

Quality documentation like this is crucial to help people re-use your UI components, but it’s also a huge pain to get right. In practice, you spend more time maintaining your documentation system than actually writing docs!

Which is why at Storybook, we’re hell-bent on making UI component docs fast and easy. Our first step was DocsPage, a tool to auto-generate best-practices documentation from your existing stories.

And today I’m excited to introduce fast, fully custom docs in Storybook, powered by MDX and available in Storybook 5.3-beta! ?

MDX enables you to customize Storybook’s auto-generated documentation with your own components, mix & match DocBlocks, and loop in non-technical teammates. All from within the comfortable confines of Markdown.

  • ? Customizable docs: Fully custom documentation made simple.
  • ? Ready-made building blocks: Reuse Storybook’s powerful DocBlocks.
  • ? Write docs together: Powerful for devs, easy for designers and PMs
  • ? 100% compatible: Seamless Storybook integration that’s zero config

Earlier this year, the team outlined an ambitious vision to rethink component documentation. Our first milestone was Storybook 5.2 that introduced DocsPage to automatically generate best practice UI docs from your existing stories.

Storybook Docs took off like a rocket, becoming one of the most popular documentation tools (by npm downloads) in a matter of weeks! But even as teams embraced DocsPage, the desire to write fully custom documentation was clear.

Storybook MDX gives component authors an unparalleled balance of flexibility, cleanliness, and ease. MDX is an open, authorable format that fluidly interleaves Markdown and JSX components in the same file. It makes it easy to compose off the-shelf building blocks like color palettes, typography samples, and prop tables into long-form documentation.

What’s more, the straightforward MDX authoring experience means designers, PMs, and anyone familiar with Markdown can contribute to shared UI documentation. Intrepid alpha and beta users are already using Storybook as a single source of truth for their component libraries and design systems.


Storybook MDX is my dream documentation system. I retain the power and flexibility of Storybook’s beloved “Canvas”, but now have a fully-fledged way to write beautiful and portable long-form documentation that truly gets at the heart of our design system. — Vince Speelman, Front-end Engineer @ TEDtalks


The key addition in Storybook 5.3 is MDX support. MDX (“markdown for the component era”) is a foundational project that fluidly mixes markdown with embedded JSX components. Here’s what an MDX story looks like:

You probably recognize Markdown in blocks like # Badge, Let's define, and We can even. There are also a few JSX elements:

  • Meta is an element that situates your component in Storybook.
  • Story defines a new story (or references an existing one).
  • Preview frames one (or more stories) and displays their source code.

These DocBlocks form the basis of Storybook MDX. We’ll introduce a few more in the next section.

But before that, let’s jump ahead to full example: REAVIZ, a React visualization library built and documented in Storybook. It demonstrates theming, static markdown pages, custom MDX, and DocsPage in a single Storybook.

In addition to rendering stories, it’s also useful to include other design system documentation, such as prop tables, color palettes, and typography.

We’ve crafted a prop table DocBlock for a component’s API.

When applied to React components, it shows each prop’s name, description, type, and default value:

Patrick Lafrance & Francis Thibault sweated the details to get this right. When applied to other frameworks — such as Vue by Aaron Pool & Shota Fuji / Angular by Kai Röder / Web components by Thomas Allmer / Ember by Matthew Irish— the prop table gets divided into sections such as inputs, outputs, slots, events, etc. Details forthcoming in another post! ?

It’s also easy to document your styling in Storybook MDX. Color palettes, iconography, and typography come out of the box. And in the future, you’ll get tighter integrations with different sources of design tokens, based on Philipp Siekmann’s fine work in storybook-design-token.

# Colors


title="theme.color.greyscale"

subtitle="Some of the greys"

colors={['#FFFFFF', '#F8F8F8', '#F3F3F3']}

/>

...

# Icons



...

# Typography


Storybook Docs provides human-readable documentation for all our components. MDX reduces complexity, and enables all parts of the organization to contribute to the conversation. — Sean Luo, Software Engineer @ Kickstarter


Storybook started as a development tool for organizing, developing, documenting, and testing components. As it grows in popularity, teams are starting to use their Storybook as shared resource for designers, PMs, and QA.

With MDX, non-technical team members can now help update shared UI docs. This gets your teammates engaged and reduces maintenance work for you. It’s a win-win that kicks off a new direction for Storybook to better support cross-functional collaboration.

Storybook MDX is 100% compatible with the rest of the Storybook ecosystem.

With all of the features Storybook MDX brings, you might guess that it would be a challenge integrating it with the rest of Storybook’s large ecosystem of prototyping, review, testing, documentation, and collaboration tools and services. Fortunately, you’d be wrong!

Earlier this year we introduced Component Story Format (CSF), an open standard for component examples based on ES6 module exports. CSF is the basis for Storybook. Under the hood, our MDX stories are transparently compiled into CSF. This means that anything can load CSF can also load Storybook MDX with no additional integration needed.

We’ve shown this with Storybook itself by adding a webpack loader, and with Jest by adding a jest transformer for Storyshots, our open-source DOM-snapshotting library. Cloud services like Chromatic also have full MDX support built in on day 1.

Want it? First upgrade your project to Storybook 5.3-beta:

npx npm-check-updates '/storybook/' -un

npm install # or yarn if you prefer

Then add docs to an existing project:

npm install @storybook/addon-docs@next --save-dev # or yarn

Finally, add the following line to your .storybook/presets.js file:

module.exports = ['@storybook/addon-docs/preset'];

For more information on configuring MDX, read the installation instructions.

The easiest thing you can do to help is install Storybook 5.3–beta in your project and ask questions and/or file bugs in our GitHub project. And if you see a bug you can fix, we welcome all contributions!

In addition, we have a lot of stuff in progress:

  • We’re expanding the set of frameworks with enhanced docs support. React in 5.2, Vue/Angular/Web Components/Ember in 5.3. We’d love to add Svelte and other frameworks with your help.
  • We’re creating a rich library of DocBlocks, for example avatars of GitHub collaborators for a component, component status badges, and so forth.
  • Finally, we also want the ability to embed storybook docs in other documentation systems such as Gatsby.

If you’re interested in collaborating on any of this, or just want to stay on top of the latest, the project community mostly lives in the #docs-mode channel on our Discord.

Storybook Docs is being developed by Michael Shilman (me!), Atanas Stoyanov, Patrick Lafrance, Francis Thibault, Aaron Pool, Shota Fuji, Kai Röder, Tom Coleman, Norbert de Langen, Lionel Benychou, Matthew Irish, Thomas Allmer, and Igor Davydkin. Design and theming by Dominic Nguyen. Special thanks to MDX early adopters Austin McDaniel, Vince Speelman, Kevin Suttle, Alex Wilson, and Tom Speak. Huge ? to Brad Frost for design systems project guidance.

If Storybook makes your UI developer workflow easier, help Storybook get better. You can contribute a new feature, fix a bug, or improve the docs. Join us on Discord, support us on Open Collective, or just jump in on GitHub.

Sign up to the Storybook mailing list to get updates in your inbox.

how-to-integrate-storybook-with-design-tools

Documentation helps teams reuse existing work instead of rebuilding new UI. It’s doubly important in component libraries and design systems because they’re intended for wide distribution.

However, documentation often takes more work than folks expect. You end up sinking time into non-documentation tasks like site infrastructure, wrangling technical writers, and maintenance instead of actually writing docs.

Storybook already provides lightweight documentation out of the box (although we don’t call it that) by naturally encouraging developers to save UI component variations as “stories”. Documentation addons amplify this core capability to help interdisciplinary teams stay in sync.

Storybook Docs

The official Storybook Docs addon generates a customizable documentation site for your component library or design system. It succeeds the popular info addon with first class support for Markdown, MDX, and JSDoc syntax.

Under the hood, SB Docs uses industry-standard docgen tooling to build API docs from stories. Bring design artifacts into SB Docs by embedding them via an iframe from Figma or Sketch (with Abstract).

InVision Design System Manager

InVision DSM is a design system documentation tool. It helps design teams consolidate UX principles, user interface design, usage guidelines, tokens, and more in a shared documentation site.

DSM allows you to view Storybook components in the DSM app alongside the designs (which are extracted from Sketch). Teams can interact with the UI component implementation in the context of the design system before integrating it in their apps.

Zeplin

Zeplin is a design handoff tool that generates styleguides from design files. It auto extracts metadata like assets, colors, and measurements from design files to make it easier for developers to adhere to the design spec. Zeplin allows you to link off to Storybook components from inside their desktop app.

Zeroheight

Zeroheight is a collaborative styleguide generator for design systems. It showcases design, code, brand, and copywriting documentation in one place. Users can easily edit that documentation with a WYSIWYG editor. The addon brings Storybook components into Zeroheight to display alongside Sketch, Figma, or Adobe XD designs.

Story2sketch for Sketch

UI components are the source of truth for designers and developers alike. Story2sketch allows you to build a Sketch file from components in Storybook. This helps designers keep their Sketch files current with the latest UI patterns.

Design Token

A “design token” is a styling constant for variables like typography, colors, spacing, and animation. Tokens are distributed by design systems for reuse across many projects. This addon extracts design token documentation from your stylesheets to display during development.

storybook-5.2

World-class design systems infrastructure

Michael Shilman

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.

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.

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:

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 coming soon in Storybook 5.3. To learn more, refer to the MDX documentation.

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', () => )

.add('emoji', () => );

In CSF, the same example looks like this:

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

export const emoji = () => ;

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:

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.

SDS was born out of the need to unify disparate components from three different websites: Storybook’s website, Learn Storybook tutorial, and Chromatic (a visual testing service by Storybook maintainers).

It encompasses 25 production-grade functional UI components and 95 stories, design tokens for the Storybook brand, and component/library documentation.

SDS will make it easier for the Storybook community to develop and maintain new marketing and documentation sites. But it also serves a secondary purpose: it’s also the design driver and public reference implementation for Storybook Docs itself! Look no further for best practices on how to develop your components stories, document them, test, and publish them.

To learn more, browse Storybook Design System or read the Design System announcement:

Easy documentation, at last!

Storybook is already the tool of choice for design systems engineering. With the addition of DocsPage, MDX, Component Story Format, and the new Design System, we’re transforming component documentation and bringing design systems best practices to all projects that use Storybook. Get started with these improvements today in 5.2, and stay tuned for more exciting updates across the board in the 5.3 release.

The amazing thing about a thriving community project with 750 contributors is that the system is continuously improving at every level.

Other highlights from 5.2 include:

✅ Addon APIs. Storybook is known for its rich addon ecosystem, and writing addons got a lot easier in 5.2 thanks to new hooks-based APIs by Norbert de Langen and Filipp Riabchun. The new APIs follow React hooks pattern, which makes state management & communication simpler and more concise. The improvements are documented here.

✅ TypeScript support. Typescript recently surpassed Javascript in Storybook’s codebase and 5.2 contains “native” Typescript types for most packages. We’ll do a proper announcement soon, but in the meantime you can move off DefinitelyTyped for most common cases. Kudos to Kai Röder, Gaëtan Maisse, Norbert de Langen and many more contributors who are actively working on the conversion.

✅ React hooks support. Storybook 5.2 contains first-class support for React hooks in stories thanks to small fixes by Michael Shilman and Atanas Stoyanov.

✅ Story sorting. By popular demand, Storybook now supports a story sorting function to control the order of stories in the navigation panel. Contributed by Robert Snow with help from Tom Coleman.

✅ Performance. Storybook story switching and search performance is for large storybooks has dramatically improved (~1000ms => ~50ms) thanks to a slowdown repro’d by Kevin Weber and optimized by Michael Shilman.

✅ Standalone mode. Storybook is still based on Webpack, but it’s now possible to connect the UI to an external server, thanks to RP Deshaies with help from Tom Coleman and Michael Shilman. We’ve prototyped an instance of Storybook running under the Parcel bundler in 5.2. This sets the stage for a lot of interesting things in the future. Storybook for Rails anybody?

✅ New presets. Storybook 5.1 introduced presets: one-line configurations for babel, webpack, and addons. Storybook 5.2 adds an SCSS preset by Igor Davydkin and a beta Create-React App preset by Brody McKee that greatly improves upon Storybook’s built-in CRA support.

Storybook 5.2 is packed with new features, but doesn’t contain any breaking changes AFAIK. We’ve got a 5.0 upgrade guide if you’re coming from 3.x/4.x. If you’re already on 5.x, upgrading is ridiculously easy:

npx npm-check-updates '/storybook/' -u

npm install # or yarn

And if you’re new to Storybook, now’s the best time to get started. Check out the Storybook Tutorial for a step-by-step of React/Angular/Vue. Or jump right in:

cd my-project

npx -p @storybook/cli sb init

yarn storybook

Once you’re on 5.2, adding DocsPage to your project is a snap:

npm install @storybook/addon-docs --save-dev # or yarn

Then add the following line to your .storybook/presets.js file:

module.exports = ['@storybook/addon-docs/react/preset'];

Replace react with your framework of choice. For more information on configuring DocsPage, read the addon-docs installation instructions.

Storybook’s backbone is its incredible community of developers and users. The project recently passed 41,000 Github stars, which puts us on a par with legendary projects like Rails and Bitcoin. Together, we’re building the future of component development.

We’d love to have you involved, regardless of your experience level. If Storybook makes your UI developer workflow easier, help Storybook get better. You can contribute a new feature, fix a bug, or improve the docs. Join us on Discord, support us on Open Collective, or just jump in on Github. Please ? applaud this post and share to help more people discover it.

Sign up to the Storybook mailing list to get updates in your inbox.

Storybook 5.2 code contributors:

@8beeeaaat @adamdoyle @atanasster @autarc @baraalex @benoitdion @bqrichards @chaseadamsio @chris-dura @christianliebel @christoph-fricke @christophehurpeau @codebyalex @crimx@ctavan @danielduan @danrha @darondel-yoobic @debel27 @dogafincan @domyen @dylanpiercey @edumoreira1506 @elliotlarson @emilio-martinez @enagy27 @enuvid @ewgenius @expe-lbenychou @fabianmarinog-turner @fabiradi @forbeslindesay @gaetanmaisse @ghengeveld @gnujim @gongreg @graup @hipstersmoothie @hypnosphi @indigolain @jamesgeorge007 @jballin @jeffgukang @jendowns @jessica-koch @jimmydalecleveland @joeycozza @jounqin @jsomsanith-tlnd @juliamitchelmore @kaelig @kamahl19 @kroeder @leoyli @libetl @lonyele @lucasterra @mariocadenas @matt-tingen @matthewlehner @mrmckeb @ndelangen @ndom91 @nzacca @pascaliske @piperchester @pksunkara @pocka @rembrandtreyes @resource11 @richardtorres314 @robaxelsen @roydipti23 @rwoverdijk @sakito21 @shilman @simenb @smasontst @stephanemw @stereodenis @testerez @thebuilder @tylerlee @wa4-fearless-otter @xyshaokang @zkochan @zol