MD-Blog_Web Creative

何故必要か？

大規模のサイト制作や時間がないときなど、複数の人で制作を進めていると、
「このページをベースに量産お願い」
と頼まれたり、
「誰がこのclass上書きしたの？」
「同じようなclassがたくさん出来てしまった！」
と怒られたりした経験はオーサリングしている人なら誰もがあると思います。

そんなときに、制作を進める上でおすすめなのがサイトのCSSドキュメント。
ドキュメントというと固いイメージですが、要はCSSの説明・サンプルです。
"このページをベースに"というそのベースのCSSを把握するのに時間がかかったりもするので、それをCSSスタイルガイドがあればすぐに把握できる。
これが巷でCSSスタイルガイドと言われているものです。

ベースページの制作者も、コメントを入れる癖だけ付けてしまえば、あとは自動的にCSSスタイルガイドがコマンド一発で生成されます。

前置きが長くなったので、早速準備から試していきましょう。

今回は、一番メジャーかつ導入が簡単と思われるStyleDoccoを紹介したいと思います。

導入手順

node.jsのインストール

これについては以前Ken.Otsukaも紹介の記事を書いていますし、もう数えられないくらい参考情報は出回っていますので割愛させていただきます。

npmからインストール

公式サイトに従い、
コマンドラインで、

npm install -fg styledocco

ここではGitも必要になります。

僕の環境はwindowsなので、msysgitを入れていたのですが、特にカスタムせずデフォルトのままインストールをしていたら、コマンドプロンプトへパスが通っていないことが判明。 下記のようなエラーが出た人は、コントロールパネル › システム › システム詳細設定 › 環境変数の設定にmsysgitインストールフォルダ\msysgit\cmd を通してあげれば大丈夫です。（msysgitの場合）

参考：Gitのパスが通ってなかったときのエラー

npm http GET https://registry.npmjs.org/styledocco
npm http 304 https://registry.npmjs.org/styledocco
npm http GET https://registry.npmjs.org/styledocco/-/styledocco-0.6.3.tgz
npm http 200 https://registry.npmjs.org/styledocco/-/styledocco-0.6.3.tgz
npm ERR! git clone git://github.com/marrs/node-findit.git CreateProcessW: ?w??
??t?@?C?????????????????B
npm ERR! Error: `git "clone" "git://github.com/marrs/node-findit.git" "C:\\User
\\hogeUser\\AppData\\Local\\Temp\\npm-6224\\1374796413288-0.42948712897486985"` fa
led with 127
npm ERR!     at ChildProcess. (C:\Program Files (x86)\nodejs\node_mo
ules\npm\lib\utils\exec.js:56:20)
npm ERR!     at ChildProcess.EventEmitter.emit (events.js:99:17)
npm ERR!     at Process._handle.onexit (child_process.js:678:10)
npm ERR! If you need help, you may report this log at:
npm ERR!     
npm ERR! or email it to:
npm ERR!     

npm ERR! System Windows_NT 6.1.7601
npm ERR! command "C:\\Program Files (x86)\\nodejs\\\\node.exe" "C:\\Program Fil
s (x86)\\nodejs\\node_modules\\npm\\bin\\npm-cli.js" "install" "-fg" "styledocc
"
npm ERR! cwd C:\Program Files (x86)\nodejs
npm ERR! node -v v0.8.14
npm ERR! npm -v 1.1.65
npm ERR! Error: EPERM, open 'C:\Program Files (x86)\nodejs\npm-debug.log'
npm ERR!  { [Error: EPERM, open 'C:\Program Files (x86)\nodejs\npm-debug.log']
npm ERR!   errno: 50,
npm ERR!   code: 'EPERM',
npm ERR!   path: 'C:\\Program Files (x86)\\nodejs\\npm-debug.log' }
npm ERR!
npm ERR! Please try running this command again as root/Administrator.

npm ERR! System Windows_NT 6.1.7601
npm ERR! command "C:\\Program Files (x86)\\nodejs\\\\node.exe" "C:\\Program Fil
s (x86)\\nodejs\\node_modules\\npm\\bin\\npm-cli.js" "install" "-fg" "styledocc
"
npm ERR! cwd C:\Program Files (x86)\nodejs
npm ERR! node -v v0.8.14
npm ERR! npm -v 1.1.65
npm ERR! path C:\Program Files (x86)\nodejs\npm-debug.log
npm ERR! code EPERM
npm ERR! errno 50
npm ERR! stack Error: EPERM, open 'C:\Program Files (x86)\nodejs\npm-debug.log'
以下省略

error not found: git
error Failed using git.
などnodejsのログに残っているのでわかるかと思います。

さっそく使ってみる

コメントの書き方

せっかくインストールしたのですが、まだコマンドは使わず、CSSスタイルガイドの元となるCSSのコメントの書き方です。

通常のCSSオーサリング時にも、後から修正や変更をしやすいようにコメントを入れていると思いますので、あとはそのコメントのフォーマットを少し変えてあげるだけで大丈夫です。

