Ways to structure your Storybook

  • Updated

Storybook is a great platform for showing your coded components in all kinds of codebases. Maybe your developers use it already? Here are some observations that have worked for me that might help you (especially when using zeroheight integration).


Navigation and structure

In an ideal world, the naming of components would be 1:1 with design and code - meaning that we have a shared vocabulary across disciplines. For many of us, we might have atomic-design-like layers of complexity, so worth having these split up in the sidebar, as not all components are the same. Naming your story in the meta element in MDX creates that simple hierarchy:

<meta name=”Layer/Component name” …>


Just one interactive story

Where I deviated from how many people use Storybook is to have a single story for a component that serves as the interactive example. The reasons for this are that my use was primarily for documentation, and I found the sidebar navigation cluttered with many stories for many components over time. (Because they form another tier of navigation under the component itself.). The canvas tab gives us access to this single story, where we can see all variants by interacting with the controls/knobs. If you name that one example story the same as your component, you should only see one navigation item in your sidebar!



Whereas you may see examples of a story per variant, I opted to have one as an example near the top of the docs that had all the props wired up to knobs/controls. If you want to show a rendered view of the other variants, you can do that using the `<Canvas>` tag without a story, which will be shown in much the same way. 

This very much depends on your approach to testing. Each story has its own URL that can be really handy if you’re using Visual Regression Testing, for example. 


Split out story data

It’s often easy to describe your component props in the example itself, but I’m a fan of splitting things out for clarity, so often, I’d have a story file (like `component.story.mdx`) with a file for data alongside it (like `component.story.data.ts|js`). This way, we can describe how to set each prop up for knobs or controls in a pretty clean way and apply them to the example component(s) with the spread operator. It’s also a good idea to set up Actions here, too, for added clarity on whether an event is triggered on interacting with your component.


You can do the same thing in cases when custom styling might be useful for better showcasing the component in the canvas view. That could be simple things like alignment or padding to the canvas container that’s unique to this component, so having, for example,`component.story.css’ imported to the story file is pretty handy.





Doing even more

While I wouldn’t recommend loading it full of plugins, it might be worth going through their directory of integrations. Some can add real value by being close to your code, from checking accessibility to showing the status report from your Jest tests (or other test coverage). You can add-in mock responses for service workers or use the Apollo client to bring in data from GraphQL. Having this ability to present a rounded picture of not just what a component looks like but what the props are and do (both through controls and the in-built ArgsTable component) but how it’s tested and how it works with actual or mocked data is a powerful thing.

As Storybook is built using JavaScript, you can make your own components to drop into your docs. You can build on top of Storybook’s Add-on API if something is not already available. You could, if you wanted, override a native implementation of a Storybook component with one of your own!

Under the hood, Storybook uses Webpack for its build process. As your content grows, you may want to take a look at what optimizations you can do there, such as looking at whether lazyCompilation might work for you (which speeds up load time but adds a delay in browsing stories). Long compilation time can put people off working with it, which is friction it’s worth removing before becoming a problem. The delay for browsing should be minimal, as most stories/docs would be quite light.


How do you do it?

Like many tools, there are many ways you can use them or customize them to meet your needs. It’s always worth clarifying what problems you feel a tool might help solve and how far you can take it in that direction. Some of these ways of using Storybook worked well for me to keep my navigation simple and clean and ensure the focus was on the component itself. That meant adding plugins that either helped with transparency (controls and actions) or instilled confidence (visualizing test suites). A single interactive story with well-configured controls is a great fit for use with zeroheight, as often a single interactive component is all you need. Still, you can go the story per variant route if that helps you document the way that’s right for you!

Was this article helpful?