スタイルガイドジェネレータ「sc5-styleguide」の使い方

Tag:

スタイルガイドジェネレータである「sc5-styleguide」の使い方について紹介します。ここでは、例としてBootstrapのSassファイルにスタイルガイド用のコメントを追記してスタイルガイドを作成してみます。

sc5-styleguideについて

スタイルガイドジェネレータといえば、次のようなものが有名です。

・StyleDocco:Node.js実装
・KSS:Ruby実装
・kss-node:Node.js実装

「sc5-styleguide」は、KSSのコメント記法を受け継いだNode.js実装のスタイルガイドジェネレータです。次のような便利な機能を使うことができます。

・Webソケットを介した自動ブラウザ更新
・Sass変数の値をブラウザ上から修正

下記の方法でスタイルガイドを作成できます。

・コマンドライン操作での作成
・gulpタスクでの作成
・Gruntタスクでの作成

ここでは、gulpタスクとしてスタイルガイドを作成していきます。gulpの使い方については下記ページで取り上げてます。
開発環境 : Gulpの使い方 | DN-Web64

作業フォルダ

下記フォルダで作業を進めます。

bower_components
├─ bootstrap       bootstrapのパッケージ
└─ jquery          jqueryのパッケージ

node_modules
├─ gulp            gulpモジュール
├─ gulp-sass       gulp-sassモジュール
└─ sc5-styleguide  sc5-styleguideモジュール

output             ★今回、このフォルダにスタイルガイドを生成していきます。
README.md          マークダウン形式で記述されたファイル。overview(概説)で利用。
bower.json         bowerのライブライ管理ファイル
gulpfile.js        Gulpの処理を記述
package.json       npmのライブラリ管理ファイル

bower_components配下のパッケージ
bowerをインストール済みであれば、下記コマンドで取得できます。

bower install bootstrap#v4.0.0-alpha.2 --save

まだ「alpha版」ですが、bootstrap4を指定しています。

node_modules配下のモジュール
node.jsをインストール済みであれば、下記コマンドで取得できます。

npm install gulp --save-dev
npm install gulp-sass --save-dev
npm install sc5-styleguide --save-dev

README.md
下記記述をしました。

# DN-Web64
SC5 style guide generatorのテストです。bootstrapのstyle guideを作成してみます。

まずは動かしてみる

gulpfile.jsに以下記述をしてgulpタスクを実行します。

gulpfile.jsの記述を表示する
var gulp = require('gulp');
var sass = require('gulp-sass');
var styleguide = require('sc5-styleguide');
var outputPath = 'output';
var srcPath = 'bower_components/bootstrap/scss'

gulp.task('styleguide:generate', function () {
    return gulp.src(srcPath + '/*.scss')
            .pipe(styleguide.generate({
                title: 'DN-Web Styleguide Test',
                server: true,
                rootPath: outputPath,
                overviewPath: 'README.md'
            }))
            .pipe(gulp.dest(outputPath));
});

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

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

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

gulp.task('default', ['watch']);

9行目
generate():KSSマークアップの解析、変数情報の収集を行います。

23行目
applyStyles():スタイルガイドで使用される実際のスタイルシートを作成します。

sc5style
デフォルトだと3000ポートが利用されるようです。

「http://localhost:3000/」にアクセスしてみます。
sc5style1
まだスタイルガイド用のコメントを記述していないためOverviewだけ表示されています。「README.md」の内容が表示されていますね。

スタイルガイド用コメントを記述してみる

buttonコンポーネント用のスタイルガイドを作成します。「bower_components/bootstrap/scss/_buttons.scss」にスタイルガイド用コメントを追記します。

追記内容を表示する
/*
Button

ボタンコンポーネントです。

.btn            - Base styles
.btn:focus      - focus
.btn-primary    - primary 
.btn-secondary  - secondary

Markup:
<button class="btn {$modifiers}">Button text</button>

Styleguide 1.0.0
*/

2行目
セクションタイトルを記述します。

4行目
セクションの説明を記述します。

6~9行目
コンポーネントのmodifierを記述します。

11~12行目
スタイルガイドに表示するHTMLを記述します。

14行目
セクションです。ブラウザ表示のナビゲーションに利用されます。

