Upgrade Your Drupal Skills

We trained 1,000+ Drupal Developers over the last decade.

See Advanced Courses NAH, I know Enough
Nov 17 2016
Nov 17
November 17th, 2016


Automated (or “living”) style guides are a popular topic in frontend development these days. And it’s no surprise, as they benefit the integrity of the project as well as ease design and development (as you can see in Part 1 of this miniseries!). Four Kitchens has a long history of using static style guides within projects, but as the frontend team re-evaluated 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 style guide always reflects the latest design and code during the entire life of the project.

We began by evaluating existing automated style guide tools and narrowed the selection down to a couple that made sense alongside our existing toolset: KSS 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.

Pattern Lab & Atomic Design

Pattern Lab is one of the more established style guide tools out there and is the brainchild of Brad Frost, best known for his “atomic design” principles. When evaluating Pattern Lab, it’s best to start by understanding atomic design.

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:

  1. Atoms: simple HTML tags (e.g., <button>, <input type="text" />, </button>
    , <a>, </a></h1>)
  2. Molecules: small combinations of atoms (search form, menu, lists)
  3. Organisms: groups of molecules forming a distinct design section (header, masthead, footer)
  4. Templates: organisms combined to form contextualized designs
  5. 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 see these naming conventions as only one 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.

Pattern Lab

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 YAML 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.

Building Patterns in Pattern Lab

Patterns are 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="https://www.fourkitchens.com/blog/article/frontend-style-guide-miniseries-part-three-pattern-lab//{{ url }}" class="button{% if variation %}--{{ variation }}{% endif %}">{{ text }}</a>

and a stylesheet containing the component styles (button.scss)

a.button {
  padding:1em 2em;

  &:hover {

  &--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:

  "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 style guide. 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:

Screenshot one.

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:

  "Alternate Button"

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:

Screenshot two.

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.

Final Thoughts

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 YAML 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, debugging or tweaking core Pattern Lab does take some effort as the codebase is fairly large. 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 contenders 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.

Stay tuned next week for the thrilling conclusion of our Frontend Style Guide Miniseries!

Recommended Posts

  • In this issue: come see us at DrupalCon Amsterdam, Instagram CSS3 filters, ontology is overrated, Douglas Crockford: the better parts, iPhone promo products from Japan, Go-powered robots, tree simulator MMO,…
  • In this issue: Come hang out with us at DrupalCon LA: we're speaking, training, playing Drupal Games, and bowling with Aten and Kalamuna! Plus, Markdown Here, more responsive media sites,…
  • In this issue: DrupalCamp Stanford 2015, party at DrupalCon Los Angeles, Headless Drupal and Frontend Performance training, and UX methods; plus WIRED's new multimedia stories, the look and feel and…
Evan Willhite
Evan Willhite

Evan Willhite is a frontend engineer at Four Kitchens who thrives on creating delightful digital experiences for users, clients, and fellow engineers. He enjoys running, hot chicken, playing music, and being a homebody with his family.

Design and UX

Posts about user experience: best practices, tools we use, methodologies we love. Posts about the design process: wireframes, colors, shapes, patterns. Frontend posts that focus more on the user interface aspects (visual, aural, etc.) than on coding practices.

Read more Design and UX
Oct 20 2014
Oct 20

Recently 10 members of the Drupal development team at Capgemini went to Drupalcon Amsterdam. Having been to two Drupalcons before, I more or less knew what to expect, but something I hadn’t previously given much thought to was how big an event it is. Compared to most other web conferences, it’s a beast. For me personally, I wonder if it’s getting too big and too impersonal, and I think that I’ll be more interested in going to smaller events.

Some of the more interesting sessions for me were the BoFs - in particular a discussion of open source training material and apprenticeships provided a lot of food for thought, and hopefully we can get involved at some level. Capgemini already does a lot of work getting graduates and apprentices into our engineering practice, and with such a big Drupal team, I hope we can benefit from and contribute to the Open Drupal initiative in 2015.

Whenever I go to an event, I come back with a to-do list, and this was no exception. I’ll definitely be digging further into CasperJS following Chris Ruppel’s session on Automated Frontend Testing. I was also very interested to hear about the way that Lullabot spin up test environments for pull requests - it will be good to investigate the feasibility of incorporating this into our workflow.

The other talk that stood out for me was John Albin Wilkins on Styleguide-Driven Development. For a long time, I’ve had a bee in my bonnet about the value of component libraries over Photoshop comps, and it was good to be reminded that I’m not alone. In an interesting session, John outlined an approach to integrating component-based design and automated style guides to agile development projects.

It’s been said many times before, but it’s worth remembering that all too often, people are still thinking in terms of pages, rather than systems.

In the context of the work that we do, this is even more important. We’re a large development team, building CMS-driven sites for large corporate clients, where the design is done by a team working for another company. We’ve made some inroads into building a more collaborative process, but it’s still too easy to end up with the designers throwing things over the wall to the developers. Very often the designer isn’t closely involved during the build phase, and design tweaks are agreed between the client and the developer without the opportunity to go back to get the designer’s opinion.

This is the whole point of living style guides - component libraries that stay in sync with the code as it evolves. As Shay Howe has discussed, component libraries help everyone on the project.

Designers are reminded of the visual language of the project, and it’s easier for them to see when they’re about to reinvent the wheel.

Style guides help developers by defining and documenting standards, and make it easier to dig in and find the way you solved some problem six months ago.

The projects we work on are large and complex, with a long lifecycle, and as developers we need to value maintainability of the front end code. Part of John’s approach to this was his class-naming convention. Having seen Jonathan Snook present on SMACSS I’d thought it was interesting, but to a certain extent it felt like a fancy name for something that was basically common sense. John’s presentation brought the concept to life well, and persuaded me that there’s more to it than that, with an impressive display of flower power.

The other interesting aspect was splitting up SASS files into components, and using KSS to create the style guide - this is something I definitely intend to do on my next project.

Modularity makes sense - it’s how the back-end is going, it’s how Javascript is going, so why shouldn’t design and CSS go the same way?

UPDATED 3rd December 2014: Unfortunately we got Chris Ruppel’s name wrong in the original version of this post, calling him “Dave Rupl”. Sorry Chris.

About Drupal Sun

Drupal Sun is an Evolving Web project. It allows you to:

  • Do full-text search on all the articles in Drupal Planet (thanks to Apache Solr)
  • Facet based on tags, author, or feed
  • Flip through articles quickly (with j/k or arrow keys) to find what you're interested in
  • View the entire article text inline, or in the context of the site where it was created

See the blog post at Evolving Web

Evolving Web