Automated (or "living") styleguides are a popular topic in Frontend development these days. And it's no suprise, as they benefit the integrity of the project as well as ease design and development (Link to Joe’s article on why styleguides). Four Kitchens has a long history of using static styleguides within projects, but as the Frontend team reevaluated our process this year, we wanted to standardize around an automated styleguide for future projects. By automating this part of our process, we ensure the styleguide always reflects the latest design and code during the entire life of the project.
We began by evaluating existing automated styleguide tools and narrowed the selection down to a couple that made sense alongside our existing toolset: KSS (Link to Randy’s article) and Pattern Lab. We then committed to testing these in real projects to expose strengths/weaknesses so that we could eventually choose the best tool for our needs. Randy discussed KSS in a previous article, and in this article we will explore Pattern Lab. In the final article in the series, we will discuss which tool we settled on and why.
Pattern Lab is one of the more established styleguide tools out there and is the brainchild of Brad Frost, best know for his Atomic Design principles. When evaluating Pattern Lab, it’s best to start by understanding Atomic Design. Put simply, Atomic Design just asserts that like organic matter, design systems can be broken down into their smallest pieces and built up from there. In web development, this means we shift from the mentality of building “pages” to breaking down designs into patterns, organized smallest to largest, and use these building-block patterns to develop the project. Here are the categories commonly used in this approach:
- Atoms: Simple HTML tags (e.g.,
<button>,<input>,<h1>,<a>,<p>) - Molecules: Small combinations of atoms (search form, menu, lists)
- Organisms: Group of molecules forming a distinct design section (header, masthead, footer)
- Templates: Organisms combined to form contextualized designs
- Pages: Fully actualized templates often with real content
There is a video from the Pattern Lab website that demonstrates this best. Some folks get distracted by the lingo (atoms, molecules, etc.), but you should merely see these naming conventions as a way to break down components into a logical structure. Pattern Lab actually allows you to use any category names you want. Pattern Lab does, however, expect you to use Atomic Design in that it wants you to organize patterns smallest to largest regardless of the category names.
On the technical side, Pattern Lab is a static site generator powered by either PHP or Node that supports Mustache and Twig templating languages. The Node version has Grunt and Gulp support as well. Importantly, Pattern Lab is open-source and actively maintained.
In terms of built-in perks, Pattern Lab not only ships with a nice stock UI, it allows you to populate pattern data using JSON or YML and then annotate the patterns using Markdown. It also provides a way to easily create pattern variations as well as pattern states (e.g., in progress, needs review, approved). It also ships with a pattern searching tool and a viewport resizer in the toolbar to easily test/demo your components across any screen size.
Patterns are simply small chunks of HTML that may also contain CSS and/or javascript. In other words, there are no technical hurdles for a current Frontend developer to build these components - only the mental shift in breaking a design down to its logical atomic design parts. Let’s take a look at building a simple button component. We'll be using Twig as our templating language.
The button component is comprised of a file with the button’s markup (button.twig):
<a href="{{ url }}" class="button{% if variation %}--{{ variation }}{% endif %}">{{ text }}</a>
and a stylesheet containing the component styles (button.scss)
a.button {
background-color:#35AA4E;
border:none;
color:#fff;
cursor:pointer;
font-size:100%;
padding:1em 2em;
text-transform:uppercase;
&:hover {
background-color:#eee;
color:#35AA4E;
text-decoration:underline;
}
&--alt {
@extend .button;
font-size: 80%;
padding: .5em 1em;
}
}
To take full advantage of Pattern Lab, let's also create some default data (button text and url) and some annotations to help describe the component. For the data, let's create a simple button.yml file. Here's the contents:
url:
"/"
text:
"Default Button"
This is what will populate the Twig variables in our markup above. And now let's create an informative annotation that will display in the styleguide. For this, we'll create a markdown file (button.md):
---
el: ".button"
title: "Default button"
---
Here we can see the default button styling in action.
This all shows up in Pattern Lab like this:
https://www.dropbox.com/s/2k14s21knubdt4k/Screenshot%202016-10-05%2014.13.14.png?dl=0
As you can see, we have our component name, followed by our annotations with code snippets in both Twig and HTML versions (another Pattern Lab perk) and then we have the design element itself, our button.
Let's now add an alternative button option. It's as simple as adding an alternative yml file (button~alternative.yml). The tilde character tells Pattern Lab this is a variation, and Pattern Lab uses the name after the tilde as the variation name. Let's add this content to the file:
url:
"/"
text:
"Alternate Button"
variation:
"alt"
You may have noticed that button.twig contained a check for a variation variable that added the variation as a modifier class (class="button{% if variation %}--{{ variation }}{% endif %}"). This alternate yml file supplies that variable, which means our template will change the class accordingly. This is what Pattern lab looks like now:
https://www.dropbox.com/s/vn1egkrws00vqr1/Screenshot%202016-10-05%2014.33.50.png?dl=0
As you can see, Pattern Lab makes it quick and painless to create components with variations and metadata. From here, Pattern Lab also makes it easy to build nested patterns and to link patterns to one another to form a full, working prototype.
Adopting any new technology has its pain points, and it is of course no different with Pattern Lab. The latest version of Pattern Lab (v2) overcame our Frontend team's strongest critiques, namely that Twig is now natively supported and data can be specified in YML format. I personally also like that annotations can now be written in Markdown, as it is a great format for this type of notation. My only remaining critique is that while writing components comes easily, understanding the inner workings of Pattern Lab as a whole does take some effort. This critique, for me, is far outweighed by all the built-in perks I mentioned above but I thought it worth mentioning.
Overall, I would argue Pattern Lab is one of the strongest contendors on the market for creating an automated styleguide. If you would like to learn more, consider reading through the documentation on their website or jumping into the codebase. Mostly, I would recommend downloading and installing Pattern Lab, as it's the most rewarding way to learn atomic design while building an automated styleguide.