正直それなりにデザインスキルが高く、かつデザイナーさんたちがテクニカルスキルが高い組織でないとスタイルガイドの運用は結構難しいと思うのですが、ちょうど現職ですでに導入されていたレガシーな自前スタイルガイド機構があったので、負債化したそれをhologramに置き換えました。
hologramはCSS上にコメント形式でMarkdownとマジックコードコメントを書くことで「実際の表示」と「コードの例」をそれぞれドキュメント化してくれるRuby製のツールです。
普通に自前で作ろうとすると「コードの例」を載せるのがとても難しいので、それをやってもらうにはやはりライブラリを使ったほうが楽です。
また、「CSS上にコメント形式で記載する」ことで、「そのCSSがドキュメント化される」のと「ガイドに掲載されているのか」がCSSを見るだけでわかるようになります。
自前で作るとなると基本的にはCSSとHTMLは分離されてしまうことが多いと思いますので、これがCSS単品で完結するのはとても大きな強みだと思います。
とはいえRailsはコンパイル後のCSSにハッシュダイジェストをつけてくれてしまうので、実はhologramをRailsに乗せるのは結構難しいです。
本来は「hologram -> 生成されたCSSを読むHTMLを吐き出す」という流れにしたいのですが、生成されたCSSのファイル名を取得する方法がhologram自体にはないので、そこは自前で書くしかありません。
blog.unresolved.xyzapp/javascripts/ 配下の元CSSを読ませるこの方法ならコンパイル後のCSSを知らなくても、コンパイル前を読み込んで自前でコンパイルさせてしまえるのでhologramでも使えるようになります。
hologram自体にもstyleguide用のCSSは必要なので、それをSassで運用するようにしてかつ元のCSSも読ませるようにすればスマートに解決します。
manifest.json を読んでCSSを埋め込めるようにする自分は方法1を選んだのでこれが実際できるのかはわかりませんが、理論的にはできそうでしょうか？
Railsは public/packs 配下に元ファイルとコンパイル後のファイルのマッピングを持ったjsonを吐き出すので、それを読み込んでコンパイル後のファイル名を取得してしまえばhologramに埋め込むことも可能かもしれません。
意外と簡単にいけるだろうと思ったのですが、思った以上に躓いて半日ぐらいかかったのでメモしておきたいと思います。きっとまたやらかします。
/* doc じゃだめ、 /*doc のようにスペースは入れないこれで30分ぐらい動かなくて悩みました。
hologramのコードを読めばわかったのかもしれませんが、何回やってもHTMLが生成されなくて適当に触りまくっていたら直りました。
スタイルガイドを作るとなると、ガイドだけではなくてデザインの確認にも使いたかったので、開発サーバを起動してstyleguideのテンプレートと実CSSファイルの変更を検知 & 再ビルドをさせたいと考えていました。
この辺はSCSSのコンパイルは sass を使っていたので、ついでに paulmillr/chokidar を入れてファイルの変更検知をさせることで解決しました。
hologram、結構古いライブラリの割にJSXの対応などが入っていてちゃんとメンテされているのだなという印象がありました（最終更新は3年前ですが）。
本来はフロントを分離してstorybookなどを使いたいのですが、レガシーシステムなのでそういうわけにもいかず、少し泥臭くてもこういった小さい改善で今後もなんとかしていきたいという気持ちです。