A Style Guide Driven Development Workflow for Drupal 8

Tags:

January 23, 2017

As I spend more time working with Drupal 8, I’ve taken the opportunity to redefine my theming workflow to incorporate style guide driven development techniques that I had used in fits and starts on Drupal 7 projects. I fully expect this process to continue to evolve over time, but the current approach has served nicely for Drupal 8 projects thus far, and also appears to be well suited to accommodate some of the component-based rendering approaches that look to be part of Drupal’s theming future.

Let’s discuss the groundwork that this entire workflow depends on — a design system.

Part 1: Developing Your Design System

At a high level, style guide driven development is an approach that decouples front and back end development. It allows the look and feel of the components on the site to be developed before the functionality actually exists. With this approach, look and feel can be developed at any time. No more swooping in for a theming phase late in the project.

A key component that makes this approach possible is the living style guide. A living style guide is a live reference of the visual language of your site or application, including all of the guidelines, elements, components, and templates on your site. It can include elements that have not yet been implemented and ones that are already live. It might be used internally by your team, shared with a client, or made available publicly for all to see. The Starbucks style guide and the US Web Design Standards both serve as excellent examples of what a living style guide could look like.

For example, if the look and feel of a component have been defined in advance, a backend developer should be able to ensure that during implementation the output includes the intended markup and classes, and in theory, the component should just magically look as expected. Of course, it requires the thoughtful development of a design system to achieve this.

The living style guide will be the cornerstone of your design system and I believe that there are four key elements that can make a living style guide especially useful.

A Living Style Guide is Modular and Re-usable

Rather than taking a page-based approach to design, your living style guide should consist of a number of smaller, reusable components. Ideally, ones that can be used in combination to create larger, more complicated components. If for example, you use a search bar throughout your site, it should look the same and consist of the same markup everywhere it is rendered.

This may ring a bell to some as Atomic Design. I’m a fan of Atomic Design, but really any mental model that helps you move away from implementing unique instances of pages and into a system that consists of reusable components is a step in the right direction. As you might imagine, the more you understand your design system, the more likely it is to be implemented consistently and the better you can later use it to protect you from regressions.

A Living Style Guide Uses Real World CSS and Markup

Your style guide should use the same CSS and markup as your site. The more your style guide reflects reality, the better. This is especially useful if you’re using a style guide as part of a visual regression testing strategy. 

The CSS part of this is usually pretty straightforward. If your style guide loads the same CSS that your website does, you’re most likely checking the box. Many of the style guide generators often used for this task provide options to import one or more CSS files.

Using real-world markup can be quite a bit harder. Consider the workflow where a component is first defined in the style guide and then the markup from the style guide is copied and pasted to be used for implementation. In a perfect world, that goes without a hitch. But maybe there were some adjustments that could be made in order to simplify the effort of the implementation. That adjustment or any future ones need to make it back into the style guide. Obviously, it is possible to maintain all of this, but it requires quite a bit of discipline and attention to detail.

As a result, there has been quite a bit of experimentation in the Drupal community to find ways to get Drupal 8 to play nice with popular style guide generators and share the exact same markup. We’ll look at some approaches in the second part of this series.

A Living Style Guide is Always Kept Up-to-Date

What this really comes down to is that your style guide needs to be generated automatically. Otherwise, your style guide will quickly be no better than the PDF style guide you might have worked from in the past that became outdated the second it was handed off to you.

Task runners like Grunt and Gulp make it easy to automate this; whenever your SASS changes, your style guide should be re-built as well. Many style guide generators have Grunt or Gulp plugins to make this easier. This isn’t completely magic though; you still need to add documentation to your sass partials so that your style guide generator can pick up on them.

A Living Style Guide is Testable

Creating a Drupal theme that looks as you intend it to can be difficult. But once you’ve created something that matches the intended design, making sure it stays that way can be even harder. Thankfully, by developing your design system you now have a much better understanding of the components that make up your design and also have a useful framework for test coverage. 

There are now a wide variety of visual regression tools that can help you guard against potential hiccups in your theme. These tools can take screenshots of your site and alert you to when things change, even creating a comparison image illustrating the differences. The end result could look something like this:

Baseline

 

Regression

 

Diff

Rather than testing manually or comparing full pages, tests that target the components in your style guide make it easy to determine exactly where things changed, and how that impacted the rest of your site.

How Theming Enhancements in Drupal 8 Help

As you might know, quite a bit has changed in the theming world in Drupal 8. The good news is that many of these changes give you increased control of Drupal’s markup and allow you to better define and target re-usable components. In short, Drupal 8 wants you to build better themes. Here’s are a few things that can help:

  • Drupal 8 Core’s Stable and Classy base themes give you cleaner markup as a base to build off of. Use Classy if you want a slightly saner version of Drupal 7’s default markup. Use Stable to start with the bare minimum of markup and classes applied. And don’t be a hero, always use a base theme. (Looking for more? Marc Drummond’s ‘A Tale of Two Base Themes in Drupal 8 core’ is a great read.)
  • Drupal 8 follows component friendly CSS coding standards and you should too. The CSS File Organization documentation recommends a SMACSS-like file organization approach and the CSS Architecture documentation recommends a BEM inspired naming convention. 
  • Drupal 8 and Twig encourage a cleaner separation between logic and display. Take the following simple example from block.html.twig in the Classy theme:
{%

           set classes = [

                     'block',

                     'block-' ~ configuration.provider|clean_class,

                     'block-' ~ plugin_id|clean_class,

          ]

%}

< div {{ attributes.addClass(classes) }}>

…

</div>

In Drupal 7 this was likely to have been done in preprocessor or theme functions instead. In Drupal 8 an effort was made in Drupal 8 to move all classes from preprocessing to Twig templates. As a result, you should need to dig around in PHP far less often to find where classes are set and you should be following the same approach in your themes.

{{ attach_library('fluffiness/cuddly-slider') }}

This all makes it much easier to include assets only where needed.

In short, the effort to build an intelligent design system should be more pleasant in the brave new world of Drupal 8 theming with Twig.

Looking Ahead

If you’ve carefully considered your design system and taken advantage of new tricks in Drupal 8 to build cleaner, reusable components, you’re on solid footing to take advantage of this groundwork in a variety of ways. In the remaining posts in this series, we’ll look at how we can generate a style guide for your theme automatically, and also use it for automated testing.

Recommended Perspectives