Styleguide

SC5-Styleguide の始め方

More than 1 year has passed since last update.

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


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


  • 面倒だからそのうちメンテされなくなる

  • 自動デプロイは必須。

  • 作るならしっかりワークフローに取り込んで

  • できればお客さんに公開してメンテの意識を。