Storybook-HTML Tutorial – Part 2 – Build a Styleguide skeleton

As an ex-Interactive/Media art student, I am used to work in a studio, atelier, or workshop room. Such highly customized environments manage the space for design and development tools. Beyond that, such spaces provide safe(!) places for learning, experimenting with art pieces. My previous blog post described the process of setting up similar digital working environments for Web Developer and Designer. In my opinion, Storybook-html is a pretty good starting point for developing your templates or other HTML, CSS, JS code.

Sometimes, I am so much into the flow moment, that I forget to document my work. Based on my experience as professional web developer, I know that happens other people, teams, too. Storybook facilitate to keep your documentation simple, accessible for all team members. A documentation from start is very easy with Storybook…

This article takes you on my styleguide journey with Storybook. The article about Design Systems for Startup has some great points, but I think a Design System from scratch is a little bit too much fort this starter project. I would prefer to assign our journey to a Styleguide and Component Library methodology, which is very similar to the Pattern Lab and its Styleguide Guide workflow. Nevertheless, which tool of choice you have chosen, the later or sooner your will reach the level and enjoyment of a style guide-driven design system😉

Personal Disclaimer

From my point of view, the Pattern Lab and its Atomic Design community achieved some highly valuable workflows between Designers and Developers. However, Storybook feels more mature to me, the architecture seems to be more flexible, and the community seems much bigger and active than the Pattern Lab community. On a personal level, I feel much more comfortable on the toolchain of NPM, Webpack, and JavaScript. Due the sum of all these reasons, I decided to go ahead with Storybook. The Atomic Design principles and workflow will be kept and applied in my Storybook working environment.

Create the first styleguide pages

Let’s start with a new Storybook story as a HTML Page. Luckily, it is damn easy to add a clean HTML documentation page to your Storybook. Below, the code creates a HTML Documentation for the Voice and Tone Guideline.

The goal of this tutorial is Styleguide structure similar to the Styleguide Guide by Brad Forst. His boilerplate addresses a great collection of a styleguide documentation. It is up to you to fill the empty documentation spaces during your ongoing process of a Living Styleguide.

The index.js file within the stories folder can become unreadable very fast. Therefore, I highly recommend to separate some parts of your documentation in new external files. Please create and add a folder with the names “tokens” and “guides” within the “stories” folder. It is possible to (mis)use the story API for loading external documentation files as HTML. In such files, we can write down more specific Design Principles (the guide section) and some elementary CSS Styles tokens (Typography, text formatting, color sets and so on). My Git branch setup-atomic-design and its first commit shows how you can establish this.

The index.js file within the stories folder can become huge and unreadable very fast. Therefore, I highly recommend to distribute your documentation in separate files and folders. It makes the maintenance of your documentation much easier.

Please create and add two new folders with the names “tokens” and “guides” within your “stories” folder. Then create the files ta-token.stories.js file for the tokens folder and add this content to it. The same process we repeat for the guides folder with this content. Storybook will automatically import those new stories from the subfolder!

Please feel free to putter around and add more specific Design Principles (to the guide section), or add some more elementary CSS Style tokens (Typography, text formatting, color sets and so on) to your documentation. All the placeholder content is visible on Git branch setup-atomic-design and in its first commit.

Nested navigation and grouped content in Storybook

Sometimes you want to group some stories in one package, but you have to write several different stories. For instance, a collection of Design tokens or an Atomic Design component can be grouped like this. Once you have figured it out in Storybook, it is pretty easy and straightforward.

The “|” character within the story string allows you to group content. For assigning a different hierarchy level, please use the “/” character. Here is a example of deeply nested structure.

Now you are capable to group your components into a component package, or just create a set of different UI states.

If you don’t like the seperator characters, you can edit them in Storyboard config options hierarchySeperator and hierarchyRootSeperator (see here and here).

Adding an Atomic Design source structure

A documentation without source code is kinda senseless. Let’s start and add some source code along a Atomic Button example (I will explain later the Atomic Design principles in part 4 of this tutorial series). Please follow these steps.

1. Create a folder “src” within your project folder
2. Jump into the “src” folder and create the folder “components“
3. Jump into the “components” folder and create the folder “00-atoms“
4. Jump into the “00-atoms” folder and create the folder “button“
5. Jump into button “button” folder

Now you should be in folder “src/components/00-atoms/button/“, right? For creating our first Atomic Design template or UI component, we will create the “button.html” file. This files holds our HTML code of a Button and defines one display pattern of an Atomic Button (later it will be changed to a HandlebarJS template). The next step is the creation of the “button.json” file. This json files describes the content pattern of our Atomic Button template (similar to Pattern Lab and see the explanation by Dan Mall). The last created file is the “button.md“, which holds the short template documentation of the Atomic Button written down in a Markdown Format (again very similar to Pattern Lab).

Congratulations, you created your first Atomic template! Yeah, but wait, we are not finished yet. All our three files must be synchronized with our Storybook environment. Jump to your ./stories/index.js file and change the code of your story “Components|Atoms/Buttons” into this expression:

The result of an Atomic UI patterns can look like this in Storybook 4.x. On the left side (A) is the component explorer with its states and various navigation listings. The area (B) is the canvas, which renders your current chosen component (in an external loaded iframe). The bottom panel provides you some tools for documentation, testing and other developer tooling. For instance, the menu Notes (C) provides you some short markdown documentation (similar to the Pattern Lab component documentation). The Viewport Tool (D) enables the simulation of different screen sizes. I think, these two Addons are more than enough for our start with Storybook. If you want to know more, please feel free to play around with the other Addon packages.

All code changes are located in commit 8c6ab22. Please have a look at it.

Adding Markdown Rendering (optional)

If you want to write a whole page documentation in Markdown Format in Storybook, then it is possible with a little additional Webpack configuration. You need to add and install a markdown-loader:

Afterwards, please edit the Storybook Webpack config file and add this code.

Please consider, the new configuration transforms all Markdown files into HTML strings. If you doing very complex things, it might cause some breaking behavior inside your Storybook. If that case is true for you, then please check the more advanced webpack configuration or the storybook-readme addon. However, all changes are located on Git branch setup-atomic-design on Github, please checkout the commit 7b26395, too.

Next steps…

I would say that we achieved a very good progress. The infrastructure for a developer friendly, easy to use and ongoing documentation is built up and ready for the real work. Yael Balla summarized most points from above and some more during her great talk about Design System from a Developer point-of-view (Storybook included).

Currently, the Storybook Team are working on some cool new Styleguide Documentation features with the name Doc Blocks and MDX. I guess the Styleguide driven development with Storybook will become much more simple in the future.

The 3rd part of this tutorial series is my favourite part. Part 3 will deal with the integration of HandlebarJS and ports the Landingpage Tutorial by Jonas Duri into our Storybook environment.