Living style guides are a wonderful way to document and develop living style guides. There are a number of frameworks and frontend build systems that can be used to setup a project for a living style guide. In the meantime I have built quite a number of living style guides and have since found a combination of Brunch and kss-node to be a good fit. This blog post shows how a project for developing a living style guide can be setup.

Brunch and KSS

Brunch is a really simple build system that favors convention over configuration. Once you get the hang of it, starting a project is straightforward and does not involve gazillion lines of boilerplate configuration. If you haven’t used Brunch before, make sure to read the getting started with Brunch guide before you continue reading.

Knyle Style Sheets (KSS) are a convention to structure parseable documentation in CSS, LESS, SASS or SCSS code. The KSS spec allows to put the documentation (even the HTML examples) right next to the code that is responsible for the documented feature. Hence, the KSS spec is easy to understand and a breeze to maintain.

To easily integrate the style guide generation into the Brunch build I have written a Brunch plugin called kssbrunch. The plugin basically adds an onCompile hook to the build that generates the style guide based on the documentation found in the stylesheets.

Setting up the Project

First, we’ll need to define the dev dependencies for the project. Add all required dev dependencies until your package.json resembles to the following:

{
  "name": "<name>",
  "version": "<version>",
  "dependencies": {
    "bourbon": "^4.2.6"
  },
  "devDependencies": {
    "bower": "^1.8.0",
    "browser-sync-brunch": "0.0.9",
    "brunch": "^2.1.3",
    "kssbrunch": "^0.0.5",
    "sass-brunch": "^1.9.2"
  }
}

This installs the Brunch tool, as well as some of the basic plugins available. Depending on your needs, you may add additional Brunch plugins to customize your build.

Building Stylesheets

The Brunch build itself is configured by the brunch-config.coffee (or .js) file in the root directory of the project. It defines the source and target folders for the JavaScript and stylesheet files:

# brunch-config.coffee
module.exports =
  config:
    paths:
      watched: ['app/', 'styleguide/']
    files:
      javascripts:
        joinTo: 'app.js'
      stylesheets:
        joinTo:
          'app.css': /^app/,
          'styleguide.css': /^styleguide/

The style guide we are about to build requires some miscellaneous resources, which we will put into a separate /styleguide folder. The goal is to customize the look and feel of the style guide with those resources to match the design the style guide is all about. As we do not want the style guide specific customizations to be in the production code, we separate them in the build configuration. Given the Brunch configuration above, the project directory structure looks as follows:

├── app/                    # all source files
│   ├── fonts/
│   ├── js/
│   │   └── app.js
│   ├── scss/
│   │   └── app.scss
│   └── styleguide.md
├── brunch-config.coffee
├── package.json
├── public/                 # generated files
│   ├── app.css
│   ├── app.js
│   ├── styleguide/         # generated style guide
│   └── styleguide.css
├── styleguide/             # style guide customizations
│   └── styleguide.scss
└── yarn.lock

Generating the Style Guide

As soon as the kssbrunch plugin is added to the package.json, a living style guide is automatically generated into the public/stylguide folder. The plugin is configured in the plugins section of the Brunch config and it is required to set the source path to the app folder containing the documented stylesheets.

# brunch-config.coffee
module.exports =
  config:
    plugins:
      kss:
        kssConfig:
          source: ["app"]
          homepage: "styleguide.md"

The style guide homepage is a document that serves as homepage for the generated living style guide and should contain project-specific getting started information as well as general guidelines that hold for all components in the style guide.

Adding BrowserSync Support

To spice up the developer experience, let’s add BrowserSync support for the living style guide. That means that as soon as JavaScript or stylesheet files are changed, the living style guide document is regenerated and then automatically reloaded in the browser. To add the support, we’ll need to add some configuration to the Brunch config:

# brunch-config.coffee
module.exports =
  config:
    plugins:
      browserSync:
        port: 3333,
        server: {
          baseDir: ["public/styleguide", "public"],
          directory: false,
          index: "index.html"
        },
        files: ["public/styleguide/**/*.html"]

The BrowserSync configuration creates a web server to serve all static files as defined in server.baseDir. As the style guide is generated into the public/styleguide folder, we’ll add that as document root as well as the public folder itself. Defining index.html as start page will launch the style guide in a new browser tab as soon as you start brunch watch.

As we want the browser to refresh if the generated style guide files change, the files parameter adds a glob to watch for all changes to HTML files in the public/styleguide directory. Note that we also set the BrowserSync server port to the Brunch server default port (which is not used in this case).

The Whole Brunch Config

You may find the whole brunch config described above in the following gist:

View Gist on GitHub

Brunch Skeleton

I have built a Brunch skeleton to jump-start living style guide development. The skeleton generates a project setup aligned with the setup described in this article. To start a new living style guide project with Brunch just type the following command:

brunch new -s gh:fakleiser/kss-brunch-seed

Happy coding!