コメントにはMarkdownというマークアップ言語を使います。
GitHubやTumblrなどでも使うことのできるアレです。

例えば下記のようなCSSとコメントを書いてみます。

/*
## ページタイトル

ページタイトルユニットは`#pageHead`

ページタイトル`.main`サブタイトル`.sub`

```
<h1 id="pageHead">
<span class="main">ページタイトル</span>
<span class="sub">サブタイトル</span>
</h1>
```
*/
body {
    color:#535353;
    font-family:"ヒラギノ角ゴ Pro W3", "Hiragino Kaku Gothic Pro", "メイリオ", Meiryo, Osaka, "ＭＳ Ｐゴシック", "MS PGothic", sans-serif;
}
#pageHead {
    font-size: :13px;
    line-height: 1.231;

    max-width:1248px;
    padding:23px 15px 25px;
    background: -webkit-gradient(linear, left top, right top, color-stop(0.0, #000000), color-stop(1.0, #AD3031));
    background: -webkit-linear-gradient(letf, #000000 0%, #AD3031 100%);
    background: -moz-linear-gradient(letf,    #000000 0%, #AD3031 100%);
    background: linear-gradient(to right,     #000000 0%, #AD3031 100%);
    background: #000\9;
}
#pageHead .main {
    display:block;
    color:#fff;
    font-size:70%;
    font-weight:normal;
}
#pageHead .sub {
    display:block;
    margin-top: 5px;
    color:#fff;
    font-size:35%;
    font-weight:normal;
}

/*
## リンクボックス

基本は`.defBox`となる

枠の反転は、
背景あり白文字は.bdrRed`をつけることでDefault：#ccc、Over：#ad3031となる

```
<article class="defBox">
<a href="/service/web-production.php">
<h1 class="title">Web Production</h1>
<p class="category">Service</p>
<p class="body">企画、サイト制作、アプリ＆システム開発など</p>
<div class="btn">FOR MORE INFO</div>
</a>
</article>

<article class="defBox bdrRed">
<a href="/service/movie_and_streaming.php">
<h1 class="title">Movie & Streaming</h1>
<p class="category">Service</p>
<p class="body">映像制作・ライブ中継・スタジオレンタルなど</p>
<div class="btn">FOR MORE INFO</div>
</a>
</article>
```
*/

.defBox{
    position:relative;
    display:block;
    padding:10px;
    margin-bottom: 10px;
    border:10px solid #ccc;
    background-color:#fff;

    -webkit-box-sizing:border-box;
    -moz-box-sizing:border-box;
    box-sizing:border-box;

    -webkit-transition: all 0.3s ease-in-out;
    -moz-transition: all 0.3s ease-in-out;
    -ms-transition: all 0.3s ease-in-out;
    transition: all 0.3s ease-in-out;
}
.defBox:before{
    -webkit-transition: all 0.3s ease-in-out;
    -moz-transition: all 0.3s ease-in-out;
    -ms-transition: all 0.3s ease-in-out;
    transition: all 0.3s ease-in-out;
}

.defBox > a{
    display:block;
    color:#000;
}
.defBox a:link{
    text-decoration:none;
}
.defBox:hover{
    border-color:#ad3031;
}

.defBox.bdrRed{
    border-color:#ad3031;
}
.defBox.bdrRed:hover{
    border-color:#ccc;
}

ついにコマンドを使う

例えばプロジェクトフォルダ配下が
-index.html
-css/example.css
とします。上記のコードがexample.cssの中身になります。
コマンドプロンプトから、

cd プロジェクトフォルダのパス

と移動し、

styledocco -n "StyleDocco入門編サンプル" css/example.css

と叩いてみます。（"StyleDocco入門編サンプル"はプロジェクト名ですので、何でも構いません。CSSスタイルガイドのタイトルになります。）

すると、プロジェクトフォルダ内にdocsフォルダが出来ていると思います。
docsフォルダ内の、example.html（example.cssでないファイル名の場合はそのファイル名.htmlになっているかと思います。）を開くと、下記のようCSSスタイルガイドが出来ていると思います。

※クリックで実際に生成されたCSSスタイルガイドにリンクしてます。

最後に

どのコメントを打てば画像のようになるか照らし合わしたりして確認してもらえればと思いますが、コメントだけ気を付けて書けば簡単に上記のようなCSSスタイルガイドが生成されますので、大規模サイトで複数人の制作体制だったり運用でページの追加などあるサイトには特におすすめです。

今回は、入門編ということで導入から簡単なサンプルまでの流れを紹介しましたが、SASSやLESSにも対応していたり、さまざまなオプションなどもありますので、また機会があれば紹介したいと思います。

他にもスタイルガイドを生成するさまざまなCSSプリプロセッサがありますので、自分の気に入った方法・デザインのものを使っていければいいのではないのでしょうか。

よきCSSスタイルガイドタイムを。