Generating Style Guides with KSS

Documenting style will always be a challenge. I think it’s up to you to decide the project’s balance between:

  • The need for providing clear documentation.
  • The practical use a styleguide would actually serve to the project’s stakeholders

And here’s the key one I’ve usually found a challenge on most projects:

For a style guide to be effective and worth your time,

It takes the concern and vested interest of the other developers on the team to carefully contribute to the documentation, while sticking to a set of style structure and organization.

This last one is always a problem. I’ve found that on the many projects I’ve been involved with, more often than not, the prjoect turns into a mess of tangled CSS code and rules. It doesn’t matter how well we structure the files and folders from the beginning; when push comes to shove, deadlines and pressure cause us to be messy developers. I’m guilty of it as well.

On this particular project, the team already had a style guide set up using static HTML. I knew there had to be a better way, and I found a perfect way to do it.

That’s where Knyle Style Sheets come in. The developer, Kyle Neath seems to enjoy the way Github does it and has created a nice solution to do it. It automatically parses your .scss, .less, or .css files when you write in the approrpiate syntax and generates some static HTML for you.

Unfortunately, when it comes to the grunt and node stack, it was really tricky for me to get it spinning up.

I ended up finding a winning combination: I used grunt-styleguide and this awesome template, plus a couple hacks to get it working.

I’ll leave out the entire Gruntfile. Our project compiles styles from assets/styles into the public/css/ directory.

styleguide task:
Gruntfile.coffee
1
2
3
4
5
6
7
8
9
10
11
styleguide:
  options:
    template:
      src: 'assets/vendor/styleguide-template'
    framework:
      name: 'kss'
      options:
        includeType: 'sass'
        includePath: 'public/css/application.css'
  all:
    files: ['_styleguide': 'assets/styles/**/*.scss']

assets/vendor/styleguide-template is a clone of the template repo mentioned earlier, with some minor customizations to the template.

This task generates static HTML/CSS for a styleguide into the _styleguide directory.

The tricky part was getting my styles to show up in the outputted code. Unfortuantely, though the grunt-styleguide docs say you can run precompiled code through and it will take care of the rest, no matter how hard I tried, that didn’t work.

In the end, it was just a simple matter of adding to my copy and watch tasks to copy the compiled CSS over.

watch task:
Gruntfile.coffee
1
2
3
4
5
6
7
8
9
10
11
12
watch:
  options:
    livereload: false
    spawn: false

  'sass-application':
    livereload: false
    files: [
      'assets/styles/application.scss',
      'assets/styles/**/*.scss'
    ]
    tasks: ['sass:application', 'copy:styles', 'styleguide']
copy:styles task:
Gruntfile.coffee
1
2
3
4
5
6
7
8
copy:
  styles:
    files: [
      expand: true
      cwd: 'public/css'
      src: '**/*'
      dest: '_styleguide/css'
    ]

As a bonus, add grunt-contrib-connect and have it boot up a little preview server. This was helpful on a project I was running because index.html wasn’t accessible.

Gruntfile.coffee
1
2
3
4
5
6
7
8
9
connect:
  styleguide:
    options:
      port: 9001
      base: '_styleguide'
      keepalive: true
      open:
        target: 'http://localhost:9001'
        appName: 'Google Chrome'

Pretty cool, huh? Now, in my _modules.scss file, I can add this before the code block I want to add:

_modules.scss
1
2
3
4
5
6
7
// Spacer
//
// A basic separator element to break up sections.
//
// Markup: <div class="spacer"></div>
//
// Styleguide 2.1

The kss-node project is pretty finicky, but when it works, it’s awesome. You can add modifier classes, and it will generate nice code samples and output for each of those modifier classes. You can even add markdown within your descriptions.

_modules.sass
1
2
3
4
5
6
7
8
9
10
// Alerts
//
// Indicate failure or success. <em>Required: `alert-success` or `alert-error`</em>
//
// Markup: <div class="alert {$modifiers}">You mistyped your password.</div>
//
// .alert-error - Indicate an error
// .alert-success - Indicate success
//
// Styleguide 2.2
Screenshot:

If you find things aren’t working, check to make sure you’re numbering things in the right order, that you haven’t already documented a section. I had to move a few of my sections around to match the order of the @import statements in my main .scss file.

You can pretty quickly and easily customize that template as well, if needed.

Here’s to hoping this helps our team stay on a solid set of rules and continued documentation!