Building a Design-Driven Workflow in Storybook.js with Angular and Sketch – Part 3

Published April 29, 2019

After learning about some advanced techniques for our new workflow in the previous posts, we’re now ready to provide some infrastructure for onboarding our team. Once you’re done with this, you’ll be ready to launch your Storybook!

What we’ll be doing

In the last installment of this series, we will put together some infrastructure to get your team on board. From keeping things nice and tidy, to establishing a shared context for your components, to showing off your source code.

For your convenience, I’ve prepared a GitHub repository that you can check out, if you don’t want to type all the examples in this post yourself. You can check it out right here.

Grouping Stories Into Sections

Once your Storybook has made its way in your everyday workflow, it can grow quite fast. Especially when you work on a larger project, possibly with a lot of components and a big team, it makes sense to group components into sections. For this, you can add a divider in your stories’ name, like so: Section | Story. This will result in stories being grouped in the sidebar:

A full example would look like this:

import {ListComponent} from './list.component';
import {storiesOf} from '@storybook/angular';
import {withKnobs, object} from '@storybook/addon-knobs';
import {listItems} from './list.component.mocks';

storiesOf('Layout | List', module)
  .addDecorator(withKnobs)
  .add('Default', () => ({
    component: ListComponent,
    props: {
      items: object('Items', listItems, 'General')
    }
  }));

Writing The Background Story

Once you’ve added some components, you might want to add a little background to your story. This might include things like where and how a component should be used, or what child components are used within a screen.

Adding Notes To Your Story With Markdown

First, we will want to add addon-notes to our project by running npm i --save-dev @storybook/addon-notes. Once the install is finished, we need to register the addon in our Storybook addon config. So let’s go to the addons.js file in the .storybook folder and add the following line at the end of the file:

import '@storybook/addon-notes/register;

This will make the notes feature usable immediately in our stories. So let’s try and add some markdown, telling us more about the story. Just add the following code above your story definition in input.stories.ts:

const md = `
# The input component

It shows off knobs! Awesome!
`;

And to attach the notes to a story, we just add the notes to the parameters for this story, like so:

storiesOf('Forms | Input', module)
  .addDecorator(withKnobs)
  .add('Default', () => ({
    component: InputComponent,
    props: {
      label: text('Label', 'The label', 'General'),
      placeholder: text('Placeholder', 'The placeholder', 'General')
    }
  }), {
    notes: md
  });

Et voilà! Now we have nicely rendered markdown notes in the notes tab of our UI:

I’d recommend using notes when building up a design system for your team. They’re a very good starting point for the consumers (developers, most likely) of your components to get a better understanding of the underlying philosophy. To give you some ideas what you could write about, I’ve put together a small list:

Use-cases – in which contexts should I use this component?
What to avoid – where and how shouldn’t I use this component?
Usage – what can I do with this component? (however, make sure to reflect this in your stories, as well).
Related – which components can be used together with this one? Are there any child components inside the one you’re showing?
Voice and tonality – think “OK” vs. “Save changes” for a button label, for example. This can make or break a good UI.

Show Off Your Work With Storysource

Storysource is a neat little addon, which adds a “Story” tab to your Storybook, showing the source code for the respective story. Installing it is as easy as adding the npm package and adding a bit of config. But let’s do this step after step. First add the addon to your project, by executing the following command in the terminal of your choice:

npm i --save-dev @storybook/addon-storysource

Great! Now we have the addon installed and ready. We still need to tell Storybook about it, though. So let’s go to the addons.js file in the .storybook folder and add the following line at the end of the file:

import '@storybook/addon-storysource/register';

Now you should be able to see the Story tab in your UI. However, it does nothing but print out loading source.... This is because we haven’t told Storybook where to find those source files yet. Let’s tell it, then! To do so, we’ll add a custom webpack configuration in the .storybook folder, by the name of webpack.config.js and add the following contents:

module.exports = {
  module: {
    rules: [
      {
        test: /\.stories\.ts?$/,
        loaders: [require.resolve('@storybook/addon-storysource/loader')],
        enforce: 'pre',
      },
    ],
  },
};

This will tell Storybook to look for all files matching .stories.ts in our project folder. And now we should be able to see our stories’ source as well.

The “Convince Your Boss Kit”

So now you have created your very own Storybook. But what should you tell your boss to get him to greenlight this effort for your project? Here’s some reasons why you should be using Storybook in your project. Developing components with Storybook:

provides an easy way to test edge cases, which would usually be hard to reach and keep track of in your live application
lets you present different aspects of a feature in a clear and easy to understand manner once it’s deployed somewhere
enables you to test those components right away without being dependent on other business logic, data or component hierarchies
paves the way for unit testing, since you already have mock data and testable components at your disposal
gives everyone in the team a shared context to talk about.
makes reviewing features easy
helps you avoid regressions, especially when you implement automated testing
provides a common place for everyone in the team to experiment and play with the components

Wrapping up

That’s it, you made it! We’ve set up the workbench for crafting a robust user experience. We tested advanced features of our application, and we even prepared for onboarding the rest of the team. By now, you’ll be ready to present your new workflow to your team, client or boss. No matter who, you’re guaranteed to blow their minds!

Have you tried this workflow and are keen to share your experiences? I’d love to hear from you on twitter!