Vinay M

#02-06 Silahis Apartments
121 Lorong K Telok Kurau
Singapore - 425762

Please send us a message and
we will get back to you within 1-2 working days.

Create styleguides with KSS and Styledocco

Posted by on 15 July 2012 in , , Read Later

Documenting CSS and HTML is one of the key steps in front-end development. Especially when you are working with another company and you have to handover your hand-coded html/css. Most of the time they come back to us, asking us "how do i generate a green button", "how do i create a blockquote" etc. I have been creating simple styleguides in the past using the "Mollio" templates.

My search brought me to 2 CSS stylguide generators

  1. KSS : https://github.com/kneath/kss
  2. Styldocco : https://github.com/jacobrask/styledocco/

KSS

KSS is an amazing stylguide generator, you can easily integrate it with your rails app or Middleman. Check out this tutorial by Stephen Tudor on how to use KSS with Middleman.

http://www.stephentudor.com/blog/2012/01/10/kss-and-middleman/

KSS needs both comments in your css as well as views for generating styleguides. This is a lot of work for me, I expect kss to use my css comments and fill the gaps.

The problem with KSS is that the generated style document is not easy-enough for 80% of the developers to understand.

Example of Styleguide generated by KSS : https://github.com/styleguide/css/1.0


Styledocco

Styledocco is my favorite here and i will explain a little bit more about how to set this up. All you have to make sure is your css is properly commented with markdown.

Example Styleguide

http://artminister.com/examples/08/docs/

Pre-requisites

  1. Less CSS Compiler

    npm install -g less
    
  2. NodeJS - http://nodejs.org/

To install styledocco, open your terminal and run.

[sudo] npm install -g styledocco

Once installed, open up your stylesheet and add comments. Please note that styledocco uses markdown in the comments and "double tab" is used to seperate the markup.

Eg:
http://artminister.com/examples/08/ui.css.less
http://artminister.com/examples/08/grid.css.less

/* 
  #Buttons
  CSS style variations for all buttons

    <button>Button element</button>

*/

button{
  background:blue;
  color: white;
  border:1px #ddd solid;

}

/*
  Submit Button

    <button class="submit">Submit button</button>
*/

button.submit{
  background:green;
}

/*
  Call to Action Button

    <button class="cta">Submit button</button>
*/

button.cta{
  background:red;
}

/* ----
  #Table
  Styles for tables

    <table>
      <thead>
        <tr>
          <th>Heading 1</th>
          <th>Heading 2</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <td>Content 1</td>
          <td>Content 2</td>
        </tr>
      </tbody>
    </table>

*/

table{
  border-collapse:collapse;
  th{background:#ccc;}
  th, td{padding:5px 10px;}
}

/*
  Zebra striped table

    <table class="zebra">
      <thead>
        <tr>
          <th>Heading 1</th>
          <th>Heading 2</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <td>Content 1</td>
          <td>Content 2</td>
        </tr>
        <tr>
          <td>Content 1</td>
          <td>Content 2</td>
        </tr>
        <tr>
          <td>Content 1</td>
          <td>Content 2</td>
        </tr>
      </tbody>
    </table>

*/

.zebra {
  td{background:#aaa;}
  tr:nth-child(odd) > td{background:#ddd;}
}

If you see the css, i am just doing the extra work of adding comments and html markup, which i often do for all my projects.

Compiling the Stylesheets to generate the styledoc

Once the css is ready, navigate to your css folder in terminal and run

styledocco -n "Styleguide" #[Name] --preprocessor "/usr/local/bin/lessc" #[less_path] --verbose #[add optional 'css_folder_path']

More options can be found here

https://github.com/jacobrask/styledocco/#options

After compiling, you will see a docs folder with html files for each stylesheet. Open it up in a browser and be amazed at how easy it was to generate a style document. :)

Example: http://artminister.com/examples/08/docs/

Bugs in styledocco and less

Less compiling gives strange error when quotation marks are not used for background images

eg: This gives error:

td{background:url(../img/bg.png);}

This wont

td{background:url("../img/bg.png");}

Useful Links