Using Storybook to develop shared understanding
— JavaScript, Documentation, Software Development — 3 min read
Recently in my spare time I’ve been working on an Instagram-like app for Pokemon Go users that allows them to curate AR shots from the game into collections such as a Pokedex or folder of favourite shots.
When building the app I’ve been using Sketch to build mockups for testing my idea with my fellow photography interested players. Sketch has a really good symbol-based system that makes it easy to swap symbols within other symbols really easily, which speeds up mockup creation immensely.
I found this very similar to the way that Web component frameworks such as React function. By breaking my design down into components / symbols I was able to make a highly re-usable UI and move from Sketch to React with minimal effort.
During development, I decided to create a separate component library with the idea that I could use this in a number of projects, but I struggled to find a means of documenting how these components worked.
Storybook is a nifty little framework I found that does exactly this and a lot more. It not only allows you to show off your components and provide example code, but it also allows potential consumers of the library to interact with both the UI and the state that powers it.
What is Storybook?
Style guides for those who have never worked with them are a means of showing off CSS and the mark up to render different UI components, usually compiled via tooling for LESS / SASS like KSS (an example of this would be the one I built for Open eObs).
Style guides work well to build understanding between designers, developers, testers and those on the business side, as you had a single document explaining how the UI would look, normally with different states shown.
Storybook takes that idea, but as Web Components can be passed properties (especially if you use the Higher Order Component pattern) there’s no need to have five separate sets of markup, instead you can use the Knobs Addon to change the property via the Storybook UI.
The addon ecosystem is what really made me realise the power of Storybook. By npm install -ing an addon and adding the relevant code to the setup you can add:
- Check how your components work on different screen sizes
- Check your components for WCAG violations
- Add UI toggles to change the properties used to render the components so you can show how they render based on different states
- Link Storybook pages together to create clickable mockups
- Add supporting documentation to the components
How can Storybook help teams?
Storybook can help teams not only build shared understanding of the product being built and the value it’s going to deliver to the user, but it can also help the development process.
UX and designers can use Storybook for validated learning activities as they can pull together new interfaces really easily within Storybook and use tools like the Knobs addon to walk the customer through how the UI will react to changes.
Testers can start exploratory testing early to catch any simple UI bugs. They can also start usability and accessibility testing too (the WCAG compliance addon helping here). There’s also a plugin that allows Jest test reports to be shown alongside stories which can help with reporting needs of the team.
Automation Testers can also use Storybook to change their Page Object Models to new UI changes earlier, as well as using the Knobs addon to force the UI into states they’d expect as the user interacts with the UI. This means the automation test packs are less prone to falling out of sync with the apps UI.
Combine Storybook with the GraphQL addon and front-end development teams can start planning how more complex components with many children will use the data received from the Higher Order Component to render pages before the backend is fully built.
Using the Notes addon teams can annotate Storybook, allowing them to add useful notes for support staff who can use this when answering support queries about navigating the UI.
Gotchas of using Storybook
No tool is perfect so naturally there a few gotchas to be mindful of, but in my opinion there are no major issues.
- As it’s JS, if one of your components (probably doesn’t apply to HTML components) in the story throws an exception that entire story will not be rendered
- As the static website is built using webpack, be careful if you are using something like GitHub pages, as you’ll need to push all the static assets (not just the changed code) to ensure the website works properly
- Aside from a branching strategy such as tags or release branches there isn’t a means to version the storybook, so you’ll need to roll your own
- It’s Javascript, so make sure you pin your dependencies! If you don’t you might find yourself breaking your Storybook without any heads up