Living style guide meets Drupal 8

  • Krisztian Kovacs

Discover more about the services E-commerce and CMS our digital agency has to offer for you.

Times are constantly changing, and so is Liip. There is a particular term that caught our attention – living style guides. It might not be the latest or the coolest fad in web development, but tools that make Drupal 8 compatible with living style guides are fairly recent. That's why we decided to take a look at what's out there in order to introduce style guide driven development to our repertoire.

What is a living style guide?

A style guide in web development is a document that define the concept and look of your product. The exact contents of a style guide can however greatly vary depending on the company, project and development team. The general idea is that it should be a clear guideline for both the development team and the client.

What makes a style guide “living” is that the style guide is synchronous with the actual codebase. So basically you will have two “websites” that share the same CSS and the same elements. This ensures that the documentation stays up to date.

What is style guide driven development?

Style guide driven development is a workflow that decouples the frontend and the backend of the project. Basically you do all the UX and design work on the style guide, which contains every element and block that will be used for the final product, allowing you to ignore the current state of the backend development. A workflow that implements the style guide based approach might look something like this:

Style guide driven workflow utilizing living style guides

I. Ideation

First you gather the requirements and set the foundation for your project. Defining the basic feel of your product, including typograph, colors, and the elements that will make up your product.

II. Atomization

In a second step, you take all the elements that you have defined, and take them apart into smaller pieces. You repeat this step several times until you end up with a collection of patterns and small components. I would also like to invite you to read Marc Drummond's  blog post about component-based theme systems.

III. Implementation

This is the part when you start implementing the style guide itself. This is also a great opportunity to test your design in different browsers, to play around with elements, and test their re-usability.

IV. Integration

In this phase all you have to do is to integrate the components and patterns from the style guide in our product. This sounds easy, but you might notice some issues that you didn't consider before. That's also one of the good points of this workflow – you can always go back to the first step to re-evaluate the situation, and either create new elements or even adjust existing ones.

Implementing living style guides in Drupal 8

After we have realized the advantages that living style guides could bring to our team, we decided

Drupal logo Liip green
to first make an evaluation phase. Everyone from our team had the opportunity to present a possible solution, regardless of their role and experience. We did however agree on the following guidelines to make the evaluation smoother:

  • The style guide has to be integrated into a Drupal 8 Theme.
  • The taskrunner has to be Gulp.js / Node.js.
  • As a CSS preprocessor we went with SASS.
  • Lastly we agreed on using the Zurb Foundation CSS Framework.

Out of the several technologies that we evaluated, there were two that we considered mature enough for building our next project on either of them: kss-node and Pattern Lab.


The first one is kss-node, a kss based Drupal 8 solution by none other than John Albin, creator of the Zen theme.  Albins kss-node, as the name already suggests, is based on Knyle Style Sheets, which generates style guides based on the comments and rules in your stylesheets. Setting it up is pretty straightforward, which might be a deciding factor based on the technical background of your team. You also have a lot of freedom in tweaking the generated style guides. This means you will have an easier time presenting the style guides to your customers. The only drawback I see going this way is that KSS gives you a more or less set way to structurize your stylesheets. Other than that, it's a handy tool that serves it's purpose.

Pattern Lab

The second is Pattern Lab, a static site generator for PHP and Node. Pattern Lab places much more focus splitting up components. You basically have five different levels:

  • Atoms, the smallest component that can exist. Just like in chemistry! Text areas, buttons and icons would fall into this category.
  • Molecules, several atoms that make up a single component when placed together.  A good example would be a search text field and its search button.
  • Organisms are compound elements too big to be molecules, but not big enough to be templates. For example a blog comment with all the details and a reply button.
  • Templates are the biggest building blocks that cover a section or even a whole page of the website. This would be a blog post with a title, breadcrumbs and a comment section.
  • Pages, templates filled with actual content.

Getting Pattern Lab to work with Drupal 8 isn't an easy task. For this reason I recommend using the Shila theme by Aleksi Peebles. This theme comes with a starterkit which does a large chunk of the tedious work for you. It also comes with some nice extras like switching between breakpoints in the style guide itself. This is a handy feature if you plan running automated tests with Selenium. You will probably want to spice the theme up a bit if you decide to use it in a real project though.

Final thoughts

The mentioned solutions are very similar, yet somehow different. Pattern Lab takes more fine-tuning, and you will have to put in some effort to take advantage of all the features it offers. On the other hand, kss-node also offers you flexibility, but looks clean and professional even out of the box. Me as a developer lean towards Pattern Lab, but I have to agree that kss-node seems to be more attractive for people less versed in technical stuff, including clients.

In any case we look forward to give style guide driven development a real try. Do you have any experience with living style guides or style guide driven development? Share it below in the comment section!

Tell us what you think