スタイルガイドを使用すると CSS設計の意図などを簡単にドキュメント化することが出来ます。

準備

まずは sc5-styleguideをインストール

$ npm i sc5-styleguide --save

gulp をローカルで入れる人は以下も追加

$ npm i gulp gulp-sass --save

gulpfile.js を作成して以下を記述

var gulp = require('gulp');
var styleguide = require('sc5-styleguide');
var sass = require('gulp-sass');
var outputPath = 'output';

gulp.task('styleguide:generate', function() {
  return gulp.src('*.scss')
    .pipe(styleguide.generate({
        title: 'My Styleguide',
        server: true,
        rootPath: outputPath,
        overviewPath: 'README.md'
      }))
    .pipe(gulp.dest(outputPath));
});

gulp.task('styleguide:applystyles', function() {
  return gulp.src('main.scss')
    .pipe(sass({
      errLogToConsole: true
    }))
    .pipe(styleguide.applyStyles())
    .pipe(gulp.dest(outputPath));
});

gulp.task('watch', ['styleguide'], function() {
  // Start watching changes and update styleguide whenever changes are detected
  // Styleguide automatically detects existing server instance
  gulp.watch(['*.scss'], ['styleguide']);
});

gulp.task('styleguide', ['styleguide:generate', 'styleguide:applystyles']);

最後にファイルを作成。

$ touch README.md
$ touch main.scss

以下のコマンドで起動します。

$ gulp watch

スタイルガイドを記述する

main.scss に以下の記述を加えていきます。

/*
サンプルコンポーネント

Styleguide 1.0
*/

/*
サンプルボタン

Markup:
<a class="btn"> hoge </a>

Styleguide 1.1
*/
.btn{
	....
}

hgttp://localhost:3000 で確認するとStyleguide のページにボタンが表示されているのを確認できます。

Markup のセクションには Pug も使えます。

/*
サンプルボタン

Markup:
a.btn hoge

Styleguide 1.1
*/
.btn{
	....
}

Include も出来ます。

/*
サンプルボタン

Markup:
include /tmpl/mixins.pug
+btnDefault

Styleguide 1.1
*/
.btn{
	....
}

スタイルガイドの設定

enablePug ： Pug 記法を有効にします。

gulp.task('styleguide:generate', function() {
  return gulp.src('*.scss')
    .pipe(styleguide.generate({
        enablePug: true
        ....
      }))
    .pipe(gulp.dest(outputPath));
});

server ： false で静的ファイルを吐き出します。

gulp.task('styleguide:generate', function() {
  return gulp.src('*.scss')
    .pipe(styleguide.generate({
        server: false
        ....
      }))
    .pipe(gulp.dest(outputPath));
});

extraHead ：スタイルガイドのHeadに要素を追加します。

gulp.task('styleguide:generate', function() {
  return gulp.src('*.scss')
    .pipe(styleguide.generate({
        extraHead: [
            `<style>
                :root{font-size: 10px}
                .sg.sg-wrapper,.sg.sg-top-nav-menu{
                    max-width: 96em
                }
            </style>`
        ],
        ....
      }))
    .pipe(gulp.dest(outputPath));
});

overviewPath ：スタイルガイドの表紙のドキュメントファイルを修正します。

gulp.task('styleguide:generate', function() {
  return gulp.src('*.scss')
    .pipe(styleguide.generate({
        extraHead: [
            overviewPath: './styleguide.md',
        ],
        ....
      }))
    .pipe(gulp.dest(outputPath));
});

注意すべき点など

スタイルガイド、必要ない場面の方が多いです。

意外と仕上げていくのは大変
コメント書くのは大変
コンポーネント間のマージなどスタイルガイドの中だけでは完成出来ない箇所も
CSSがコンポーネントの階層意識せずコーディング出来るのは良い

スタイルガイド、必要なくなる場面の方が多いです。

面倒だからそのうちメンテされなくなる
自動デプロイは必須。
作るならしっかりワークフローに取り込んで
できればお客さんに公開してメンテの意識を。