Automating Living Style Guides in a Drupal Theme

Over the past year or so here, we’ve tried to make front-end development less painful by creating living style guides in our Drupal themes that we can use internally as a valuable resource during development, as well as externally as a client deliverable. They allow us to write consistent, reusable and efficient code that is easy to maintain over the lifespan of a project. In addition, they show our design standards and prototypes that we can play with in a browser, at different sizes and in mobile devices, before things are truly functional and placed on an actual page of the site.

Though it takes more work at the beginning to set up, it definitely pays off in the long run. Ready to make an automated, living style guide work within your Drupal theme? Here’s how:


Using KSS and Grunt together to build a living style guide

Knyle Style Sheets (KSS) allows us to add special code comments to our Sass/CSS to specify the site’s repeated patterns, branding, color palette, typography, components and Drupal blocks/panel panes. When the Sass is saved and compiled it gets generated into a nice and clean style guide via kss-node (the NodeJS implementation of KSS), immediately viewable in your web browser. If you don’t like how the default style guide looks, you can customize things with KSS Node Template or just customize the default, vanilla style guide template. (However, recent improvements in kss-node – like being able to specify markup or a template file for everything that gets compiled into the style guide – have made KSS Node Template less useful for us.)

Grunt tasks have been great for us, helping automate some of the stuff we regularly do manually.  For example, updating the style guide files the moment that there’s a saved change to the Sass files we’re working on:

