SC5-styleguideでスタイルガイドしてみる #CSS

この記事は J2complexed Advent Calendar 2016 の2日目の記事です。

ほかのひとがjsについていっぱい書いてくれそうなので、cssのこと書きます。

複数人で進める必要のある、ある程度大きなプロジェクトでは、
モジュールパーツのDOM構成やらスタイルやらがどうしてもばらつきがちで、
なんらかの拠り所がないと、最終的には地獄の業火に焼かれたりしますね。
こわいですね。

もう書き古されたかもしれないけれど、sc5-styleguideを導入したので、
かゆかったとこに手を伸ばしたりしたことをポエムします。

styleguideジェネレータいろいろある

Styledocco
KSS
SC5 styleguide （今回はこれ）
hologram
Kalei Styleguide
aigis（昨日知った..今度使ってみたい）

SC5 styleguide genelator

sassが使える（もちろん！）
gulpでまわせる（gulpあいしてる）
腐ってない
メジャーなKSSの後継（KSSは利用者多いが、最近廃れ腐れ気味っぽい）
自由度高め
ページの生成ルールが仕様に合う（sassファイルごとにページが自動生成されたりしない）
記法が厳格（≒ 最初に決めた仕様から外れづらい）

つかってみる

sassファイル内の記法は、ぐぐるとしあわせになれます。いっぱい情報ある。
記法が厳格なので、空行が抜けたりちょっとでもミスると生成してくれないので注意。

さてgulpをあいしているので、gulpで回します。

要件

スタイルガイドがローカルで見れる
黒い画面もgulpも触らないデザイナーも見れる
特別意識しないでもsassを書いていけば実際使うモジュールがスタイルガイド上でも見れる
- スタイルガイド上でcssだけじゃなく画像とjsも見れる&動く

gulpfile.js
（styleguideに必要そうなところだけ抜いてきたので、うごかないかもしれない）

var gulp = require('gulp'),
    sass = require('gulp-sass'),
    styleguide = require('sc5-styleguide'),
    bulkSass = require('gulp-sass-bulk-import'),
    pleeease = require('gulp-pleeease'),
    header = require('gulp-header'),
    cmq = require('gulp-combine-media-queries'),
    minimist = require("minimist");　// ※２

// taskのオプション
var env = minimist(process.argv.slice(2));

var paths = {
  srcDir : 'themes/pc/assets/', //ソースファイルディレクトリ
  dstDir : 'themes/pc/dist/', //吐き出しファイルディレクトリ
  sgDir: 'themes/pc/dist/styleguide/' //スタイルガイド用ディレクトリ
}


var appRootPC,appRootSP,staticFlg;
if(env.server) { // ※３
  appRoot = '/styleguide/pc';
  staticFlg = true;
} else {
  appRoot = '';
  staticFlg = false;
}

gulp.task('styleguide:generate', function () {
  gulp.src([paths.srcDir + 'sass/**/*.scss'])
    .pipe(styleguide.generate({
      title: 'my Styleguide',
      server: true,
      port: 9800, // ※１
      rootPath: paths.sgDir,
      overviewPath: paths.srcDir + 'sass/overview.md',
      afterBody: [
        '<script src="' + appRootPC + '/js/build.js"></script>' // ※４
      ],
      disableEncapsulation: true,
      disableHtml5Mode: staticFlg,
      appRoot: appRootPC
    }))
    .pipe(gulp.dest(paths.sgDir));
});

gulp.task('styleguide-pc:applystyles', function () {
  gulp.src([paths.srcDir + 'sass/**/*.scss'])
    .pipe(bulkSass())
    .pipe(sass({
      errLogToConsole: true
    }))
    .pipe(styleguide.applyStyles())
    .pipe(gulp.dest(paths.sgDir));
});


gulp.task('watch',function(){
  gulp.watch(paths.srcDir + 'sass/**/*.scss', ['styleguide']);
});

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

これを
$ gulp styleguide
で叩くとスタイルガイドが単体で動き

または
$ gulp watch
しておけば、sassファイルを監視してスタイルガイドが生成されます。

※１で設定したポートで、生成したスタイルガイドが確認できます。やったー

サーバーでも見れるようにしたい

黒い画面が触れないひとにも確認してもらえる状態にするために、サーバーにあげて見られるようにします。
このままサーバーにあげると、パスが通らないのでエラー出まくって画面真っ白になるだけなので心が折れます。

1.プラグインの「minimist」を使って、gulpコマンド叩く際のオプションを引数として渡せるようにする。（※１）
2.if文で、「server」オプションがある場合、SC5-styleguideのプロパティ「appRoot」にサーバー上のパスを設定する
3.生成されたstyleguideフォルダをサーバーにごっそりあげる。
4.サーバーで見れる。やったー

サーバーにあげられると、フロントとバックエンドが別で動いているときも、こんなパーツ入りますとか必要ならこっから参照してくださいとかができるので、しあわせになれます。

スタイルガイドにjsの読み込み

もいっこ要件、スタイルガイドのモジュール上で、js使ってたり（ex. ナビゲーションの開閉とか）、画像使ってたりする場合にもきちんと見れるようにしたい。

※４のように、gulpファイルに外部ファイルの読み込みを記載できます。afterBody以外にも用意されてるので、jsファイル以外も読み込み放題。

beforeBody
afterBody
afterSections

ほかにも便利機能あってあいせる

スタイルガイド内で子要素をincludeできたりとか、
スタイルガイド内にマークダウンもかけたようなきがする（曖昧な記憶）

そんなかんじでスタイルガイド、いろいろ使い倒すと便利だなってポエムでした。