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

    kss-node
    
  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:
    <a href="#" class="button {$modifiers}">Link Button</a>
    <button class="button {$modifiers}">Button Element</button>
    <input type="button" class="button {$modifiers}" value="Input Element"/>
    
    :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:
    <a href="#" class="button {$modifiers}">Link Button</a>
    <button class="button {$modifiers}">Button Element</button>
    <input type="button" class="button {$modifiers}" value="Input Element"/>
    
    .curved                - Indicate slightly rounded buttons
    .rounded               - Indicated circular buttons
    
    Styleguide 1.1
    */
    
    ...
    
    /*
    Paragraph
    
    Main typography across the pages
    
    Markup:
    <p class="{$modifiers}">Lorem ipsum dolor sit amet, consectetur adipisicing elit. Nisi, consectetur.</p>
    
    .warning               - Displays warning
    .error                 - Display error
    
    Styleguide 2
    */
    

... ```

  1. create styleguide

    kss-node [css-directory] [styleguide-directory] --[style-language] [input-file]
    kss-node css styleguide --css css/style.css
    
  2. 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
    
  2. change some styles in the folder styleguide-template

  3. 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

    node_modules/*
    
  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) {
    
      grunt.initConfig({
    
        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

    grunt
    
  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

Credits

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