watch: {
 css: {
  // Here we'll config grunt-contrib-watch to keep an eye on any .scss file, in any directory in the theme.
  files: ['**/*.scss'],
  // When one is changed and saved, let's run the sass task to compile CSS.
  tasks: ['sass:dev']

things get turned into CSS

sass: {
 dev: {
  options: {
   // Since we're compiling a "dev" version of the CSS here, let's make it expanded output style so we get all the little helpful references to where the CSS originates from in the Sass.
   outputStyle: 'expanded',
  files: {
   // Advomatic standard practice is to have one single manifest file (styles.scss) where we import various partial Sass files in the order we want them compiled. We'll specify Sass to compile CSS exactly where we want it, in this case... css/styles.css.
   'css/styles.css': 'sass/styles.scss'

and then the style guide gets regenerated on the fly.

kss: {
 options: {
  // Link to previously compiled CSS.
  css: '/sites/all/themes/custom/mythemename/css/styles.css',
  // Link to theme JS.
  js: '/sites/all/themes/custom/mythemename/js/script.js',
  // Set our custom template to build styleguide from.
  template: 'mythemename-styleguide-template'
 dist: {
  files: {
   // "styleguide" is the destination directory, the source directory is "sass"
   'styleguide': ['sass']

With this setup in the Gruntfile.js in your theme directory, you can view your style guide directly in your browser by viewing That’s kind of a long URL, but we can make it more digestible by setting up a redirect to point that long path to a shorter path, like

Drupal markup examples

You know them, you love them! Drupal has a bunch of “pieces” that you usually have to style on every site you work on; tabs, error messages, pagers – that kind of thing.  A great way to see all the different stuff that could appear in your Drupal site is to download and install the styleguide module (check out this demo site to see it in action).  You might not want all of that stuff in your KSS style guide, so just pick and choose the stuff you do want to use.  For adding more standard, non-Drupal-specific HTML elements and design patterns to your style guide, Brett Jankford’s Style Guide Boilerplate is an excellent source of markup chunks.

Let’s say you want to add the Drupal pager to your style guide.  

The latest version of kss-node allows you to specify a file containing a markup example template file (either .html or .hbs) for each section of your style guide.  You can then copy the default pager markup that gets rendered from the styleguide module’s page for your theme at at, and stick it into a pager.html file in your theme and tell KSS where to find it via the KSS comments in your Sass, like so:

// Pager
// Markup: pager.html
// Styleguide: pager

After you compile your style guide, you will find a “Pager” section that has a prototype (non-functional) pager example using the markup in the pager.html file you added.  You can then style that example as you wish.  Note: the filename should be relative to the .scss file you’re specifying it from.

Pager example

Pager example within the KSS styleguide, as well as a background grid (via Susy)


In conclusion

This is just a brief overview of how to make an automated KSS/Grunt living style guide work within your Drupal theme, and there are even more ways to make your it more organized and comprehensive.  We have definitely found that a little work setting up a living style guide during your initial theme setup goes a long way during the project. The result is a constantly updated library of default styles, patterns and prototypes (with markup examples) that serves as a valuable team and client resource.

For an excellent overview on the resources for building (as well as the benefits of) living style guides, you must read my fellow Advomatic front-ender Amanda Luker‘s excellent recent post.

You should also check out:


13 Responses to “Automating Living Style Guides in a Drupal Theme”

  1. Chen Hui Jing on

    Thanks for yet another really informative article style guides in Drupal. I’m going to try out the bit on Drupal markup examples because it sounds like a really good idea. Was wondering if you guys have experience with the gulp-kss plugin, but since you appear to be using Grunt, I guess probably not.

    • Jack Haas on

      Your welcome! I gave gulp-kss a try (very briefly) about a year ago when I was weighing Grunt vs. Gulp, and at the time there just wasn’t the variety of Gulp tasks out there that made it attractive to me over Grunt. So here I am, with grunt-kss.

    • Jack Haas on

      Thanks, was not aware of this! Before we were using KSS, we did use styleguide (and still do to some effect) and I had always hoped for that kind of functionality.

    • Dave Hansen-Lange on

      The downside of that approach seems to be that you loose the ability to have front-end and back-end teams working in parallel. While a front-end developer is creating a prototype in KSS, a back-end developer can be creating the entity bundle, and programming display logic. If you use

      Style guide view modes, someone’s got to do that back-end work before it can be styled.

    • Dustin LeBlanc on

      Nope, actually this works concurrently, all you need is Drupal installed, theme setup (all your grunt config and what-not) and you just create HTML snippets, commit them to the directory storing the snippets, and share. You navigate to the styleguide pages and there is your HTML snippet, rendered in all it’s glory, never touching any of your site’s backend content types, templates, or any of that. The module mentioned actually enables this concurrency because themers can create the markup before there is a content type/node/whatever to apply it to.

      The backend team, or a savvy enough front end developer then backport that markup into an approriate template once they have the data back-end.

      One big advantage here is that this all happens inside your theme and inside Drupal. You write the styles once, and there is no external build process or need to host the styleguide elsewhere for the folks writing the checks. You just point them at the styleguide URL and what they see is what they get 🙂

    • Jack Haas on

      Dustin, when you say “backport that markup into an appropriate template” do you mean whatever override theme template you’d normally use to provide your own markup for something (a view, a panel pane, whatever…)? Or are you referring to some new/other kind of template somewhere that the styleguide module would then use to render a “real” version of your component or whatever on the styleguide page (as opposed to the static version you started with via .html or .inc file)?

    • Dustin LeBlanc on

      I mean to create the actual theme thing–more-specific–thing.tpl.php to theme Drupal’s real output; or whatever method (fences, views fields, etc.) you would use for the final markup. Once the theme css is written and the example markup has been presented in the styleguide, this is the last step to make the theme display it using real production data 🙂

    • Jack Haas on

      OK thanks, just thought I’d ask. We’re on the hunt to figure out how we can eliminate the static/example version of the markup and have a styleguide render a “real” copy of things – so there’s no need to maintain/update two copies of markup when there are changes – what’s in the styleguide vs. the “real” template version on the site.

    • Dustin LeBlanc on

      It would be great to have someway of backporting changes from a linked tpl file. We’d need to bind a snippet to a template it seems to make that work. I like the idea. Doing it within Drupal sounds like a hairy job, but those are the best ones to tackle in the end right?

  2. kendalltotten on

    Any concerns about creating technical debt by copying and pasting markup? As in, whenever the markup on your site changes, you are responsible for going back and updating the code in your styleguide templates. Has anyone created component templates that can be used by both the actual website *and* the styleguide?

    • Jack Haas on

      Yes, that’s the downside. However, I think the benefits of getting things prototyped and in a browser far outweighs the technical debt that occurs later, after things are developed. You do have to circle back to your styleguide sometimes to adjust the markup to reflect the state of rendered markup on the site. There is maintenance time involved keeping the styleguide up to date for sure, and it’s time you do have to account for.

      Lonely Planet had a great post on this topic last year:

      I’m not aware of any component template systems that can pick up on changes in the Drupal ecosystem of blocks, views, panes, etc… and render the updated styleguide markup accordingly.

      If you’re fine using the styleguide module for this kind of stuff, there are sub-modules mentioned here by others for getting view_modes and custom static html snippets into the styleguide. We are trying to think of ways to make things more automatically maintained with the restrictions (must work via .html or .hbs template files) we do have right now when using KSS.