LoginSignup
5

More than 5 years have passed since last update.

SC5-Styleguide の始め方

Last updated at Posted at 2017-04-22
1 / 21

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

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

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

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
5