SC5-Styleguide の始め方


スタイルガイドを使用すると 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がコンポーネントの階層意識せずコーディング出来るのは良い 

***

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

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