Generate Sass style guide with Grunt and KSS

What is style guide and why it helps

What — A document that shows specification of the style, for each element and its variations. Eg: button (padding, border, box-shadow)

A sample style guide

Why —Easier to understand, maintain and extend style sheets. Eg: A new front-end developer who needs to create a new page for the application. With style guide they will know which class to use for buttons, layouts, input forms, etc.

I want to make one

There are many documentation syntax and tools out there such as KSS, DSS and Topdoc. Their syntax are quite similar and easy to understand.

If you know JSDoc before, then these should be familiar.

If you don’t, here is a general idea of how to use it:

  1. Write comment blocks in your CSS/SASS/LESS file following a syntax to describe each component/class and how to use it.
  2. Use the terminal to generate a style guide web site from those comment blocks. Usually this can be found in /docs sub-folder.
A sample comment block

Select documentation tool

Here I go through different documentation tools and explain my selection. This section mainly apply to Grunt user, so if you use Grunt in your project already, please continue. Otherwise, the final solution still largely works for you up to the Grunt part, so you can skip this section.

  • grunt-dss: the original DSS project created a style guide based on my comments block, and all was good until I realized it doesn’t use my CSS files =_=, and also doesn’t have an option for it. That issue is still open in their GitHub. So no grunt-dss.
  • grunt-topdoc: Topdoc created a style guide with all elements I commented and with the CSS files I created. But I couldn’t find any of my comment blocks anywhere 0_0. So no grunt-topdoc either.
  • grunt-kss: It created a style guide with my comment blocks and CSS files. So GREAT! I tried to register a grunt task that covers every tasks needed including cleaning the docs folder, pre-process my SASS files, generate the document and watch for changes in the SCSS files. However, the grunt task didn’t terminate itself after the document is generated, so whatever tasks I wrote afterward couldn’t run #Feelsbadman.

The final solution

Thanks to a blog post by Vitalii Bilous, I realized a kss command in the terminal will stop after the document is created, and I just have to use grunt-shell to run that command automatically. That’s the general idea, now let’s get to the details.

Installing stuffs

npm install --save-dev grunt-shell kss grunt-contrib-compass grunt-contrib-cssmin

Start with adding a simple KSS comment block in your Sass file

// Button
//
// Styleguide 1.0
button {
border-radius: 5px
}

Also generate a css file with your button style to include in the style guide

sass --watch url/to/scss-file:url/to/css-file

Now we are ready to generate the document, let’s try running the kss command in the terminal (more configuration options)

cd node_modules/.bin
kss --source path/to/scss --destination path/to/styleguide --css url/to/css-file.css

A note about the command above: path/to/scss and path/to/styleguide start from node_modules/.bin directory, but url/to/css-file.css starts from your path/to/styleguide directory.

If everything goes well, you will see this in your terminal, and then the command terminates.

Style guide build completed successfully!

Fantastic! Now we just need to create a grunt task to do all these automatically. Below I only configure the tasks necessary for the style guide to run, convenient tasks like clean, connect and watch aren’t mentioned.

shell — Run kss command in the terminal

shell: {
styleguide: {
options: {
execOptions: {
cwd: '.node_modules/.bin'
}
},
command: 'kss --source path/to/scss --destination path/to/styleguide --css url/to/css-file.css'
}
}

compass — Generate CSS files from your Sass files

compass: {
options: {
sassDir: 'path/to/scss',
cssDir: 'path/to/css',
},
server: {
options: {
sourcemap: true
}
}
}

This task is overly simplified, so if you want more configuration, here is the official document.

cssmin — Minify all your CSS files into one. This is very useful when you use many CSS files in your app and want to load all of them in your style guide.

cssmin: {
docs: {
files: {
'url/to/css-file.css': ['pattern/to/all-css-files']
}
}
}

Finally remember to load your Grunt dependencies and register the task

grunt.loadNpmtasks('grunt-shell');
grunt.loadNpmtasks('grunt-contrib-compass');
grunt.loadNpmtasks('grunt-contrib-cssmin');
grunt.registerTask('styleguide', [
'compass',
'cssmin:docs',
'shell:styleguide'
]);

Now you can open the style guide document straight away, or add clean, connect and watch tasks to serve and watch the style guide as you make more changes.