用StyleDocco來撰寫CSS樣式指引文件

在撰寫網頁樣式的時候，有時候會遇到跟其他人（通常是設計師）一起合作的場合，要是像程式碼那樣的Style Guide，有一份樣式上的指引文件幫助溝通以及讓夥伴們遵循，想必會提昇不少溝通上的效率。
現在已經有了一些工具可以從CSS原始碼中自動產生這樣的指引文件，StyleDocco就是其中之一。

首先透過npm將StyleDocco安裝起來。
npm install -g styledocco
除了直接對CSS做處理外，StyleDocco還支援其他如LESS和SASS之類的CSS Preprocessor，這裡就直接用普通的CSS來做示範：

/*
# 凸框
 
可以調整陰影透明度。
 
依畫面光源設定的方向不同，也別忘記改變陰影方向。
 
```
<div class="box">
  <p>Hello!</p>
</div>
```
*/
.box {
	border: 1px solid rgba(0, 0, 0, .15);
	box-shadow: rgba(0, 0, 0, .2) -1px 1px 0, rgba(255, 255, 255, .7) -1px 1px 0 inset;
	border-radius: 4px;
	padding: 10px;
}
 
/*
# 按鈕
 
注意各種狀態變化。
 
```
<div class="button" style="display: inline-block">
</div>
<div class="button-alt" style="display: inline-block">
</div>
```
*/
.button {
	width: 50px;
	height: 20px;
	background-color: #66EE33;
	border: 1px solid rgba(0, 0, 0, .15);
        box-shadow: rgba(0, 0, 0, .2) -1px 1px 0, rgba(255, 255, 255, .7) -1px 1px 0 inset;
        border-radius: 4px;
        padding: 10px;
}
.button-alt {
	background-color: #66EE33;
	width: 50px;
        height: 20px;
	border: 1px solid rgba(0, 0, 0, .15);
	box-shadow: rgba(0, 0, 0, .2) -1px 1px 0, rgba(255, 255, 255, .7) -1px 1px 0 inset;
	padding: 10px;
}
.button:hover, .button-alt:hover {
	background-image: linear-gradient(to bottom, #EEFF99, #66EE33);
}

而以上的CSS原始碼，經過指令：
styledocco -n "Style Guide" style.css
可以產生這樣的樣式文件。

簡單地講解一下書寫的大原則，註解裡面使用的是簡單易懂的Markdown，而註解後連著的樣式在遇到空行之前都會被納入同一個段落，因此像上面的範例這樣就分成了兩個段落。

同時可以看到原始碼跟實際的呈現樣貌，除了方便溝通之外，還能整理自己的樣式規則避免重複，總之是很實用的工具呢。

如果要再搭配 Grunt 作自動化的話，可以使用 grunt-styleguide 來實現。

npm install grunt --save-dev
npm install grunt-styleguide --save-dev

接著準備好必要的 Gruntfile.js 設定檔如下：

module.exports = function(grunt) {
        grunt.initConfig({
                styleguide: {
                        styledocco: {
                                name: 'Style Guide',
                                files: {
                                        'docs': 'style.css'
                                }
                        }
                }
        })
        grunt.loadNpmTasks('grunt-styleguide');
        grunt.registerTask('build', ['styleguide']);
};

就可以把這個文件產生的步驟加入 grunt build 的流程裡面了。

“用StyleDocco來撰寫CSS樣式指引文件” 有 1 則迴響