Railsにhologramを導入してスタイルガイドを運用できるようにする

正直それなりにデザインスキルが高いかつデザイナーさんたちがテクニカルスキルが高い組織じゃないとスタイルガイドの運用は結構むずかしいとおもうんだけど、ちょうど現職ですでに導入されてるレガシーな自前スタイルガイド機構があったので、負債化したそれをhologramに置き換えた。

• trulia/hologram

hologramのここが良い

hologramはCSS上にコメント形式でMarkdownとマジックコードコメントを書くことで「実際の表示」と「コードの例」をそれぞれドキュメント化してくれるRuby製のツール。

普通に自前で作ろうとすると「コードの例」を載せるのがすごく難しいので、それをやってもらうにはやっぱりライブラリを使ったほうが楽。

また、「CSS上にコメント形式で記載する」ことで、「そのCSSがドキュメント化される」のと「ガイドに掲載されているのか」がCSSを見るだけでわかるようになる。

自前で作るとなると基本的にはCSSとHTMLは分離されてしまうことが多いと思うので、これがCSS単品で完結するのはめちゃくちゃ強みだと思う。

hologramをRailsに乗せる

とはいえRailsはコンパイル後のCSSにハッシュダイジェストをつけてくれちゃうので、実はhologramをRailsに乗せるのは結構難しい。

本来は「hologram -> 生成されたCSSを読むHTMLを吐き出す」という流れにしたいんだけど、生成されたCSSのファイル名を取得する方法がhologram自体にはないので、そこは自前で書くしかない。

方法1: styleguide用scssを自前コンパイルしてそのCSSから app/javascripts/ 配下の元CSSを読ませる

この方法ならコンパイル後のCSSを知らなくても、コンパイル前を読み込んで自前でコンパイルさせてしまえるのでhologramでも使えるようになる。

hologram自体にもstyleguide用のCSSは必要なので、それをSassで運用するようにしてかつ元のCSSも読ませるようにすればスマートに解決する。

方法2: manifest.json を読んでCSSを埋め込めるようにする

僕は方法1を選んだのでこれが実際できるのかはわからないけど、理論的にはできそう？

Railsは public/packs 配下に元ファイルとコンパイル後のファイルのマッピングを持ったjsonを吐き出すので、それを読み込んでコンパイル後のファイル名を取得してしまえばhologramに埋め込むことも可能かもしれない。

hologram導入で躓いたところ

意外と簡単にいけるだろ！って思ったけど思った以上に躓いて半日ぐらいかかったのでメモっておきたい。きっとまたやらかす。

コメントは /* doc じゃだめ、 /*doc のようにスペースは入れない

これで30分ぐらい動かなくて悩んだ。

hologramのコードを読めばわかったのかもしれないけど、何回やってもHTMLが生成されなくて適当に触りまくってたら直った。

SCSSの自前コンパイルとファイルウォッチ

スタイルガイドを作るとなると、ガイドだけじゃなくてデザインの確認にも使いたかったので、開発サーバを起動してstyleguideのテンプレートと実CSSファイルの変更を検知 & 再ビルドをさせたかった。

この辺はSCSSのコンパイルは sass を使ってたので、ついでに paulmillr/chokidar を入れてファイルの変更検知をさせることで解決した。

終わりに

hologram、結構古いライブラリの割にJSXの対応とかがはいっててちゃんとメンテされてるんだなあという印象があった（最終更新は3年前だけど）。

本来はフロントを分離してstorybookとかを使いたいんだけど、レガシーシステムなのでそういうわけにもいかず、ちょっと泥臭くてもこういった小さい改善で今後もなんとかしていきたいなあという気持ち。