※3,10,13行目の空欄行は必須です。
※Markup,Styleguideの頭文字は大文字で記述します。

追記して保存すると自動でブラウザも更新されます。以下のように「Buttonセクション」が追加されました。
sc5style2

スタイルは、modifierの分だけ表示されています(赤矢印)。{$modifiers}には、各modifierの値が展開されています(緑矢印)。
sc5style3

sass変数の値修正

右側に「Designer Tools」というボタンがあります。
sc5style7

クリックすると、現在表示しているセクションに関連するSass変数の一覧が表示されます。
sc5style8
ローカルでサーバーを動かしているのであれば、ここで値を変更すると自動でファイルの値も変更してくれます。

セクションを追加

formコンポーネント用のスタイルガイドを作成します。「bower_components/bootstrap/scss/_forms.scss」にスタイルガイド用コメントを追記します。

「_forms.scss」への追記内容を表示する
/*
Forms

フォームコンポーネントです。

.form-control            - Base styles
.form-control-sm	  - small	
.form-control-lg   - large

Markup:
<div class="form-group">
    <div class="input-group">
        <input class="form-control {$modifiers}">
    </div>
</div>

Styleguide 2.0.0
*/

/*
validation states

.has-success            - success
.has-warning	  - warning
.has-danger   - danger

Markup:
<div class="form-group {$modifiers}">
    <div class="input-group">
        <input class="form-control">
    </div>
</div>

Styleguide 2.1.0
*/

Styleguideで指定した値を元にナビゲーションが作られてますね。
sc5style4

javascriptを読み込む

navbarコンポーネント用のスタイルガイドを作成します。「bower_components/bootstrap/scss/_navbar.scss」にスタイルガイド用コメントを追記します。

「_navbar.scss」への追記内容を表示する
/*
Navbar

collapse - collapse

Markup:
<nav class="navbar navbar-light bg-faded">
<!-- Toggle Button -->
<button class="navbar-toggler hidden-sm-up" type="button" data-toggle="collapse" data-target="#nav-content">
☰
</button>
<!-- Nav Content -->
<div class="collapse navbar-toggleable-xs" id="nav-content">
<a class="navbar-brand" href="#">Logo</a>
<ul class="nav navbar-nav">
<li class="nav-item">
<a class="nav-link" href="#">Link 1</a>
</li>
<li class="nav-item">
<a class="nav-link" href="#">Link 2</a>
</li>
<li class="nav-item">
<a class="nav-link" href="#">Link 3</a>
</li>
</ul>
</div>
</nav>

Styleguide 3.0.0
*/

navbarのスタイルガイドが追加されましたが、展開ボタンを押しても展開されません。
sc5style5

展開の動きを確認するには、javascriptが必要です。そこで「gulpfile.js」を修正してgulpを再実行します。

gulpfile.jsの修正内容を表示する
var gulp = require('gulp');
var sass = require('gulp-sass');
var styleguide = require('sc5-styleguide');
var outputPath = 'output';
var srcPath = 'bower_components/bootstrap/scss'

gulp.task('styleguide:generate', function () {
    return gulp.src(srcPath + '/*.scss')
            .pipe(styleguide.generate({
                title: 'DN-Web Styleguide Test',
                server: true,
                rootPath: outputPath,
                overviewPath: 'README.md',
                extraHead: [
                    '<script src="/js/jquery.js"></script>',
                    '<script src="/js/bootstrap.js"></script>'
                ],
                disableEncapsulation: true
            }))
            .pipe(gulp.dest(outputPath));
});

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

gulp.task('watch', ['styleguide'], function () {
    gulp.watch([srcPath + '/**/*.scss'], ['styleguide']);s
});

gulp.task('js', function () {
    gulp.src(['bower_components/jquery/dist/jquery.js',
            'bower_components/bootstrap/dist/js/bootstrap.js'])
            .pipe(gulp.dest(outputPath + '/js'));
});

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

gulp.task('default', ['watch','js']);

追記箇所
14~18行目、36~40行目

修正箇所
44行目

今度は、展開ボタンを押すと展開されました。
sc5style6

その他の使い方

下記サイトを参考にしてみてください。
http://styleguide.sc5.io/
https://github.com/SC5/sc5-styleguide

スポンサーリンク