by Flo Preynat

Style guides are design deliverables providing details such as fonts, colors, white space, and interface elements that communicate the essence of a visual brand for the web, as well as how and when to use them.

Boom. Bomb is dropped. You’ve got to love the concept of style guides (or tiles or whatever you want to name it), especially as you deal with large scale responsive design missions. What a great idea, whether used while rolling out the project in order to present the visual components of the desired website to your fellow designers, various team members, clients, or even past project end when reviewing components to be dismissed or slightly altered.

Yet, because we are working alone on a project, do not have enough time and want/need to focus on other types of documentation (such as CMS functional doc), we intentionally decide not to go through the style guide process and pass on an excellent opportunity to keep {such a detailed} track of all the nifty features we have included on our websites.

Automation

You may know of tools such as Stylify Me that help designers quickly gain access to an automatically generated style guide, but let’s admit it: although such overviews might be helpful in some cases, especially on the typographic front, nothing will replace a hand made and carefully-planned style guide.

KSS

This is where KSS comes in. KSS is intended to help automate the creation of a living styleguide. It can be used with CSS, SCSS, LESS and more. I’m going to show you how to use KSS-node, the NodeJS implementation of KSS. For this you’ll need to have node and its package manager npm installed on your system.

Let’s get started

You can follow the documention as much as I can but here’s a quick summary:

Install kss-node globally by running on your terminal:

npm install -g kss

Once installed, check out the various kss-node commands by running:

kss-node

You should get the following:

Usage:
 kss-node sourcedir [destdir] --init [directory] --{style,less,sass,stylus} [file]

Options:
  -t, --template  Use a custom template to build your styleguide [string]
  -s, --style     Compile and include a stylesheet               [string]
  -l, --less      Compile and include a LESS stylesheet          [string]
  -y, --stylus    Compile and include a Stylus stylesheet        [string]
  -S, --sass      Compile and include a SASS stylesheet          [string]
  -c, --css       Compile and include a CSS stylesheet           [string]
  -m, --mask      Use a custom mask for detecting stylesheets    [string]
  -i, --init      Create a new styleguide template to work from

My way or the highway… unless

Having succesfully tested kss-node with an end file made of plain vanilla css, and since I’m happy with the process I currently have in place, I would be happy to have the feedback of the people who know how to take full advantage of the tool with Sass files. I have seen it working with grunt modules, json files, and you name it which I am far from confident with, therefore I am just gonna show you how I use it personnally. My way.

For your info, I use Sass, Compass and Codekit on a daily basis, therefore my way of generating style guides is defo compatible with the use of a pre-processor like Sass. Just bare in mind you will need an uncompressed css version of the stylesheet whenever generating the style guide.

Markup

