KSS styleguides with grunt

This post is about using Knyle Style Sheets and grunt to auto-generate and keep style guides up-to-date. I used it on the redesign for www.leicester.gov.uk.

I first experimented with the raw node implementation but since I’d started looking at grunt I thought there was very likely to be a plugin for KSS. Sure enough, there were a few. I tried using kss-grunt but didn’t get on too well with that one. I then found grunt-styleguide, which I implemented in the end.

Here’s my full gruntfile config with some explanation.

...    
    clean: ["css", "docs"], //1

    copy: {  //2
        development: {
            files: [{
                src: ['scss/styleguide.md'],
                dest: 'docs/styleguide.md'
            }]
        }

    },

    sass: {  //3
      options: {
        includePaths: ['bower_components/foundation/scss']
      },
      development: {
        options: {
            style: 'expanded'
        },
        files: {
            'docs/app.doc.css': 'scss/app.scss'
        }
      },
      dist: {
        options: {
            style: 'compressed'
        },
        files: {
            'css/app.css': 'scss/app.scss'
        }        
      }
    },

    watch: {
      grunt: { files: ['Gruntfile.js'] },

      sass: {
        files: 'scss/**/*.scss',
        tasks: ['sass']
      }
    },

    stripmq: {  //4
        options: {
            width: 1024
        },
        all: {
            files: {
                'css/desktop.css': ['css/app.css']
            }
        }
    },

    "rem-to-px": {  //5
      default_options: {
        options: {
          path_images: 'images/'
        },

        files: {
          'css/desktop.css': ['css/desktop.css']
        }
      }
    },

    styleguide: {  //6
        development: {
            options: {
                template: {
                    src: 'styleguide-template'
                },
                framework: {
                    name: 'kss'
                }
            },
            files: {
                'docs/styleguide': 'docs/app.doc.css'
            }
        }

    },
  1. clean – this is the ‘contrib-clean’ plugin that is used to delete generated files prior to a build. The main reason for using this is that the css and styleguide are auto-generated on each build, so some files may be removed by a build as development proceeds. So, its good to just start fresh each time
  2. copy – for the styleguide task, KSS requires a ‘styleguide.md’ file that it uses as the overview page. This can be used to give the project title and a description of what it was about. The original styleguide.md file resides in the ‘scss’ directory but when a build is done, this file is copied to the ‘css’ directory so that KSS can find it when the styleguide is generated.
  3. sass – the sass task compiles the sass and sets an include path that allows all foundation files to be imported. Notice here that 2 targets are specified
    1. development – the development target outputs expanded css with comments, which is used as the basis for generating the styleguide. It also stores the output in the docs directory rather than the css one.
    2. dist – this target outputs the compressed css to the css folder.
  4. stripmq – This task goes through all the css and strips out media queries, generating a ‘desktop.css’ file. This is used as the basis for the IE7,8 stylesheet (which don’t accommodate media queries). There’s a post here about that.
  5. rem-to-px – Another task used to accommodate older browsers who don’t understand the rem measurement. Same post as above for details.
  6. style-guide – The KSS framework is targeted (with this plugin, styledocco can also be used), the location of the template to use is specified, and which files to look at to generate the guide.

I’ve just started to actually get into the guts of annotating the css but so far the output is looking promising…

kss-styleguideIn my opinion, KSS seems more powerful and intuitive for documenting a complete website style, without having to document every single rule.

One of the really cool features is the ability to add variables into the commented markup, which then generate variants of a rule. As seen above, 2 variants are output showing an ‘info’ alert and a ‘warning’ alert. To do that, I just added the following above the styles for alerts…

/* 
Alerts

Alert boxes styled to show various messages throughout the site.

Markup:

<div class="alert-box {$modifiers} round" data-alert="">Alert message with an optional link.<a class="close" href="#">ร—</a></div>

.info - an information alert (e.g. school closures, roadworks) .warning - a warning alert (e.g emergency, disaster, bad weather) 

Styleguide 1.0 

*/

This gives the section an overall description, shows variants and gives the rules some context.

Also, due to the hierarchical nature of KSS, if I create bespoke rules somewhere (that aren’t part of core foundation) I can just annotate them with the same major styleguide number but add a minor one to it. That way, when the styleguide is generated, all the docs are put together. I did this for buttons. In foundation, buttons is a component with its own stylesheet. However, to extend the component, you just need to call the button mixin and add any additional rules yourself. So, in the app.scss file I added the following…


//custom button
/* 
Shadow button

Button with a white stroke and box shadow

Markup: <button class="shadow-button {$modifiers}">button text</button>

.secondary      - orange style button for top tasks, contact us buttons

Styleguide 3.1
*/
.shadow-button {
    @include button(rem-calc(15), $primary-color, $global-radius, false, false, true);
    border: 2px solid #fff;
    box-shadow: $global-box-shadow;

    &.secondary {
        background-color: $secondary-color;
        border: 2px solid #fff;
        box-shadow: $global-box-shadow;
        color: $body-font-color;

        &:hover {
            color: $body-font-color;
        }
    }
}

In the styleguide, buttons are under heading 3. By specifying 3.1 for this element, even though its not together with the other button specification, when the stylesheet is compiled, the hierarchy is maintained.

kss-buttons

By just doing a ‘grunt build’ a desktop fallback is generated as well as a (literally :)) living styleguide. The only issues at the moment are that I’m manually commenting the foundation framework. I can’t see any better way than this but if anyone else can, please let me know. The other thing that must manually be done is setting the hierarchy of sections. I can’t really see any way this could be automated though.

Update

Here’s a little image of the file structure for my KSS setup.

KSS file structure

KSS file structure

5 thoughts on “KSS styleguides with grunt

  1. Thanks, found this very helpful.
    For some reason, the styleguide task for some reason didn’t work until I changed `files: { … }` to `all: { files: [{ … }] }`.
    Any idea why?

    1. not sure. when specifying ‘all: { files: [{…}] }’ you are creating a task called ‘all’ that can be called with various commands. So if you wanted certain actions to run regardless of what command you execute you could potentially put them in the ‘all’ or ‘default’ task configuration. As long as the ‘styleguide’ task appears in your ‘registerTask’ line, it should execute. If, however, you only wanted the styleguide to be created for production, you could put it in a ‘dist’ object inside the task declaration. Then, when registering the grunt task you could do the following

      grunt.registerTask(‘build’, […, ‘styleguide:dist’, …]);

      That probably doesn’t answer your question but hey ๐Ÿ™‚

  2. Great read, do you have an example of you file structure for the example? I’ve strugling to generate the template pulling in my style sheets. I am using sass

    1. I’m using foundation for this so the file structure is exactly the same as that. The styleguide-template is a sibling of the scss folder which contains the main app.scss with all the KSS directives in. I’ll put an image of the file structure up when I get a chance.

Leave a Reply