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がコンポーネントの階層意識せずコーディング出来るのは良い

---

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

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