スタイルシートを書くのってほんとうにややこしいですね。気がついたら、どこになにが書かれているのかわからない数万行の CSS 地獄になってしまいます。
CSS 地獄にならないためには、例えばボタンなら共通のボタンのスタイルシートに統一して、どのページでも同じスタイルシートでボタンを表現したほうが、効率的だし仕事も早いですよね。デザインのリニューアルだって一瞬です。さらには、デザイナーが作業しなくてもエンジニアだけでボタンを用意できてしまうという CSS 天国が待っています。
CSS 天国を実現するためには、どのような共通のスタイルシートを用意しているのかまとめてあるドキュメント、「スタイルガイド」を用意しておくと便利です。べつに wiki にまとめてもいいんだけど、wiki って更新するの忘れてしまいがち。そこで、スタイルシートに書いたコメントを抽出して自動でスタイルガイドを生成してくれるっていう便利なツールを紹介したいと思います。
このようなツールは GitHub も使っている KSS や、デフォルトのテンプレートがかっこいい StyleDocco などいろいろありますが、ここでは Hologram を使ってスタイルガイドを作ってみようと思います。ツールそれぞれに特徴があるので、ぜひいろいろ試してみて自分のプロジェクトに合ったものを選んでください！
それでは Hologram でスタイルガイドを作ってみましょう！
スタイルガイドの生成を体験するために、サンプルのかんたんなプロジェクトを用意しました。
さっそく以下の手順で Hologram を実行してみましょう。
(環境は Mac の OSX、Ruby は最新のバージョンになっている前提のコマンドです！)
- ターミナルを立ち上げます。
$ gem install hologram
- Mac に Hologram をインストールします。
$ git clone [email protected]:shikakun/styleguide.git
- サンプルプロジェクトを Mac にダウンロードします。
$ cd styleguide
- サンプルプロジェクトのディレクトリへ移動します。
$ hologram hologram_files/config.yml
- Hologram を実行します。
Hologram を実行すると、app ディレクトリと同じ階層に styleguide というディレクトリができます。このなかにあるファイルが、スタイルガイドです！
button.html をウェブブラウザで開いてみましょう。
スタイルガイドができてるぞ!!
さきほど生成したスタイルガイドでは例としてボタンのスタイルシートについて説明していますが、この説明がどこに書かれているのかというと、ボタンのスタイルシートが書いてある CSS ファイルにコメントとして書かれています。
app/stylesheets/button.css には、以下のように書いてあります。
/*doc
---
title: このスタイルシートについて
name: 0-button-outline
category: button
---
このスタイルシートでは、ボタンのスタイルを指定しています。
*/この /*doc からはじまったコメントが Hologram のために書かれたコメントです。スタイルシートのコメントがすべてスタイルガイドに反映されるわけではなく、Hologram の記法に沿っていないものは無視されます。
それぞれ指定してる項目の意味は以下の通りです。
title:- スタイルガイドで見出しになる文字列です。日本語で書いても問題ありません。
name:- スタイルガイドで URL のアンカーになる文字列です。また、同じ name は同じスタイルの説明として解釈されるので、スタイルの説明ごとに別の name をつける必要があります。半角英数で指定するのがおすすめです。
category:- スタイルガイドの目次に表示されたり、ファイル名になる文字列です。半角英数で指定するのがおすすめです。
コメントは issue でいつも慣れ親しんでいる Markdown で書くことができるので便利ですね。
スタイルガイド自体のテンプレートは hologram_files/templates ディレクトリに入っていて、ヘッダーとフッターのマークアップや、スタイルガイド自体のスタイルシートを編集できるようになっています。目の前の仕事から逃避したいときや、土日に予定がなさすぎてつらいときとかにプロジェクトに合ったおしゃれなデザインをしてみるのも一興です。
そんな暇ないよ！って人は、モダンな Hologram のテンプレートを作って公開してる人もいるので、そのまま使うなりディレクトリ構成を参考にするなりしてみたらいかがでしょうか。
これは、CodeGrid っていう有料のメールマガジンで Hologram の使い方を紹介していたときのサンプルコード。サンプルコードは GitHub で無料で公開されています。
- Hologramでカスタムスタイルガイド
このサンプルプロジェクトの Hologram は、実は Markdown をパースするところもカスタマイズしています。
```example
ボタン
```というように書くと、実際にボタンとして html を表示してコードも併記できるようにしています。
詳しくはhologram_files/markdown_renderer.rbを参照ください。
Hologram はカスタマイズ性が高いので、自分の好きなように表示できてめっちゃ楽しいです。
実際にスタイルガイドを書きながらスタイルシートを書いていると、いつも誰かに説明を迫られているような気がして、scss の長い入れ子を分割したり、どうしてこのように書いているのかをまめにコメントするようになって、あとから自分で見返したときもわかりやすくなって良いなと思います。
あと、サンプルの html が一覧になっていることで、そのスタイルシートがうまく適用されなくて表示が崩れても見つけやすいという、テスト的な使い方もできるなーと思いました。
まだ全然手探りでやってますけど、なかなかよかったので、とりいそぎご紹介でした！