An Introduction to Atomic Design and Pattern Lab in SiteFarm

by Anthony T Horn
June 21, 2018

The Hook

The backbone of the SiteFarm theme is a solid front-end design. This design is comprised of well-written, modern, and maintained Javascript and CSS. This code is kept inside of a framework called Pattern Lab that allows us to design, review, and share the look of the theme outside of the SiteFarm CMS. Gulp.js is a workflow automation tool we have nested within the Pattern Lab framework. It allows us to validate JS/CSS, compile syntactically awesome style sheets(SASS), minify code, and export our work into the SiteFarm CMS.

"Pattern Lab helps you and your team build thoughtful, pattern-driven user interfaces using atomic design principles."

The History

We began working with Pattern Lab as a means to quickly conceptualize and create the front-end of a website without the complexity of simultaneously building the back end. This allowed us to present a simple interactive version of a web project to a client for approval without having to complete the project. The framework is conceived around Atomic Design principles, devised by Brad Frost.

Atomic Design

Atomic design works around the concept of Atoms, Molecules, Organisms, Templates, and Pages.

Atoms: The smallest items in a web design are Atoms. These are things like buttons, links, headings, tables, etc.
Molecules: Slightly more complex patterns comprised of Atoms are Molecules. These are small patterns like a single teaser display or a small sign-in form.
Organisms: Even more complex patterns are Organisms. Examples include a list of teasers with a pager, the header or footer of the site, or a complex form.
Templates: Atoms, Molecules, and Organisms are then juxtaposed together to create the templates that represent the primary pages and content types of the site. A .json file is used to populate the content of the site using placeholder text.
Pages: Pages are duplicates of Templates, but use an overriding .json file to inject actual text and image content consistent with the desired end product of the site.

An Important Concept

Notice in the above list of Atomic Design elements I used the term pattern. CSS patterns are an important concept both in Atomic Design and in modern front-end development. In the past pieces of a website would be created in one-off states. The result is similar code being written over and over to work in different areas. An item like a button might be styled as a sign-in button, call to action button, regular button, sidebar button, etc. This produced messy and confusing code. The solution is to create a button pattern. This pattern can then be used anywhere and can be modified to meet different needs. So you might have a button, .button, with a modifying class of .button button--bright that would change the color of that button.

One of the code conventions we use when writing CSS or SASS is BEM. BEM stands for Block, Element, Modifier. This syntax lends itself really well to the nested nature of writing SASS. Here's an example of a teaser classed using BEM syntax. Let's start with creating the Block.

<div class="teaser"></div>

See that our block is classed as teaser. Now let's add some elements to our teaser.

<div class="teaser">

<img class="teaser__image" src="/images/some-image.jpg"/>

<p class="teaser__text">Lorem ipsum dolar.<p>

</div>

In BEM syntax, elements nested inside a Block are classed with the Block name, two underscores, and the Element name. Now let's look at a teaser with a Modifier.

<div class="teaser teaser--featured">

<img src="/images/some-image.jpg" class="teaser__image"/>

<p class="teaser__text">Lorem ipsum dolar.<p>

</div>

In BEM Modifiers consist of the Block name, two dashes, and the modifier name. You can see how this is really helpful to us to be able to create a teaser pattern, style elements of that pattern specific to it, then modify its appearance when output in an HTML template by adding modifier classes to style it based on context.

The Interface

Pattern Lab not only gives us a space to create, it gives us a place to demonstrate, test, and share. Pattern Lab has its own user interface. The interface consists of a menu with drop downs for Atoms, Molecules, Organisms, Templates, and Pages. Choosing a pattern from the menu displays that pattern in the interface with a draggable bar that allows you to resize it inside of the browser window without having to actually resize the browser. There are also buttons in the upper right of the interface that allow you to quickly resize the pattern to Small, Medium, or Large. The eyeball icon contains options for showing any annotations provided for that pattern, show the code, or open the pattern in a browser window outside of the Pattern Lab interface.

The Pattern Lab Interface — SiteFarm Pattern Lab Interface.

Showing the code is a valuable tool for developers working on a subtheme or just trying to implement existing patterns into things like new views in Drupal. When viewing the code, an inspection style area opens at the bottom of the page allowing you to view both the HTML markup and template code. This is a good way to see the structure of CSS classes and elements required to leverage the styling and js. Another useful aspect of the code window is it provides a series of links to other patterns that this pattern is constructed of and included in. This allows you to quickly piece together all the patterns involved.

Upper Right of Pattern Lab Menu — Pattern Lab Interface Settings

The last tool is the gear icon which provides links to a number of resources for understanding how to use Pattern Lab including our Sass Docs. The Sass Docs is a useful index of SASS mixins and placeholders used within the SASS code for our Pattern Lab. This is very handy for the developer who is going to clone the Pattern Lab and continue to build upon it or alter it in some way.

One of the goals for designing our SiteFarm Pattern Lab has been to keep the code non-specific to the CMS for which we are using it. Our hope is that others who want to implement the design on another system can do so without running into coding specific to SiteFarm.

Yet another neat feature of Pattern Lab is pattern states. Patterns can be flagged as:

inprogress: pattern is in development or being worked upon. a red dot.
inreview: pattern is ready for a client to look at and comment upon. a yellow dot.
complete: pattern is ready to be moved to production. a green dot.

Pattern state example — Pattern State Example

This is great when developing for a client as they can browse the library with indicators of the status of each pattern.

Though we use it as storage for our front-end development on its way to Drupal, it is possible for Pattern Lab to be used as a static website generator. If properly linked up, the pages are stored as static HTML in the public directory and can be viewed outside of the interface.