So this is how it works… And if you follow my lead (which is the ignorant one, see section above, it will work whether yo use css or scss (reminder for Sassy fans – output_style = :expanded in your config.rb).

First thing first, let’s create a markdown file to describe the styleguide. This styleguide.md will need to be added in your css folder. And in the file you will enter something along the lines of:

#Living Styleguide for my loving customer

a detailed description about the project

and some more words on the web design project
made by @shoogledesigns

http://shoogledesigns.com

Then, in your CSS or SCSS file (in my case), include the following commented-out section before any feature you need to include in your styleguide:

/* Top level description of the feature

A description.

Markup: <some markup with a specific {$modifier} like class or a pseudo class >

.class 		- description of the class state
:pseudo 	- description of the pseudo state

Styleguide X (digit number to increment eg chapter)
*/

Example

/* Buttons

Buttons can and should be clicked.

Markup: <button class="button {$modifiers}">

:hover - Highlight the button when hovered.
.vip - Displays a very important button 

Styleguide 1
*/

.button {
	background-color: blue;
	text-decoration: none;
	font-size: 20px;
	&:hover {
		background-color: lighten(blue,20%);
	}
	&.vip {
		font-size: 40px;
	}
}

I’m sure that by now, you know what I’m gonna say next. Repeat this as many times as you need sections to be added in the style guide.
I’m going to create a second set just for the sake of example.

/* Colors

Colors should be pretty and seen from far away.

Markup: <div class="{$modifiers}">Some text, preferrably anything but Lorem ipsum in there</div>

.lightblue 	- LightBlue text box.
.red 		- Red text box. 
.orange 	- Orange text box. 
.green 		- Green text box. 

Styleguide 2
*/

.lightblue,.red,.orange,.green {
	padding: 10px;
}
.lightblue {
	background-color: lightblue;
}
.red {
	background-color: red;
}
.orange {
	background-color: orange;
}
.green {
	background-color: green;
}

Obviously, this is far from optimal coding, but you catch my drift.
This is what your project should look like in Sublime Text2. A markdown file in your css folder and a bunch of partials to be imported in your global scss file (here style.scss).

KSS-node the scss way

Generate your living styleguide

Right, so you’ve worked your way through the CSS files and annotated every part of your stylesheet with descriptive and detailed KSS markups. In the terminal, go to the root of your project folder, and type the following:

kss-node css styleguide --css css/style.css

If you’ve already taken a look at the kss-node commands, this won’t look like rocket science to you. css is the source directory, styleguide is the end directory, – -css refers to the file type to be inspected, and css/style.css is its exact location.

You will get a beautiful and carefully sectioned styleguide you’ll be happy to show to your fellow team mates and customers (for this, open the newly cretaed styleguide folder, and check out index.html).

KSS Node Basic Styleguide

Customization

Not happy with the default look and feel of the style guide, and want to add a bit of your own branding before presenting it? Let’s customize the beast by creating a styleguide template and amend it.

Simply run:

kss-node --init

This will create a styleguide template you’ll be able to modify to your liking. Add your own branding to styleguide-template/index.html, and play with the file color, fonts (and more) by altering styleguide-template/public/kss.less.
I personnaly added my name in the left side panel, and changed its original color from lightblue to lightgreen, but I’m sure you can prove to be more imaginative.

Once happy, re-generate your living styleguide by telling kss-node what template to use:

kss-node css styleguide --css css/style.css  --template styleguide-template

KSS-node styleguide overview

KSS-node generated style guide

Verdict

Really impressed by the easiness of the whole process. It takes nothing but a bit of discipline and some carefully placed css comments to get this styleguide going… without any additional effort. Have a go and let me know what you think of KSS-node.

My name is Flo Preynat and I am the freelance webdesigner and developer behind shoogle designs. I live in France and specialize in responsive web design. Give me a shoogle or get in touch with me on twitter.

Most Recent Posts

Special Recent Posts

Sip: a color picker refreshingly simple indeed

Sip: a color picker refreshingly simple indeed

July 10th, 2014

I've just discovered Sip, a color picker app for Mac users. "Just discovered" since it's been around[...]

Perch – the CMS that does not pollute your web design workflow

Perch - the CMS that does not pollute your web design workflow

July 7th, 2014

I have recently finished a project based on Perch, the clever 'little' CMS created by edgeofmyseat.c[...]

Responsive video code snippet

Responsive video code snippet

June 29th, 2014

More of a reminder than a pure detailed blogpost, this code snippet will be my go-to resource when I[...]

Project Naphta: a nifty extension to play with text embedded in images

Project Naphta: a nifty extension to play with text embedded in images

June 9th, 2014

We've all been there. You want to select a good chunk of text on a website, only to realise you can'[...]

Free photos for your web design projects

Free photos for your web design projects

June 4th, 2014

Nothing beats using a real professional photographer when working on a cool project. You can be the[...]

Comments

  1. Birger Fühne says:

    Thanks so much for your article, quite useful for my dev workflow.

    I just stumbled upon a little problem following your instructions:

    The comments in the css need to be done by line comments (//), or otherwise the processing of the sass files fails:

    Not working:

    /* Top level description of the feature
    A description.*/

    Working
    //Top level description of the feature
    //A description

  2. Iain says:

    Have you managed to get it working with CSS images defined by a relative path? By default, the paths to any CSS images come out wrong as the generated css file is nested one layer deep inside a public’ directory. Eg my less files are in the root, when I run kss-node, it creates a public folder in this root, and creates a styles.css file inside this. The relative paths in styles.css are therefore wrong. I’d love to hear if you solved this problem.

    • Hi Iain,

      Not tried with pictures defined by relative paths.
      You could mimic the folder structure of the styleguide, but that’s not exactly what we’re looking for here.

      Anybody’s got something on this?

  3. Hanna Kutcher says:

    Hmmm. I’m only seeing curly braces in the index.html file even though “Generation completed successfully!” in the Terminal. I’m tried kss-node both .css and .scss files. Followed your example to the letter. I’m on Mavericks 10.9.2, Terminal, CodeKit, opening index.html in Safari and Firefox both locally and on a remote server. Would you mind pointing me in the right direction? What am I doing wrong?

  4. Ogb says:

    Hello, I found this article very helpful. Surprised though that there are so few resources and most from almost a year ago.

    I use Sass and found that mixin parameters are outputted on a single line as a paragraph.

    Also, when adding Markup, how does one indicate what format it’s in, HTML, CSS, SCSS etc?

    Thanks a lot. Again, this article was a great help. Now i’m off to battle with using kss-node with Grunt.

    Cheers.

  5. sribas says:

    Hi,

    Thanks for this tutorial :)
    Followed it step by step. However, it doesn’t generate the navigation structure. The public/style.css is empty and I have nothing but the Overview.
    Any suggestion?

    Thanks very much.

  6. Mark says:

    This was really useful, thanks for such a simple walk-through!

    One part I was having an issue with was the first step within ‘Customization’. kss-node –init resulted in a ‘TypeError’ … Turns out I just needed to pass in the destination directory of styleguide-template after –init and it worked a treat.