I am currently constructing my home lab. I will re-start recording the episodes in my new lab from end 2015.

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