Qiita Teams that are logged in
You are not logged in to any team

Log in to Qiita Team
Community
OrganizationAdvent CalendarQiitadon (β)
Service
Qiita JobsQiita ZineQiita Blog
Help us understand the problem. What is going on with this article?

LivingStyleGuideでスタイルガイドを作ってみた

More than 5 years have passed since last update.

現在担当しているプロジェクトでLivingStyleGuideをいれてみたのでメモ。
公式サイトはこちら

できることとかできないこととか

  • マークダウンで記述するスタイルガイド
  • Sassを使用しているプロジェクトに限られる?
  • JSを埋め込めるので、動きのあるものもプレビューできる
  • スタイルガイドのデフォルトデザインはCSSを上書きすることでカスタム可能
  • header、footerもオリジナルのHTMLを挿入できる
  • gulp、gruntのプラグインあり
  • ページ分割はできなさそう

必要なものの準備

Sass

Sassファイルを用意する。

ディレクトル構成は下記のようにしてみた。

│──sass
│   │── foundation
│   │    │── _base.scss
│   │    └── _reset.scss
│   │── component
│   │    │── _button.scss
│   │    │── _button.md
│   │    │── _icon.scss
│   │    └── _icon.md
│   │── app.scss
│   └── styleguide.lsg

livingstyleguideのインストール

ターミナルで下記を叩いてインストール

$ sudo gem install livingstyleguide

styleguide.lsgファイルを作成

下記内容でsassディレクトリ直下にstyleguide.lsgファイルを作成する

styleguide.lsg
source: 'app.scss' # replace with your default Sass/SCSS file name
title: 'My Living Style Guide'

sourceはデフォルトのscssファイルを指定
これをCSSにコンパイルしたコードがスタイルガイドのhtmlのheadタグ内に記述される。
今回はapp.scssを指定している。

titleにはスタイルガイドのtitleタグの内容を指定

マークダウン

各パーシャルファイル名と同じ名前のマークダウンファイルを作成すし、スタイルガイドを書く。
_button.scssに記述してあるCSSのスタイルガイドを作成する場合、同じ階層に_button.mdを作成する。

_button.scss
.c-button {
  display: inline-block;
}
.c-button-more {
  font-size: 13px;
  font-weight: bold;
  border-radius: 2px;
  background-color: #fbc30a;
  padding: 0 12px;
}
_button.md
Buttons
======= 

``` 
 <a class="c-btn c-btn-more">続きを見る</a> 
``` 

スタイルガイドを生成する

必要なマークダウンファイルを作成したら、スタイルガイドを作成する。

コマンドラインでスタイルガイドを生成

下記コマンドでスタイルガイドのhtmlを生成する。

$ livingstyleguide compile sass/styleguide.lsg docs/styleguide.html

gruntでスタイルガイドを生成

プラグインをインストールする

$ npm i grunt-livingstyleguide -D
Gruntfile.js
grunt.initConfig({
  livingstyleguide: {
    generate: {
      options: {
        src: './sass/styleguide.lsg',
        dest: './docs/styleguide.html'
      }
    }
  },
})

gulpでスタイルガイドを生成

プラグインをインストールする

$ npm i gulp-livingstyleguide -D
gulpfile.js
var gulp = require('gulp');
var livingStyleGuide = require('gulp-livingstyleguide');

gulp.task('livingstyleguide', function () {
  return gulp.src('./sass/styleguide.lsg')
    .pipe(livingStyleGuide())
    .pipe(gulp.dest('./docs'));
});

最終的なディレクトリ構成

│──docs
│   └── styleguide.html
│──sass
│   │── foundation
│   │    │── _base.scss
│   │    └── _reset.scss
│   │── component
│   │    │── _button.scss
│   │    │── _button.md
│   │    │── _icon.scss
│   │    └── _icon.md
│   │── app.scss
│   └── styleguide.lsg

ヘッダー、フッターのカスタマイズ

styleguide.lsgに下記記法でhtmlを記述することでヘッダー、フッターのhtmlを変更できる。
また、CSSも新たに追加することができる。

styleguide.lsg
header: |
  <div class="sg-header">
    <div class="sg-header__main">
      <h1>Style Guide</h1>
    </div>
  </div>

footer: |
  <div class="sg-footer">
    <div class="sg-footer__copyright">
      <p>copyright</p>
    </div>
  </div>

styleguide-scss: |
  .sg-header {
    background-color: #ffd400;
  }
  .sg-header__main {
    margin: 0 auto;
    padding: 20px 0;
    box-sizing: border-box;

    h1 {
      font-size: 30px;
      font-weight: bold;
    }
  }

スタイルガイドのデフォルトスタイルを変更する

styleguide.lsgに設定を追加することでデフォルト設定を上書きできる。

デフォルト設定は下記ページのscssファイルに記載してある。
https://github.com/livingstyleguide/livingstyleguide/blob/master/stylesheets/_livingstyleguide.scss

  • $livingstyleguide-- で始まる変数の値を上書きできる
    例えばフォントサイズを変更したい場合は $livingstyleguide--base-font-size で変数が定義されているので、 base-font-size: 10px のように記載する。
  • 全てのSass記法が使える
  • 自分のプロジェクトで定義している変数も使用できる

下記が設定してみた例。

styleguide.lsg
style:
  base-font: 'Helvetica, Arial, "Hiragino Kaku Gothic ProN", Meiryo, sans-serif'
  width: $site-width
  base-font-size: 10px
  base-line-height: 1.5
  code-color: 'darken(red, 10%)'

所感

  • 導入するにあたり学習コストは高くない。
  • ページ分割ができないので、大規模サイトだとつらそう。
  • マークダウンで別ファイルで書けるのがいい

Sassを使用している小規模なサイトで、スタイルガイドのデザインにそこまでこだわらない(以前にhologramいれてみたけど、デザインカスタマイズにすごい時間割いた記憶があるので・・)のであれば、LivingStyleGuideを導入するのがいいのではないかと思った。

あと、細かく見てないがv2.0で大幅にアップデートされるっぽい。

dmzero3
フロントエンドの実装をしています。 Swift書きたい。
Why not register and get more from Qiita?
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away