はじめまして、アメーバ事業本部 teens事業部の谷です。業務ではフロントエンドデベロッパーとして、主にHTML/CSSの設計・実装をおこなっています。
今回は、以前斉藤が書いた「モバイル時代におけるCSSの設計と実装」という記事で触れられていたコンポーネントリストもといスタイルガイドについてのお話です。
スタイルガイドの事例と、スタイルガイドを生成するツール StyleDocco の紹介をします。
スタイルガイドもしくはデザインパターンと呼ばれるページはいくつかのサイトで公開されています。下記はその例です。
このように部品を並べ、それぞれの仕様や使い方、あわせてコードスニペットをまとめておくことで、実装者自身はもちろん他の開発者やデザイナーに共有できる便利なドキュメントになります。
更新されないドキュメントは、ドキュメントそのものが無いのと同様、またはそれ以上に混乱を招き、逆効果となってしまうかもしれません。運用ルールを徹底して、デザインやスタイルが編集されればスタイルガイド側のHTMLとCSSも更新するというのは限界があります。
このスタイルガイドを作る作業を簡略化するためのツールとして今回紹介したいのがStyleDoccoです。
StyleDocco
StyleDoccoはNode.jsで実装されているスタイルガイドジェネータです。
StyleDoccoはCSS内に書かれたコメントをパースし、その内容をスタイルガイドページとしてHTMLにしてくれます。
つまり、CSSファイルを更新・修正する度にスタイルガイド側のHTML/CSSを手作業で修正するという必要はありません。
CSSファイルを更新した後にコマンドを実行するだけでスタイルガイドも更新されます。
実際にどのようなページを作ってくれるのかは、StyleDoccoのサイトにあるexampleをみてみましょう。
スタイルの説明、そのサンプルデザインのプレビュー、HTMLスニペット、CSSスニペットがグループ化され整理されています。
こうしたスタイルガイドをコマンドラインで簡単に生成することができます。
以下StyleDoccoの導入手順と使い方を説明します。
※必要に応じて
Node.jsおよびnpmをインストールしていない人は、Node.jsのサイトからダウンロードできるインストーラーを実行すれば簡単にインストールできます。その後、CygwinやTerminalといったコマンドラインツールで上記を実行します。
説明文はCSSのコメント記法 /* */ で囲みます。そして本文は通常のコメントのように文章をかけば良いのですが、例のような
このような記述形式をMarkdownと呼びますが、もし使ったことがない場合には、こちらなどで構文を確認してください。
Markdown
スタイルガイドの構成上、最低限
また # ひとつの場合は h1要素に置き換えられるのですが、スタイルガイド上ではこのh1の単位でセクションエリアが分割されます。
このあたりは実際に試されてから試行錯誤してみてください。
この移動先の1pixelディレクトリに下記のような構成でファイルが用意されているとします。
ここで確認してもらいたいのはCSSディレクトリとそれ以下のCSSファイルです。中にはcommonという名前でプロジェクト共通のCSSがあり、またそれらを@importで統合するstyle.cssがある、というような例です。各HTMLページではstyle.cssを読み込む想定です。
style.css:
では、コマンドラインツール上でこの1pixelディレクトリにいる状態から、下記のようなコマンドを実行します。
生成した後は docs/index.html にアクセスすればスタイルガイドが確認できるかと思います。
この例のように、@importを使って分割している場合にはそれぞれのドキュメントページを生成し、スタイルガイドにも階層ナビゲーションが用意されます。
CSSプリプロセッサは、.scss,.lessといった各プリプロセッサの対応拡張子のファイルをCSSにコンパイル（変換）するプロセスが必要です。
StyleDoccoでスタイルガイドを作るためにも、そうしたプリプロセスが必要かというとそうではありません。StyleDoccoはコンパイル前のプリプロセッサファイルをパースし、内部的にCSSへとコンパイルしてデザインプレビューに反映してくれます。
例えば下記のような場合でもその構成の通りのスタイルガイドを生成してくれます。
CSSプリプロセッサによる運用の場合、 上記のようにファイルを分割し、それぞれを必要に応じて読み込んで使う、というようなケースもありますが、その場合でもそれぞれでスタイルガイドを生成してくれます。
-nの部分は、–nameでも構いません。プロジェクト名をここで定義するのは必須となります。またここで定義された名前はスタイルガイドの左上のエリアに反映されます。日本語でも大丈夫です。また名前はダブルコーテーションで囲みましょう。
その他のオプションには下記が用意されています。
スタイルガイドを生成するディレクトリを指定できます。未指定の場合は、デフォルトの docs となります。これはコマンドを実行したディレクトリから見て相対的な場所に生成されます。
CSSプリプロセッサを利用しており、そのプリプロセッサの任意のコマンドを実行したい場合に使うオプションです。
すでに説明した通り、CSSプリプロセッサを対象とした場合には、StyleDoccoでスタイルガイドに反映させるためのコンパイルをしてくれるのですが、その場合に任意のコマンドを別途実行させたい場合に使うようです。個人的にはこれを使ったことはありません。
スタイルガイド上のサンプルのプレビュー部分に対して任意のCSSやJSを読みこませることができます。プレビュー部分にはスタイルガイドにするCSSがそのまま適用されますが、任意でプレビュー用のCSSを適用させることができます。
例えば、プレビュー上の背景を変えたいとか、レイアウトを制御したいような場合には使えるかもしれません。またJSファイルを読みこませることもできます。これはプレビュー上、何かしらのインタラクションの表現が必要である場合などに使えます。たとえばクリックしたときに任意のクラスを適用し、要素を変化させたい、といったこともできます。なお–includeを複数記述する形で、複数のファイルを読みこませることもできます。
これはあくまでもプレビューエリア内のカスタマイズとなるので、スタイルガイド本体のスタイルに影響するものではありません。
コマンドを実行した時にログが表示されるようになります。デフォルトではオフ（false）になっているので何も表示されませんが、このオプションを指定すると、各CSSファイルがどのHTMLに反映されたかを確認することができます。
基本的にこれも使うことはないとおもいますが、うまく実行されているかわからない場合には指定してみるといいかもしれません。
以上のオプションをフルで使う場合には次のようなコマンドになります。
スタイルガイドのトップページ
コマンドを実行すると、各CSSファイルのHTMLページだけでなく、スタイルガイドのトップページも生成されます。このトップページは、対象のディレクトリ、ここまでの例でいえば css ディレクトリの直下に README.md というファイルを置き、その中にMarkdown形式で記述すれば、それがHTMLとなって反映されます。そのスタイルガイドを運用する上での説明などを書いておくと良いでしょう。
コメントをドキュメントに反映させない
ドキュメントに反映させる文章はコメントで記述するのはすでに説明した通りです。しかし中にはコード上残しておきたいが、スタイルガイド上は除きたいものがあるかもしれません。例えばコピーライト表記といったものです。
その場合にはコメントに先頭に半角スペースを空けることで、ドキュメントには反映されなくなります。
擬似クラスのプレビュー
リンクやボタンなどのデザインでは、それらのマウスオーバー（:hover）、アクティブ（:active）などの擬似クラスの表現をスタイルとして用意することもあるでしょう。それらもプレビューとして表現したい場合には、プレビューのHTMLのclassに、:hover、:active というのをつければ反映されます。
そのレベルで対応したい場合には、StyleDoccoが影響をうけた、KSSというスタイルガイドジェネレータであればテンプレート機能でデザインのカスタマイズが可能です。同様に、KSS派生のnode.js版 kss-nodeでも同じようにカスタマイズ可能です。これらの使い方については今回説明はしませんが、興味があればStyleDoccoと比較して試してみると良いでしょう。
またStyleDocco自身には、ファイルの更新を監視して自動実行する、といった仕組みはありません。
CSSファイルを更新したら、自動的にStyleDoccoのコマンドを実行する、ということをおこないたい場合には、grunt.jsを使うと良いかもしれません。
grunt.jsはnode.jsで実装されているビルドツールです。grunt.jsについての詳しい話は今回割愛しますが、grunt.jsを使うのであれば、grunt-styleguideというgruntタスクがあるので、それを使えば自動化が容易です。こちらも興味があれば試してみてください。
※ただし、grunt-styleguideたまに上手くスタイルガイドページの生成時に一部が反映されなかったり、タスクを動かすgrunt.js本体のバージョンに左右されて動かないようなケースもあるので、そのあたりは注意してください。
順番としては逆になってしまいますが、こうしたツールを通じてでもスタイルガイドを強く意識することで、CSSの設計をより深く考えられるようになります。
CSS開発を効率化するドキュメントとして、それだけではなくCSSの設計力を身につけるためのツールとしてもおすすめします。
最後までお読みいただきありがとうございました。
今回は、以前斉藤が書いた「モバイル時代におけるCSSの設計と実装」という記事で触れられていたコンポーネントリストもといスタイルガイドについてのお話です。
スタイルガイドの事例と、スタイルガイドを生成するツール StyleDocco の紹介をします。
スタイルガイドとは
先の記事より引用すると、ページ上の部品（コンポーネント、モジュール）を集めたリスト、ページのことです。どれがコンポーネントで、どれがモジュールと呼ぶか、というのは人によって若干定義は異なるかとおもいますが、ここではひとまずページ上の部品ということで進めます。スタイルガイドもしくはデザインパターンと呼ばれるページはいくつかのサイトで公開されています。下記はその例です。
このように部品を並べ、それぞれの仕様や使い方、あわせてコードスニペットをまとめておくことで、実装者自身はもちろん他の開発者やデザイナーに共有できる便利なドキュメントになります。
スタイルガイド運用の問題
スタイルガイドを作ること自体は決して難しいわけではなく、ひとつのページ内にサイト/アプリ内で使われるスタイルをまとめていくだけです。難しいのは、その後に修正・改善を重ねてデザインやスタイルや変わったときに、そのスタイルガイドの方も更新していくことです。更新されないドキュメントは、ドキュメントそのものが無いのと同様、またはそれ以上に混乱を招き、逆効果となってしまうかもしれません。運用ルールを徹底して、デザインやスタイルが編集されればスタイルガイド側のHTMLとCSSも更新するというのは限界があります。
このスタイルガイドを作る作業を簡略化するためのツールとして今回紹介したいのがStyleDoccoです。
スタイルガイドジェネレータ StyleDocco
StyleDocco
StyleDoccoはNode.jsで実装されているスタイルガイドジェネータです。
StyleDoccoはCSS内に書かれたコメントをパースし、その内容をスタイルガイドページとしてHTMLにしてくれます。
つまり、CSSファイルを更新・修正する度にスタイルガイド側のHTML/CSSを手作業で修正するという必要はありません。
CSSファイルを更新した後にコマンドを実行するだけでスタイルガイドも更新されます。
実際にどのようなページを作ってくれるのかは、StyleDoccoのサイトにあるexampleをみてみましょう。
スタイルの説明、そのサンプルデザインのプレビュー、HTMLスニペット、CSSスニペットがグループ化され整理されています。
こうしたスタイルガイドをコマンドラインで簡単に生成することができます。
以下StyleDoccoの導入手順と使い方を説明します。
StyleDoccoのインストール
StyleDoccoはnpmからインストールします。
npm install -fg styledocco※必要に応じて
sudoで実行してください。
sudo npm install -fg styledocco
Node.jsおよびnpmをインストールしていない人は、Node.jsのサイトからダウンロードできるインストーラーを実行すれば簡単にインストールできます。その後、CygwinやTerminalといったコマンドラインツールで上記を実行します。
ドキュメントのコメントをCSSに書く
スタイルガイド上に反映される説明文は、CSSファイル内のコメント部分に記述します。次はその例です。
/*
# ボタン
サイト共通のボタンスタイル。
## デフォルトのボタン
`.btn`クラスを付与する。
```<div class="section">
<a href="#" class="btn">Default</a>
</div>
```
## 主要なボタン
`.btn`クラスと併せて、`.btn-primary`を付与する。
```<div class="section">
<a href="#" class="btn btn-primary">Primary</a>
</div>
```
*/
説明文はCSSのコメント記法 /* */ で囲みます。そして本文は通常のコメントのように文章をかけば良いのですが、例のような
# や`（バックティック）などを使うことで、それらをHTMLの要素化してくれます。# の場合にはh1、## はh2というような形式です。このような記述形式をMarkdownと呼びますが、もし使ったことがない場合には、こちらなどで構文を確認してください。
Markdown
スタイルガイドの構成上、最低限
# と `（バックティック）は覚えておきましょう。サンプルデザインのプレビュー部分を構成するHTMLは、`（バックティック）3つで囲むことで反映されます。また # ひとつの場合は h1要素に置き換えられるのですが、スタイルガイド上ではこのh1の単位でセクションエリアが分割されます。
このあたりは実際に試されてから試行錯誤してみてください。
プロジェクトディレクトリで実行する
コメントが書けたら、コマンドラインツール上で対象のプロジェクトのディレクトリへ移動します。（以下のプロジェクトディレクトリへのパスは例です）
cd ~/Dropbox/Project/1pixel/
この移動先の1pixelディレクトリに下記のような構成でファイルが用意されているとします。
1pixel/
+ css/
+ style.css
+ common/
+ normalize.css
+ button.css
+ blog/
+ index.html
ここで確認してもらいたいのはCSSディレクトリとそれ以下のCSSファイルです。中にはcommonという名前でプロジェクト共通のCSSがあり、またそれらを@importで統合するstyle.cssがある、というような例です。各HTMLページではstyle.cssを読み込む想定です。
style.css:
@import “common/normalize.css”;
@import “common/button.css”;
body {
…
}
では、コマンドラインツール上でこの1pixelディレクトリにいる状態から、下記のようなコマンドを実行します。
styledocco -n "My Project" css
1pixel/
+ css/
+ style.css
+ common/
+ button.css
+ normalize.css
+ docs/
+ common-button.html // common/button.cssのガイド
+ common-normalize.html // common/button.cssのガイド
+ index.html // スタイルガイドのトップページ
+ style.html // style.cssのガイド
+ index.html
生成した後は docs/index.html にアクセスすればスタイルガイドが確認できるかと思います。
この例のように、@importを使って分割している場合にはそれぞれのドキュメントページを生成し、スタイルガイドにも階層ナビゲーションが用意されます。
CSSプリプロセッサへの対応
StyleDoccoはSassやLESSといったCSSプリプロセッサにも対応しています。CSSプリプロセッサは、.scss,.lessといった各プリプロセッサの対応拡張子のファイルをCSSにコンパイル（変換）するプロセスが必要です。
StyleDoccoでスタイルガイドを作るためにも、そうしたプリプロセスが必要かというとそうではありません。StyleDoccoはコンパイル前のプリプロセッサファイルをパースし、内部的にCSSへとコンパイルしてデザインプレビューに反映してくれます。
例えば下記のような場合でもその構成の通りのスタイルガイドを生成してくれます。
1pixel/
+ css/
+ style.scss
+ base/
+ _codes.scss
+ _forms.scss
+ _images.scss
+ generic/
+ _clearfix.scss
+ _helper.scss
+ _mixins.scss
+ _normalize.scss
+ objects/
+ _buttons.scss
+ _columns.scss
+ _grids.scss
+ index.html
CSSプリプロセッサによる運用の場合、 上記のようにファイルを分割し、それぞれを必要に応じて読み込んで使う、というようなケースもありますが、その場合でもそれぞれでスタイルガイドを生成してくれます。
コマンドとオプション
コマンドは、プロジェクト名の定義、任意でオプションを指定、最後に対象となるCSSファイルがあるディレクトリを指定して実行します。
styledocco -n [プロジェクト名] [任意のオプション] [CSSのディレクトリ]
-nの部分は、–nameでも構いません。プロジェクト名をここで定義するのは必須となります。またここで定義された名前はスタイルガイドの左上のエリアに反映されます。日本語でも大丈夫です。また名前はダブルコーテーションで囲みましょう。
その他のオプションには下記が用意されています。
--out,-o-o styleguide
スタイルガイドを生成するディレクトリを指定できます。未指定の場合は、デフォルトの docs となります。これはコマンドを実行したディレクトリから見て相対的な場所に生成されます。
--preprocessor--preprocessor "scss --load-path=deps/"
CSSプリプロセッサを利用しており、そのプリプロセッサの任意のコマンドを実行したい場合に使うオプションです。
すでに説明した通り、CSSプリプロセッサを対象とした場合には、StyleDoccoでスタイルガイドに反映させるためのコンパイルをしてくれるのですが、その場合に任意のコマンドを別途実行させたい場合に使うようです。個人的にはこれを使ったことはありません。
--include--include preview.css --include preview.js
スタイルガイド上のサンプルのプレビュー部分に対して任意のCSSやJSを読みこませることができます。プレビュー部分にはスタイルガイドにするCSSがそのまま適用されますが、任意でプレビュー用のCSSを適用させることができます。
例えば、プレビュー上の背景を変えたいとか、レイアウトを制御したいような場合には使えるかもしれません。またJSファイルを読みこませることもできます。これはプレビュー上、何かしらのインタラクションの表現が必要である場合などに使えます。たとえばクリックしたときに任意のクラスを適用し、要素を変化させたい、といったこともできます。なお–includeを複数記述する形で、複数のファイルを読みこませることもできます。
これはあくまでもプレビューエリア内のカスタマイズとなるので、スタイルガイド本体のスタイルに影響するものではありません。
--verbose
コマンドを実行した時にログが表示されるようになります。デフォルトではオフ（false）になっているので何も表示されませんが、このオプションを指定すると、各CSSファイルがどのHTMLに反映されたかを確認することができます。
基本的にこれも使うことはないとおもいますが、うまく実行されているかわからない場合には指定してみるといいかもしれません。
以上のオプションをフルで使う場合には次のようなコマンドになります。
styledocco -n "My Project" -o styleguide --preprocessor "scss --load-path=deps/" --include custom/preview.css --include custom/preview.js --verbose css
その他の小技
スタイルガイドのトップページ
コマンドを実行すると、各CSSファイルのHTMLページだけでなく、スタイルガイドのトップページも生成されます。このトップページは、対象のディレクトリ、ここまでの例でいえば css ディレクトリの直下に README.md というファイルを置き、その中にMarkdown形式で記述すれば、それがHTMLとなって反映されます。そのスタイルガイドを運用する上での説明などを書いておくと良いでしょう。
コメントをドキュメントに反映させない
ドキュメントに反映させる文章はコメントで記述するのはすでに説明した通りです。しかし中にはコード上残しておきたいが、スタイルガイド上は除きたいものがあるかもしれません。例えばコピーライト表記といったものです。
その場合にはコメントに先頭に半角スペースを空けることで、ドキュメントには反映されなくなります。
/* これは反映される */
/* ←先頭に半角スペースを空けているので、これは反映されない */
擬似クラスのプレビュー
リンクやボタンなどのデザインでは、それらのマウスオーバー（:hover）、アクティブ（:active）などの擬似クラスの表現をスタイルとして用意することもあるでしょう。それらもプレビューとして表現したい場合には、プレビューのHTMLのclassに、:hover、:active というのをつければ反映されます。
```
<div class="section">
<a href="#" class="btn btn-primary">Primary</a>
<a href="#" class="btn btn-primary :hover">Primary hover</a>
<a href="#" class="btn btn-primary :active">Primary active</a>
</div>
```
StyleDoccoの惜しいところ
StyleDoccoは今のところ、スタイルガイド本体のデザインを変更するためのオプションなどはありません。例えば、納品データとしてスタイルガイドを用意したい場合には、それらしい体裁にしたかったり、余分な要素を排除してシンプルにしたい、ということがありません。そのレベルで対応したい場合には、StyleDoccoが影響をうけた、KSSというスタイルガイドジェネレータであればテンプレート機能でデザインのカスタマイズが可能です。同様に、KSS派生のnode.js版 kss-nodeでも同じようにカスタマイズ可能です。これらの使い方については今回説明はしませんが、興味があればStyleDoccoと比較して試してみると良いでしょう。
またStyleDocco自身には、ファイルの更新を監視して自動実行する、といった仕組みはありません。
CSSファイルを更新したら、自動的にStyleDoccoのコマンドを実行する、ということをおこないたい場合には、grunt.jsを使うと良いかもしれません。
grunt.jsはnode.jsで実装されているビルドツールです。grunt.jsについての詳しい話は今回割愛しますが、grunt.jsを使うのであれば、grunt-styleguideというgruntタスクがあるので、それを使えば自動化が容易です。こちらも興味があれば試してみてください。
※ただし、grunt-styleguideたまに上手くスタイルガイドページの生成時に一部が反映されなかったり、タスクを動かすgrunt.js本体のバージョンに左右されて動かないようなケースもあるので、そのあたりは注意してください。
スタイルガイドで気づくモジュール設計の重要さ
きれいにスタイルガイドをつくるためには、それぞれモジュール単位でスタイルをつくる必要があります。StyleDoccoでも必要に応じてプレビューデザインをHTMLスニペットで作るわけなので、そうした設計が必須となります。順番としては逆になってしまいますが、こうしたツールを通じてでもスタイルガイドを強く意識することで、CSSの設計をより深く考えられるようになります。
CSS開発を効率化するドキュメントとして、それだけではなくCSSの設計力を身につけるためのツールとしてもおすすめします。
最後までお読みいただきありがとうございました。