StyleDoccoでStyleGuideの作成をしてみた！ – SAITEI no CHINJUU!!!（最低の珍獣）

二年前に自分で書いたCSSを解読するのに苦労しました。大熊猫です。
“一年後の自分は他人。だから未来の自分への手紙（ドキュメント）を残した方が後で苦労をしないよ”
その昔に、あるプログラマーさんに言われた事を思い出しました。

未来の自分や作業を引き継ぐ誰かのために、スタイルガイドをつくりましょう。
という事で今回はスタイルガイドをわりと簡単に作成できるStyleDoccoのお話です。

スタイルガイドについて簡単に

スタイルガイドとはページ上に存在する部品（コンポーネント）の仕様をまとめたリスト（ページなど）の事です。
それぞれの部品の仕様や使い方を見える形にする事で、本人はもちろんですが、他の作業者も（同時に作業を行う場合）後に作業を引き継ぐ人も効率よく作業を行えます。

CSSが他のプログラム言語に比べ柔軟である事から、スタイルガイドの必要性はあまり考えられていませんでした。
しかし最近ではWebベースのアプリケーションが増えてきた事もあり、効率化、メンテナンス性、柔軟性を考慮した設計がCSSに求められる傾向にあり、スタイルガイドが必要とされているようです。

これは通常のwebサイト（静的なサイト）においても、複数の作業者が関わる場合や公開後の運営などを考えると同じ事が言えると考えます。
また現に作られる事もあると思います。

StyleDoccoとは

StyleDocoはスタイルガイドを簡単に生成出来るジェネレーターの一つです。
Node.jsで実装されています。

ジェネレーターは他にも幾つかあるようですが、StyleDocoとKSSというものが有名なようです。
ちなみに、KSSはRubyで実装されているようです。

StyleDoccoを準備する

Node.jsとnpm

StyleDoccoを利用するにはNode.jsとnpm(Node Packaged Modules)のインストールが必要になります。
まずはターミナル(Windowsの場合はMINGW等)でnode.jsとnpmがインストール済みかを確認しましょう。

node -v
v0.8.15
npm -v
1.1.66

上記のようにそれぞれのバージョンが表示されればOKです。

Node.jsとnpmのインストールについては今回は割愛致します。
最近はWindows環境でも公式のインストーラーが出ていますのでそちらをご確認ください。

スタイルガイドを作ってみる

それでは実際にスタイルガイドを作成してみます。
スタイルガイドの内容は実際にコンテンツの作成に利用するCSSに記述します。
今回は解説のためにstyledoccoと言うディレクトリを用意しました。

styledocco
　┗　css
　　┗　style.css

CSSファイルのコメントとして記述

cssディレクトリのstyle.cssにスタイルガイドを書いていきます。
実際に利用するCSSファイルにスタイルガイドも書いていきます。
StyleDoccoではスタイルガイドの記述はMarkdownの文法を採用しています。

/*
解説を書くとか
*/
/*
# 見出し

見出しについての解説、見出しについての解説、見出しについての解説・・・・

```

見出し

あああああ


見出し

あああああ


見出し

あああああ



```
*/

.contents01{
	padding: 5px 0;
	width: 100%;
}


.h-type01,
.h-type02,
.h-type03 {
	padding-left: 12px;
	font-size: 22px;
	font-weight: normal;
	line-height: 1.4;
	color: #5B5B5B;
}

.h-type01 {
	border-left: solid 10px #009AE4;
}

.h-type02 {
	border-left: solid 10px #999AE4;
}

.h-type03 {
	border-left: solid 10px #FF9AE4;
}

よく使うMarkdownの文法の解説

スタイルガイドはMarkdownの文法で記述します。Markdownの文法は沢山あります。
今回は上記で利用したものだけを解説致します。

/*
「/*」から「*/」がMarkdownの本文

# 見出し　文頭に`#`で見出し 見出しレベルは六段階まで（#が6つまで）

文頭に何も無いものは段落

```
バックティックを3つでpre要素でマークアップ
*/

とっても少なくてごめんなさいm(_ _)m
でもコレ以外はあまり使う気がしません（そんな事はない・・）
その他のMarkdownの文法についてはこちらをご覧下さい。

StyleDoccoを実行

ではStyleDoccoを実行してみましょう。
プロジェクトのディレクトリ(今回はstyledoccoディレクトリ)に移動し実行します。
もし他のディレクトリにいる場合は移動します。

準備が整ったらターミナルで以下を実行します。

styledocco -n "My Website" css/style.css

styledoccoの後の”n”オプションでプロジェクト名を入れる事ができます。
「”」から「”」の間にプロジェクトの名前を記述します。
最後の「css/style.css」はスタイルガイドの内容を記述したファイルの指定です。

styledocco
　┗　css
　　┗　style.css
　┗　docs
　　┣　index.html
　　┗　style.html

実行すると”docs”ディレクトリが生成されます。
その中にある”style.html”があり、それがスタイルガイドになります。

実際に出来上がったものがこちらになります。
通常のStyleの指定は右側に表示され、左側にはMarkdownで記述したHTMLと、その実行結果が表示されます。

CSSプリプロセッサーにも対応

StyleDoccoはSASS（SCSS）, Less, Stylusなどのプリプロセッサーにも対応をしています。

styledocco -n "My Website" --preprocessor "sass" sass/style.scss

指定は簡単で上記の例では”–preprocessor”オプションで”sass”を指定しています。

Compassはこちらが参考になると思います。

プリプロセッサーの利用も当たり前になってきたので、スタイルガイドがあると便利ですね。

StyleDocco触ってみた感想

良いところ

良いところは何より簡単。
導入も作成も更新も含め簡単である事はとても重要です

悪いところ

簡単とは言ってもスタイルガイドの変更の度にコマンドを叩かないとならないのが少し手間。
解決策としてはGrunt.js※などを利用して自動化が考えられます。

まとめ

スタイルガイドの製作そのものは、どのような方法をとってもそれほど難しい事はないと思います。
ただ、最新の状態を維持できず、関係者への共有に時間がかかったり、スタイルガイドの更新自体が、作業者に大きな負担を与えるのであれば全く意味はありません。

今回のStyleDoccoなどのジェネレーターを利用すれば、この問題も解消でき、且つ生きたスタイルガイドを作る事ができると思います。

参考

※1　Grunt.jsはnode.js上で動くJavaScriptのビルド管理ツールです。こちらについいてはまた今度