スタイルガイドって重要だなと痛感したので、StyleDoccoの導入方法についてまとめました。
「スタイルガイド」って何？
まずは「スタイルガイド」といってもピンとこない人がいるかもしれないのでその説明です。
Wikipediaによると、下記のようになっています。
ウェブサイトスタイルガイドの場合は、主に外観や技術的な側面に関するスタイルを規定する。
とまあこれでもピンとこないと思うので私なりに噛み砕いて言うと、サイト内のパーツや使いまわすスタイルを定義するものです。
実際に見たほうがはやいと思いますので、スタイルガイドページとして見れるものをあげてみます。
これらのページを見れば、一目で既に定義されているスタイルが分かるので無駄がおさえられますよね。
複数人での構築や運用案件で担当者が変わった場合でも、わかりやすいはずです。
StyleDoccoについて
「よし、ではスタイルガイドページを導入しよう」となっても手動で更新するのは大変です…
そこでStyleDoccoを使って自動で生成してもらおうと思います。
StyleDoccoとは
node.jsで実装されたスタイルガイドジェネレータです。
何ができるかと言うと、css内のコメントに指定の記述でガイドに関する文言を書けば、HTMLとして出力してくれます。
Bootstrap一部を使用して例をあげます。
例えば次のように記述すると、
/*
## ボタン設定
### 基本構造
*/
/*
ボタン使用時、デフォルト設定として class="btn" をつける
<a href="#" class="btn">デフォルト</a>
*/
.btn {
display: inline-block;
*display: inline;
/* IE7 inline-block hack */
*zoom: 1;
padding: 4px 12px;
margin-bottom: 0;
font-size: 14px;
line-height: 20px;
text-align: center;
vertical-align: middle;
cursor: pointer;
color: #333333;
text-shadow: 0 1px 1px rgba(255, 255, 255, 0.75);
background-color: #f5f5f5;
background-image: -moz-linear-gradient(top, #ffffff, #e6e6e6);
background-image: -webkit-gradient(linear, 0 0, 0 100%, from(#ffffff), to(#e6e6e6));
background-image: -webkit-linear-gradient(top, #ffffff, #e6e6e6);
background-image: -o-linear-gradient(top, #ffffff, #e6e6e6);
background-image: linear-gradient(to bottom, #ffffff, #e6e6e6);
background-repeat: repeat-x;
filter: progid:DXImageTransform.Microsoft.gradient(startColorstr='#ffffffff', endColorstr='#ffe6e6e6', GradientType=0);
border-color: #e6e6e6 #e6e6e6 #bfbfbf;
border-color: rgba(0, 0, 0, 0.1) rgba(0, 0, 0, 0.1) rgba(0, 0, 0, 0.25);
*background-color: #e6e6e6;
/* Darken IE7 buttons by default so they stand out more given they won't have borders */
filter: progid:DXImageTransform.Microsoft.gradient(enabled = false);
border: 1px solid #cccccc;
*border: 0;
border-bottom-color: #b3b3b3;
-webkit-border-radius: 4px;
-moz-border-radius: 4px;
border-radius: 4px;
*margin-left: .3em;
-webkit-box-shadow: inset 0 1px 0 rgba(255,255,255,.2), 0 1px 2px rgba(0,0,0,.05);
-moz-box-shadow: inset 0 1px 0 rgba(255,255,255,.2), 0 1px 2px rgba(0,0,0,.05);
box-shadow: inset 0 1px 0 rgba(255,255,255,.2), 0 1px 2px rgba(0,0,0,.05);
}
.btn:hover,
.btn:focus,
.btn:active {
color: #333333;
background-color: #e6e6e6;
*background-color: #d9d9d9;
}
.btn:active {
background-color: #cccccc 9;
}
.btn:first-child {
*margin-left: 0;
}
.btn:hover,
.btn:focus {
color: #333333;
text-decoration: none;
background-position: 0 -15px;
-webkit-transition: background-position 0.1s linear;
-moz-transition: background-position 0.1s linear;
-o-transition: background-position 0.1s linear;
transition: background-position 0.1s linear;
}
.btn:focus {
outline: thin dotted #333;
outline: 5px auto -webkit-focus-ring-color;
outline-offset: -2px;
}
.btn.active,
.btn:active {
background-image: none;
outline: 0;
-webkit-box-shadow: inset 0 2px 4px rgba(0,0,0,.15), 0 1px 2px rgba(0,0,0,.05);
-moz-box-shadow: inset 0 2px 4px rgba(0,0,0,.15), 0 1px 2px rgba(0,0,0,.05);
box-shadow: inset 0 2px 4px rgba(0,0,0,.15), 0 1px 2px rgba(0,0,0,.05);
}
次のようなHTMLファイルが出力されます。
※ボタンサイズから下の部分は上記のコードには含んでいないです
コーダーはコメントを書いてコマンド実行するだけでできてしまいます。
コメント部分はMarkdownで記述します。
また、Grunt.jsを使えばコマンド実行も自動で行なってくれます。
StyleDoccoの環境構築
まずは、Node.jsをインストールしてnpmを実行できるようにする必要があります。
下記から、Node.jsをダウンロードしてインストールしましょう。
Node.js
完了したら、StyleDoccoをインストールするため、下記のコマンドを実行します。
npm install -fg styledocco
<!-- Macでインストール出来なかったら -->
sudo npm install -fg styledocco
あとは、プロジェクトフォルダに移動して、次のようなStyledoccoのコマンドを叩くだけで使用出来ます。
styledocco -n "Style Guide" css/style.css
<!-- コマンドの解説 -->
styledocco -n "[プロジェクト名]" [任意のオプション] [CSSのディレクトリ]
コマンドを実行すると、次のようにファイルが生成されます。
"プロジェクトのフォルダ"
┗ css
┗ style.css
┗ docs
┣ index.html
┗ style.html
cssプリプロセッサーを使用している場合は次のようなオプションをつけることで使用出来ます。
<!--sassの場合 -->
styledocco -n "styledocco" --preprocessor "sass" sass/style.scss
意外と簡単に導入できるので、是非試してみてください。
