Creating a Living Style Guide with Open Social

The following blog was written by Drupal Association Signature Supporting Partner, Open Social by GoalGorilla.

A living style guide – a way to control markup or CSS – has been making a name for itself. And for a good reason; they’re an important tool for web development. They keep developers in sync, communicate design standards, and help organize complex interfaces. In this post, I want to discuss how and why living style guides are important and how to implement one for Open Social using Drupal for software.

We’re using a living style guide because it serves as a valuable internal resource for development; we’re able to write reusable and consistent code that’s easy to maintain. And it’s a great external resource for client deliverables. Ready to see how to make a living style guide work with Drupal software? Let’s go!

Moving From Static to Dynamic

We didn’t always rely on a living style guide. Open Social was built and maintained using different strategies such as component libraries and atomic designs. These strategies have advantages, such as reusability, facilitating collaboration within the team, and ensuring design consistency. There were, however, disadvantages to a static style of working.

In the past, a component library or style guide was usually graphic-based. The designer would create a visual representation of a component (in PS or Sketch, for example) and then the front-end developer would transfer these visuals to HTML and CSS. This immediately meant double maintenance; for instance, if the markup or CSS changes, the graphics style guide would need to be updated to reflect this change and vice-versa. In our experience, the shelf life of these “static” systems is only a few iterations before the graphic version gets left behind and forgotten due to too much maintenance and not enough return. Yikes.

This is why we decided that it was time for a change. What we needed what a more dynamic system: a living style guide.

A Living Style Guide Is the Best

Any style guide is better than none but a living style guide is the best.

A living style guide consists of a single source of code, thankfully. The style guide’s markup, javascript, and CSS are the same as what was used in production. This provides a wide array of benefits. See below!

Sharing design capabilities. Our team easily shares design capabilities between designers and front-end developers, which also benefits the backend developers and project managers who work with us.

Less reliance on other team members. The developers refer to the style guide and reuse components for new features without being heavily reliant on the designers and front-end developers for implementation.

Most importantly, the client benefits. The project manager offers new feature ideas and lower-cost solutions to the client, based on reusing and recombining existing components. Inevitably our clients benefit from this, especially when they begin thinking this way themselves.

While this blog post focuses on how we work on Open Social enterprise projects, it is also an accurate reflection of working in the Drupal frontend nowadays. A quick google for “Drupal Living Style Guide” can give you some ideas about the current popularity, challenges, and general atmosphere surrounding the subject. In the next section of the blog, I will take you through the steps of setting up a living style guide with Open Social.

Side note: refer to this GitHub repo for an example of a component library within a Drupal theme folder structure, and package.json with dependencies, gulpfile.js for run KSSnode style guide and generate assets for the Drupal theme.

The Drupal Component Library Module and Twig Namespaces

The living style guide firstly requires the Component Library Drupal module to get up and running. The Drupal components library allows us to create custom twig namespaced paths. This means we are not limited to placing our components in the Drupal theme templates folder (as the current Drupal 8 architecture dictates).

The KSS style guide lives in our theme directory but has no knowledge of Drupal. This is what makes it so flexible. In theory, we can copy the component library directory and use it in other (non-Drupal) projects. A big thanks to John Albin, the maintainer of Zen Theme and KSS node, for paving the way for us to implement our theme and style guide.

Once the namespace has been defined, you can include and extend twig templates from the component library, Drupal’s template override files and other components (like in an atomic design approach) by simply referring to the files like this:

Social Blue comes with the style guide ready to go (read the Social Blue readme and follow the instructions on how to create a custom theme from it). However, because we have copied this to our custom theme folder, the gulpfile that runs the different tasks needs to be updated to reflect the new location in relation to the base theme (socialbase).

Compiling the Style Guide

Basically, most of the action happens in the gulpfile. Spending some time reading its comments and exploring it really helps you understand the dynamics of linking a Drupal theme with a living style guide.

If we refer to the package.json, we will see which packages we have installed, and by examining the gulp tasks and configuration, we can get a sense of how the style guide is compiled from our component library and theme files.

The Theory

We are relying on Drupal’s theme layer to render the twig files from our components and attach the libraries (our CSS and js). We also rely on the component module to create the namespace allowing us to map Drupal variables with the json variables in our style guide.

The style guide copies Drupal’s theme assets (CSS and js) and has its own twig compiler (see os-builder folder).

The end result is the style guide made up of CSS/js copied from the base theme’s assets folder, our theme’s assets folder, and HTML generated from the twig and json, from our component library. The CSS/js copied from the assets folders need to be included in the gulpfile to be copied into your style guide.

(Side note: a nice little improvement is to have a designated folder, therefore avoiding the need to list each file.)

The Drupal HTML pages and the style guides are not shared. This is important to point out because caching might affect each differently.

The style guide isn’t a layer because it doesn’t know Drupal exists beyond sharing the files in the component library directory. This concept illustrates one of the powerful elements of a dynamic component library – you can copy it from project to project, regardless of the environment, because in the end, all it really is is HTML, CSS, and javascript (see image below).

Diagram of how a component library, KSSNode style guide, and Drupal theme work together to make a living style guide

In Conclusion…

For front-end developers and designers, a living style guide is becoming an essential part of the web developer’s toolkit.

We are able to focus on the implementation of design components while the backend is being built, thus working in parallel with our team members instead of relying on others to finish before we can start.

We can do browser and accessibility tests on a component level, thus improving the quality of features (current and future). Another benefit (one that deserves a blog post on its own) is implementing visual regression testing on the living style guide to help spot changes in HTML or CSS negatively affecting existing elements.

The time investment needed, especially for a complex project, is nothing compared to the peace of mind knowing adding new elements does not break others.