Atomic design, Pattern Lab and Drupal 8 theme development

When presented with something that almost instantly seems obvious, you don't need much more convincing. For me atomic design was like that. After making the choice to use atomic design and Pattern Lab in a real world Drupal 8 project and seeing the methodology validated, I have wanted to design and build all websites in this way.

The Holy Grail

Atomic design is both platform and tool agnostic and Pattern Lab is a static site generator. The philosophy of Pattern Lab is to reduce dependencies and keep things simple. So how does Drupal theme development fit in? How can we integrate atomic design and Pattern Lab with Drupal theme development? Can we achieve the Holy Grail of keeping the pattern library in sync with our Drupal theme?

Come together

As a first step we can place Pattern Lab in the Drupal theme folder. This is not necessary but does help in creating a strong mental association between the Drupal theme and Pattern Lab.

An added bonus in having a Pattern Lab instance in the theme folder is that we have a way to access Pattern Lab through the Drupal installation. The URL might not be pretty, but knowing that your theme's pattern library is always there with your theme brings a nice, warm feeling. And it is always possible to have a separate web server configuration for Pattern Lab.

Of course there might be cases where we don't want this, especially on production sites, so having Pattern Lab in the Drupal theme folder should always be optional.

Templates and templates

A Drupal theme has templates. Pattern Lab has templates. CSS is used to style the HTML produced from these templates. CSS is the obvious low hanging fruit that can be fairly easily shared between a Drupal theme and Pattern Lab. We only have to make sure that the naming and structure of the CSS classes (and the structure of the HTML, at least to some extent) stays the same.

It is of course possible to keep a Drupal theme's templates and Pattern Lab's Mustache templates in sync one way or another. But maintaining two sets of templates is not ideal.

Enter Drupal 8 with Twig theme templates and the Twig edition of Pattern Lab. Could there be a way to use the same templates with this combination? Well, unsurprisingly it turns out that there are some issues that need to be solved before Drupal theme templates are usable in Pattern Lab. I have covered these issues, and solutions for them, in a separate post.

But the good news is that after solving the aforementioned issues it is indeed possible to use the exact same templates for both Drupal and Pattern Lab. Then the only thing needed to achieve the Holy Grail is to come up with some conventions and best practices.

It's all about the structure

Drupal allows the organizing of a theme's templates in any kind of folder structure. This means that the templates can be placed in the standard folder structure expected by Pattern Lab. Drupal theme templates that are not used in Pattern Lab can be kept in a separate structure.

Drupal will even find the templates from inside a Pattern Lab folder placed in a Drupal theme folder. However, it is good to keep the theme and Pattern Lab decoupled. Automation and a tool such as Gulp can be used to watch for changes and to keep two sets of templates in sync. This can also be done with CSS files and other assets.

A CSS preprocessor such as Sass allows the compiling of the final theme CSS files from any kind of file and folder structure. Drupal CSS coding standards and atomic design are quite compatible and it is possible to organize CSS partials in a nested structure based on both.

What's in a name

Drupal theme templates not used by Pattern Lab can be kept out of the shared template structure, but Pattern Lab will require some templates not used by Drupal. Having Pattern Lab specific templates in a Drupal theme can be a bit confusing, but a naming convention can help. Such a convention already exists in the form of prefixing Pattern Lab templates with numbers. Number prefixes make it easy to see which templates are for Pattern Lab only.

Introducing Shila theme

This post has only covered the basics of one way to integrate Pattern Lab with Drupal 8 theme development. The best way to present this still experimental approach is to provide a working example.

Shila theme is an atomic design and Pattern Lab friendly starting point for new Drupal 8 themes. A Pattern Lab generated Shila theme style guide is also available on GitHub.