Generating an Automatic Style Guide for a Drupal 8 Theme

January 25, 2016
blog author


Senior Front End Developer

In this post I wanted to share my experience of integrating an automatic living style guide into a Drupal 8 theme.

Living style guides are a way to document the visual language, colour palettes, and typography of a site or application and help front-end developers transform their code into well described pattern libraries with minimal effort.

Style Guide Driven Development

Styleguide Driven Development has been very popular in the last couple of years. As web development becomes more modular and complex, there is an increasing need to create and document work flows that help designers, front-end and back-end devs. There are many good resources for getting started with Style Guide Driven Development. Also, there are plenty of Style Guide Generators that will get your well noted CSS/SCSS transformed into a living document.

Setting up SC5 Style Guide Generator

In one of my previous posts I wrote about creating and integrating Gulp work flow into a Drupal 8 theme (source code). I wanted to add the style guide to this theme and integrate it with the existing Gulp pipeline. For this purpose I've settled on SC5 Style Guide Generator as it didn't require any additional dependencies. SC5 is built with AngularJS and generates good looking style guides from style sheets using KSS notation. Set up was pretty straightforward and requierd an addition of one npm module to the package.json file

npm install sc5-styleguide --save-dev

and a style guide task to the gulp.js pipeline


gulp.task('styleguide:generate', function() {
  return gulp.src('scss/**/*.scss')
        title: 'Monoset Styleguide',
        overviewPath: '',
        server: true,
        port: 3010,
        rootPath: outputPath,

With SC5 generator there are options to run style guide on a local port as you develop or use a static set of files which are saved to a directory.

Styelsheet's KSS Notation

KSS is a set of guidelines to help you produce an HTML style guide tied to CSS documentation that is nice to read in plain text, yet structured enough to be automatically extracted and processed by a machine. Here is an example of the notation I did for the typography scss partial:

  // Typography
  // Roboto & Georgia
  // Roboto Font:
  // Styleguide 1.0

  // Type Weights
  // $thin - 100;
  // $light  - 300;
  // $normal -  400;
  // $medium - 500;
  // $bold - 700;
  // $ultra-bold - 900;
  // Styleguide 1.1
  // ...

Which produces this section of the style guide. Here is the full source code of this section's scss partial.

And a full monoset's style guide Demo

As a leader in Drupal design and development, Appnovation’s experts can quickly and easily migrate or upgrade your site to Drupal 8. We're your experts in Drupal 8 migrations, able to handle data, site and content migrations of any size and complexity. Have questions about migration? Contact us today, we're here to help!