読者です 読者をやめる 読者になる 読者になる

Hologram でスタイルガイドを自動生成してみた

ペパボテックカンファレンスで知った Hologram をさっそく試してみた.Hologram を一言で表現すると「CSS のスタイルガイドを自動生成するツール」のこと.Ruby で書かれてるので,困ったら直せそうだし良さそう.

Hologram 以外にも

結構イロイロある.最近よく使われてるのはどれなんだろう.

背景

サービスを育てていくと CSS が肥大化してカオスになるっていうのはよくある話で,UI 改善などで既に使わなくなったスタイルも CSS には残ったままっていうのも多いと思う.常に影響範囲を洗い出しながら精査をすれば良いんだけど,そこまでの時間はないし,無理に消して影響が出るなら残しておこうという判断になったりもする.ペパボテックカンファレンスで「2万行になった CSS」の話があって,単純にデカイ!と思った.

あとスタイルを本来意図した使い方ではなく,求めているデザインになるから流用してしまうこともあって,そうすると「この機能は無くなったから消そう」ってすると「なぜ別の機能の要素にも影響が出るの!」みたいになる.あるある.

サービスのコンセプトに特化する

全ての CSS にドキュメントを書く必要はないと思っていて,サービスのコンセプトに沿った重要な要素だったり,ユーザーのシナリオによって標準化されている要素に特化してドキュメントを書くだけで十分だと思う.単純な例で言うと「警告は黄」で「エラーは赤」など.そこで Hologram が有用だと感じた.

Hello Hologram

試してみた.コードは Playground に置いておいた.

バージョン

最新の 1.4.0 にした.ただ最近はリリースが行われて無くて master にマージされたまま止まってるものもある.

➜  gem install hologram
➜  hologram -v
hologram 1.4.0

初期化

➜  hologram init
Created the following files and directories:
  hologram_config.yml
  doc_assets/
  doc_assets/_header.html
  doc_assets/_footer.html
  code_example_templates/
  code_example_templates/markdown_example_template.html.erb
  code_example_templates/markdown_table_template.html.erb
  code_example_templates/js_example_template.html.erb
  code_example_templates/jsx_example_template.html.erb

文字化け対策

自動生成した HTML が文字化けしてしまうため doc_assets/_header.html に mata を追加する.ただ既に master にはマージされているので,リリースしてくれれば良いのになぁ,なんて思ってしまう.あと必要に応じて titleh1 の文言も変更しておく.

<meta charset="UTF-8">

コードを CSS にする

デフォルトだと Sass から自動生成するようになっているため hologram_config.ymlsource を更新する.

-source: ./sass
+source: ./css

CSS を追加する

ここで CSS を追加する.既に稼働しているアプリケーションに適用する場合は不要.今回はカレントディレクトリに ./css を作ってそこに CSS を配置するので,以下のサンプルを書いてみた.

mkdir css
touch css/button.css

ドキュメントは markdown で書く.GitHub のサンプル参照で!

(markdown の中に markdown をプレーンテキストとして書く方法がわからなくて...)

実行する

自動的に docs/base_css.html が生成される.サンプルの例が良くないかもしれないけど,こういう形でスタイルガイドが標準化されていたら良いね!

➜  hologram

f:id:kakku22:20151114132908p:plain

スタイルガイドをカスタマイズする

デフォルトのままだとあまりにシンプルなので,スタイルガイド用の CSS を書いて,以下のファイルをカスタマイズすることができる.

  • doc_assets/_header.html
  • doc_assets/_footer.html

以下のサンプルは凄く良いなと思う.

今後

正直 Hologram の README を見てもよくわからなくて,ちゃんと生成できるまで試行錯誤してしまった.Hologram には他にも機能があるので,試してみようと思う.あと最近 Middleman を使ってるので,Middleman + Hologram も良さそう.

関連エントリー