Documentation Primitives
Accessible, best practice docs for Storybook
Good documentation — accessible, extensive, and up-to-date — is crucial to building trust and driving the adoption of any software product, including design systems.
Producing and maintaining documentation is never the responsibility of any single discipline. As this HubSpot article points out, the task is co-owned by designers and developers. Each discipline can then contribute its skills, context, and the unique perspective towards this challenge.
How do we make working on documentation easy for both designers and developers?
This is an interesting challenge for the design system infrastructure. Is there a platform that helps each discipline fulfill their documentation goals while enabling collaboration in a seamless and transparent way?
Can it be solved without investing in a fully custom solution (not every organisation has a budget for it, or scale large enough to justify the need), or having to maintain multiple platforms which inevitably go out-of-sync (a common scenario is using Storybook for components and zeroheight for documentation)?
At Digital Arts Network we experiment with Storybook a lot and believe it could be the ultimate shared resource for both component code and documentation. Teams already use it to build, test, and catalog components. With the latest version of the Docs Add-on, we can author long-form documentation that doesn’t have to be strictly text-based. Powered by MDX (allows to embed components into Markdown pages), documentation can be composed out of smaller DocBlocks — think UI components, but for narrative. This makes perfect sense, we are already building apps using components — we can document them in much the same way.
With Storybook, Docs Add-on, and MDX, we have a robust foundation for writing documentation that can successfully mix text, component examples (“stories” in Storybook terms), and DocBlocks. DocBlocks is what makes documentation more expressive and engaging while keeping the entry barrier low for non-technical contributors. Effectively, anyone with a GitHub (or GitLab, or BitBucket) account (web editing interfaces are perfect for this — no need to keep a local copy of the project) can start contributing to documentation.
This is an example of what an MDX-enhanced narrative looks like:
# Our brand coloursOur colors are optimized to meet WCAG 2.0 Level AA Accessibility Guidelines.<Usage>
<Correct>Use "Red 500" for validation error text.</Correct>
<Incorrect>
Don’t combine color values in ways that do not meet minimum
accessibility contrast requirements.
</Incorrect>
</Usage>
Notice how we are still mostly writing text, while the <Correct> and <Incorrect> tags, wrapped in a <Usage>, handle all the markup and styling required to render a “Do / Do Not” section, similar to those used by Polaris and Carbon design systems.
We don’t have to rely on 3rd party platforms for customisation options or to be able to insert a certain type of content— we can achieve that with custom components. Storybook ships with a selection of ready-to-use DocBlocks. More custom DocBlocks are being built by the Storybook community. One of these packages is our own Documentation Primitives library.
Introducing Documentation Primitives
Documentation Primitives is a collection of simple, low-level building blocks — primitives — for building design system documentation in Storybook. At the moment, it includes colour swatches, usage blocks (“Do / Do not”), note and warning panels, spacing scale tables, and other smaller utilities. These reusable blocks complement and extend the Storybook built-in documentation capabilities.
The blocks are low-level by design which means they can be adopted by design system teams with very different needs.
Great documentation is within reach for teams of any size. Auto-generated by Storybook, enhanced and extended by custom MDX components, it stays up-to-date with the components and allows non-technical team members to contribute.
