Building style guides with the Kalei Styleguide_Sass and Compass Designer's Cookbook-QQ阅读男生历史网

上QQ阅读APP看书，第一时间看更新

Building style guides with the Kalei Styleguide

Style guide shows you the visual effect of your CSS code. When integrating a style guide into your Sass workflow, you can easily check whether your changes have had the desired effect or, on the other hand, do not break your design. In this recipe, you will be introduced to the Kalei Styleguide tool.

Getting ready

Install Ruby Sass, as described in the Installing Sass for command line usage recipe of Chapter 1, Getting started with Sass, to compile your SCSS code into CSS code. The Kalei Styleguide tool used in this recipe can be downloaded at https://github.com/thomasdavis/kaleistyleguide/archive/gh-pages.zip. You should download and unzip this file into your current working directory.

The Kalei Styleguide tool requires an up and running web server, so you should serve the code for this recipe on an HTTP server. Setting up a web server for your projects is out of the scope of this book. In this recipe, WEBrick has been used to server the files. WEBrick is a Ruby library that provides simple HTTP web server services and is part of the Ruby standard library for Ruby 1.9.3. How to install Ruby can be read in the Installing Sass for command line usage recipe of Chapter 1, Getting Started with Sass, too.

In the There's more… section of this recipe, you can read a short description on how to use the Kalei Styleguide tool with Ruby on Rails. Ruby on rails also uses WEBrick to test applications.

How to do it...

The following steps will show you how to build a style guide by using the Kalei Styleguide tool:

Create the following folder and file structure after downloading the Kalei Styleguide and unzipping the files:

Edit your sass/components/_header.scss file to style some headers and add your comment for the Kalei formatted in Markdown:

// CSS RESET
body, html {
  margin: 0;
  padding: 0;
}

@mixin header-styles($background-color) {
  background-color: $background-color;
  border: 3px solid darken($background-color, 20%);
  color: $header-default-font-color;
}

$header-margin: 10px !default;
$header-childs-padding: 10px !default;
$header-default-color: lightyellow !default;
$header-default-font-color: black !default;

$warning-color: red;

.header {
  margin: $header-margin;
  * {
    padding: $header-childs-padding;
  }
}

/*
## Header default
```
<header class="header header-default">
    <h1>Write and debug Sass in browser</h1>
</header>
```
*/

.header-default {
  @include header-styles($header-default-color);
}

/*
## Header warning
special header to show a warning
```
<header class="header header-warning">
    <h1>Write and debug Sass in browser</h1>
</header>
```
*/

.header-warning {
  @include header-styles($warning-color);
}

The sass/main.scss file should contain only the following line of code:
```
@import 'components/header';
```
Compile your code by running the following command in your console:
```
sass sass/main.scss css/main.css
```
Edit the kaleistyleguide/css/js/config.js file to point the tool to the compiled css/main.css file. The css_path variable should be set as follows:
```
css_path: '/css/main.css'
```
Now, server the file from your current working directory over HTTP on port 8080 with WEBrick by running the following command in your console:
```
 ruby -run -e httpd . -p 8080
```
Open http://localhost:8080/kaleistyleguide/ in your browser. You will find that your style guide looks as follows:

How it works...

The Kalei Styleguide tool uses the comments formatted in Markdown in your style sheets to build a style guide. Markdown is a plain text formatting syntax, which can be easily converted into HTML. Stackoverflow (http://stackoverflow.com/), the popular developer forum, uses Markdown for comments and asking questions. Markdown is readable and easy to learn, and it does not require any special software.

To use the Kalei Styleguide tool, you should add Markdown comments in your Sass code. You should use multiline comments before each selector or class that you want to display in your style guide. You can add a title with a line starting with the chars. Normal text will be displayed as paragraphs. The HTML code on which the style should be applied should be written down between ``` and ``` backticks.

Because multiline comments are used, these comments are not compiled in the final CSS, provided that the --style compressed option is used. The Commenting your code in SCSS syntax recipe of this chapter will give you more information about the usage of comments in your Sass templates, and the Choosing your output style recipe of Chapter 1, Getting Started with Sass, explains the differences between the available output styles for the compilation process.

Modularization of your code will help you create better and more useful style guides too. In the Applying the OOCSS, SMACSS, and BEM methodologies recipe of Chapter 4, Nested Selectors and Modular CSS, you can read about OOCSS, SMACSS, and BEM; these methodologies help you to create modular, reusable, and maintainable CSS code.

There's more…

The Sass code used for this recipe is similar to that used for the Building style guides with tdcss.js recipe of this chapter. The tdcss.js tool requires HTML templates for your styles and leaves the Sass and CSS code untouched. Styledocco is another style guide that uses comments formatted in Markdown to build the style guide.

In Chapter 14, Ruby on Rails and Sass, you can read about how to build a Ruby on Rails application. A gem that provides an easy way to add the Kalei Styleguide to your existing Ruby application can be found at https://github.com/andrewhavens/kalei-ruby-gem.