047 Styleguide

13 Jul 2013

Automatic living styleguide helps to create styleguides from documentation in our CSS styles. We will explore 2 tools KSS-Node and StyleDocco with CSS and CSS pre-processor, SASS along with its plugin in GruntJS build tool.

Download video: mp4

Sample code: Github

Similar episodes: 005 Markdown , 010 SASS, 021 GruntJS

##Background on Styleguide

  1. Github Styleguide
  2. Tools used:

##Things to learn with Styleguide

###1. prepare style.css

.button {
  background-color: #bbb;
  text-decoration: none;
  padding: 10px;
  cursor: pointer;

.button:hover {
  background-color: red;

.button:active {
  background-color: black;

.button.info {
  background-color: lightblue;

.button.curved {
  border-radius: 10px;

.button.rounded {
  border-radius: 50%;

p {
  color: #444;

p.warning {
  background-color: yellow;

p.error {
  background-color: red;

###(option A) with StyleDocco

  1. install StyleDocco

    npm install -g styledocco

  2. create a folder css with readme.md and style.css
  3. readme.md contents

    ``` #My project styleguide

    some styleguide notes! ```

  4. insert comment above each style in style.css with Markdown format

    ``` /* #Buttons Provides extra visual weight and identifies the primary action in a set of buttons.

     <button class="button">Button Element</button>  */

    /* Button with info.

     <button class="button info">Button Info</button>  */

    /* Button with curved.

     <button class="button curved">Button curved</button>  */

    /* Button with rounded.

     <button class="button rounded">Button rounded</button>  */

    /* #Paragraphs Some explanations

     <p>Lorem ipsum dolor sit amet, consectetur adipisicing elit. Debitis, tempora!</p>  */

    /* Explanation with warning.

     <p class="warning">Lorem ipsum dolor sit amet, consectetur adipisicing elit. Debitis, tempora!</p>  */

    /* Explanation with error.

     <p class="error">Lorem ipsum dolor sit amet, consectetur adipisicing elit. Debitis, tempora!</p>  */  ```
  5. generate the styleguide

    styledocco -n "My project" css -o styleguide --verbose

  6. open file styleguide/index.html in the browser

###(option B) with KSS-Node

  1. install KSS-Node

    npm install -g kss

  2. command line options


  3. create a folder css with files styleguide.md and style.css
  4. create styleguide.md to include some overview information on css

    ``` #Hello styleguide

    Some information about the styleguide ```

  5. insert comments inside style.css

    ``` /* Buttons

    Buttons are action items for users.

    Markup: Link Button

    :hover - Highlight the button when hovered. :active - “Press” the button down when clicked. .info - Indicate information

    Styleguide 1 */

    /* Buttons corners

    Buttons can be as rounded as desired.

    Markup: Link Button

    .curved - Indicate slightly rounded buttons .rounded - Indicated circular buttons

    Styleguide 1.1 */

    /* Paragraph

    Main typography across the pages


    Lorem ipsum dolor sit amet, consectetur adipisicing elit. Nisi, consectetur.

    .warning - Displays warning .error - Display error

    Styleguide 2 */

    … ```

  6. create styleguide

    kss-node [css-directory] [styleguide-directory] --[style-language] [input-file] kss-node css styleguide --css css/style.css

  7. open file styleguide/index.html in the browser

####create styleguide template 1. create new template for the styleguide and a new folder styleguide-template

kss-node --init
``` 1. change some styles in the folder `styleguide-template` 1. use the template to generate the styleguide

kss-node css styleguide --css css/style.css --template [styleguide-template-directory]
kss-node css styleguide --css css/style.css --template styleguide-template

###with a build tools, css preprocessor and kss

  1. create a new folder project
  2. copy the folder kss styleguide template
  3. create a folder sass with files button.scss and paragraph.scss
  4. contents of style.scss

    @import "button.scss"; @import "paragraph.scss"

  5. create a file package.json

    { "name": "my-project", "version": "0.1.0", "dependencies": {}, "devDependencies": { "grunt": "0.4.1", "grunt-contrib-clean": "0.4.1", "grunt-contrib-sass": "0.4.0", "grunt-contrib-copy": "0.4.1", "grunt-shell": "0.3.0" } }

  6. create a file .gitignore with the following contents


  7. install all the modules as declared in package.json

    npm install

  8. create a file Gruntfile.js inside folder project

    ``` module.exports = function(grunt) {


     clean: {
       style: ['css', 'styleguide']
     copy: {
       styleguide: {
         files: [
           { src: ['sass/styleguide.md'], dest: 'css/styleguide.md'}
     sass: {
       development: {
         options: {
           style: 'expanded'
         files: {
           'css/style.doc.css': 'sass/style.scss'
       production: {
         options: {
           style: 'compressed'
         files: {
           'css/style.css': 'sass/style.scss'
     shell: {
       styleguide: {
           command: 'kss-node css styleguide --css css/style.doc.css --template styleguide-template'
     }    });

    grunt.loadNpmTasks(‘grunt-contrib-clean’); grunt.loadNpmTasks(‘grunt-contrib-sass’); grunt.loadNpmTasks(‘grunt-contrib-copy’); grunt.loadNpmTasks(‘grunt-shell’);

    grunt.registerTask(‘default’, [‘clean’, ‘sass’, ‘copy’,’shell’]);

    }; ```

  9. execute command


  10. see the following files created:
    • css/style.doc.css with expanded format styles and documentation in comments
    • css/style.css with minified styles
    • styleguide/index.html for the complete styleguide

##More Resources on Styleguide

  1. Other tools: Kalei Styleguide and Hologram
  2. Create styleguides with KSS and Styledocco
  3. Creating livint style guides to improve performance


Thanks to everyone who responded to my tweet: any ideas for creating automated living style

##Build Link of this episode The Mother of all Demos by Douglas Engelbart