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.
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.
Creating the Living Style Guide
It’s important to note that this section assumes you have a copy of the Open Social distribution running locally on your development machine (here’s where you can install the Open Social distro if you’re looking for it).
This demonstration uses a copy of the Social Blue theme, but you can implement the style guide using any custom theme. The Social Blue theme ships with the KSS style guide. Once we have the style guide up and running, the final result will look like this. Here we go!
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.
In this demonstration, a namespace was created in the theme’s .info.yml file, just like this:
(More documentation is available on the module’s drupal.org project page)
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).
Read the Social Blue readme and follow the instructions to create your own custom theme. Once you have updated the package.json file and the gulpfile.js with those provided in Lisa's demo repo, refer to the Social Blue readme again, and follow instructions under the heading “Working with Gulp”. These steps will install the theme’s dependencies.
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.
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.
Conceptually, we are dealing with 3 layers.Drupal core SocialBase component library (as CSS/js already compiled) and Drupal templates (handled by Drupal’s theme layer) Custom theme extending base component library and drupal template
Diagram of how a component library, KSSNode style guide, and Drupal theme work together to make a living style guide
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.
What you need to know:Drupal and Twig KSS style guide (additional documentation) Drupal theme CSS/JS