スタイルガイドは全く使ったことがありませんでしたが、ちょっと使う機会があったので試してみました。

調べてみると、Node製のstyledoccoやRuby製のhologramなどがあるそうですが、たまたまSNSでシェアされていたNode製の「sc5-styleguide」というものを使ってみました。

ざっと調べてみた感じ高機能で最近でも更新されているようなことが書かれていました。

gulpやGruntで使えてJadeやSass・Lessなどができるみたいですが、今回はgulpでSassのスタイルガイドを作ってみます。

もくじ
  1. インストール
  2. gulpfileの作成
  3. スタイルガイドを作ってみる
  4. ガイドのメニューを増やす
  5. ガイドをツリー状にする
  6. 設定いろいろ
  7. 検索機能
  8. 画像やフォントを使いたい

インストール

プロジェクトフォルダ内でpackage.jsonを作ります。

npm init -y

次にgulpと今回使うsc5-styleguide、sassをインストールします。

npm i gulp gulp-sass sc5-styleguide -D

sc5-styleguideをインストールする時若干時間かかる感じがします。

gulpfileの作成

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('styleguide/**/*.scss')
    .pipe(styleguide.generate({
        title: 'My Styleguide',
        server: true,
        port: 4000,
        rootPath: outputPath,
        overviewPath: 'styleguide/overview.md'
      }))
    .pipe(gulp.dest(outputPath));
});
gulp.task('styleguide:applystyles', function() {
  return gulp.src('styleguide/style.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(['styleguide/**/*.scss'], ['styleguide']);
});
gulp.task('styleguide', ['styleguide:generate', 'styleguide:applystyles']);

GitHubのドキュメントから、パスなどを少し変更しています。

スタイルガイドを作ってみる

上記のgulpfileの設定で「styleguide」ディレクトリを使うように書いたので、まずはstyleguideディレクトリを作り、overview.mdも作ります。

styleguide/overview.md

このファイルはマークダウンで概要を書くところです。スタイルガイドに反映されます。

# スタイルガイドのサンプル
概要を書く

次に同じ階層にstyles.scssを作り、以下を書いてみます。

styles.scss

// Button
//
// スタンダードなボタン
//
// Markup:
// <button class="btn btn-primary">ボタン</button>
//
// Styleguide 1.0.0
.btn {
  display: inline-block;
  padding: 6px 12px;
  margin-bottom: 0;
  font-size: 14px;
  font-weight: 400;
  line-height: 1.42857143;
  text-align: center;
  vertical-align: middle;
  cursor: pointer;
  border: 1px solid transparent;
  border-radius: 4px;
}
.btn-primary {
  color: #fff;
  background-color: #337ab7;
  border-color: #2e6da4;
  &:hover {
    color: #fff;
    background-color: #286090;
    border-color: #204d74;
  }
}

コメントアウトしてるところに、コメントを書いたりします。けっこう制約は厳しくて、ちょっと間違うとエラーがでます。

この状態で、一旦以下コマンドを打ちます。

gulp watch

gulpfileの設定でポート番号を4000番にしたので、「localhost:4000」を開きます。

するとこんな画面に

buttonのページを開くとこんな感じです。

「show css」をクリックするとCSSコードを見ることができます。

ガイドのメニューを増やす

ボタンのスタイルガイド以外にも、例えばフォントのページを作ってみます。

まずは、ファイル分割しましょう。その方がページが増えた時管理しやすいはず。style.scssを以下のように修正して、各ディレクトリを作ります。

@import "button/button";
@import "typography/typography";

button.scssを作り、先ほどのstyle.scssに書いたことをコピペします。そして、typographyディレクトリを作りtypography.scssも作っておきます。

typography.scss

// Typography
//
// Typographyのスタイルガイド
//
// Styleguide 2.0.0

sc5-styleguideはコメントアウト内の「Styleguide」の数字で管理しています。この数字が重複するとエラーがでます。

先ほどのbuttonが1.0.0だったので、Typographyトは2.0.0にしておきます。

そして、「gulp watch」で再起動すると

追加されています。

ガイドをツリー状にする

先ほど作った「Typography」にスタイルガイドを追加していきます。

typography.scssを以下のように追記します。

// Typography
//
// Typographyのスタイルガイド
//
// Styleguide 2.0.0
// Headings
//
// 見出しのスタイル
//
// Markup:
// <h1>h1. heading</h1>
// <h2>h2. heading</h2>
// <h3>h3. heading</h3>
// <h4>h4. heading</h4>
// <h5>h5. heading</h5>
// <h6>h6. heading</h6>
//
// Styleguide 2.1.0
.h1, h1 {
    font-size: 36px;
}
.h2, h2 {
  font-size: 30px;
}
.h3, h3 {
  font-size: 24px;
}
.h4, h4 {
  font-size: 18px;
}
.h5, h5 {
  font-size: 14px;
}
.h6, h6 {
  font-size: 12px;
}

Styleguideの数字を2.1.0にして追加しています。

すると、メニューがツリー状になり「Heading」ページを開くとこのようになります。

typography.scssの中に追加していく以外にもファイル分割すれば管理しやすいです。

typographyディレクトリの中にalignment.scssを作り以下を書きます。

typography/alignment.scss

// Alignment
//
// 整列
//
// Markup:
// <p class="text-left">Left aligned text.</p>
// <p class="text-center">Center aligned text.</p>
// <p class="text-right">Right aligned text.</p>
// <p class="text-justify">Justified text.</p>
//
// Styleguide 2.2.0
.text-left {
  text-align: left;
}
.text-center {
  text-align: center;
}
.text-right {
  text-align: right;
}
.text-justify {
  text-align: justify;
}

そして、style.scssで読み込みます。

@import "button/button";
@import "typography/typography";
@import "typography/alignment";

するとalignmentページが追加されます。

こんな感じでスタイルガイドを増やしていきます。

設定いろいろ

gulpfileに戻って設定を見てみます。

この部分

gulp.task('styleguide:generate', function() {
  return gulp.src('styleguide/**/*.scss')
    .pipe(styleguide.generate({
        title: 'My Styleguide',
        server: true,
        port: 4000,
        rootPath: outputPath,
        overviewPath: 'styleguide/overview.md'
      }))
    .pipe(gulp.dest(outputPath));
});

title (string, optional)

スタイルガイドのタイトルを設定するところです。

extraHead (array or string, optional)

スタイルガイドのheadタグにcssやjsを指定できます。

gulp.task('styleguide:generate', function() {
  return gulp.src('styleguide/**/*.scss')
    .pipe(styleguide.generate({
        title: 'My Styleguide',
        extraHead: [
          '<link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/css/bootstrap.min.css" integrity="sha384-BVYiiSIFeK1dGmJRAkycuHAHRg32OmUcww7on3RYdg4Va+PmSTsz/K68vbdEjh4u" crossorigin="anonymous">'
        ],
        server: true,
        port: 4000,
        rootPath: outputPath,
        overviewPath: 'styleguide/overview.md'
      }))
    .pipe(gulp.dest(outputPath));
});

sideNav (boolean, optional, default: false)

trueにするとメニューがサイドバーになります。

beforeBody (array or string, optional)

body直下にタグを挿入できます。

gulp.task('styleguide:generate', function() {
  return gulp.src('styleguide/**/*.scss')
    .pipe(styleguide.generate({
        title: 'My Styleguide',
        beforeBody: '<div>sample</div>',
        server: true,
        port: 4000,
        rootPath: outputPath,
        overviewPath: 'styleguide/overview.md'
      }))
    .pipe(gulp.dest(outputPath));
});

何に使うかはよくわかってないです。

afterBody (array or string, optional)

beforeBodyと同じような感じで、コンテンツの最後にタグを挿入できます。

commonClass (string or array of strings, optional)

以下のように指定します。

gulp.task('styleguide:generate', function() {
  return gulp.src('styleguide/**/*.scss')
    .pipe(styleguide.generate({
        title: 'My Styleguide',
        commonClass: 'styleguide-body',
        server: true,
        port: 4000,
        rootPath: outputPath,
        overviewPath: 'styleguide/overview.md'
      }))
    .pipe(gulp.dest(outputPath));
});

これを指定すると、この範囲を囲むようにclassを追加してくれます。

使いどころは掴めてないですが、bodyタグに指定してるスタイルはスタイルガイドではクリアされてしまうようです。例えば%指定のフォントサイズの元となるサイズや、font-familyなど。

そういう時に、このclassでbodyタグ代わりに使ったら、上手くいったのでそういう使い方もできそうです。

server (boolean, optional)

true/falseで指定します。Webサーバの立ち上げに使います。オートリロードもこれでやってるみたいです。

port

ポートの指定をできます。

rootPath (string, optional)

serverで立ち上げる時のルートパスの指定です。

appRoot (string, optional)

謎。調べ中。ローカルじゃなくて、どこかで公開する時に指定するんですかね。。

Define the appRoot parameter if you are hosting the style guide from a directory other than the root directory of the HTTP server. If the style guide is hosted at http://example.com/styleguide the appRoot should be styleguide.

When using the build as a subdirectory of your application, tune your server to resolve all the paths to that subdirectory. This allows Angular to deal with the routing. However, the static files should be resolved as they are stored.

styleVariables (string, optional)

sc5-styleguideは変数をスタイルガイド上から変更して指定することができます。

gulp.task('styleguide:generate', function() {
  return gulp.src('styleguide/**/*.scss')
    .pipe(styleguide.generate({
        title: 'My Styleguide',
        server: true,
        port: 4000,
        rootPath: outputPath,
        styleVariables: "styleguide/styleguide_variables.scss",
        overviewPath: 'styleguide/overview.md'
      }))
    .pipe(gulp.dest(outputPath));
});

例えば、こんな感じでstyleVariablesのパスを指定し、以下のファイルに変数を書きます。

styleguide/styleguide_variables.scss

$btncolor: #5cb85c;
$btnborder: #4cae4c;

style.scssにもインポートしておきます。

@import "styleguide_variables.scss";
@import "button/button";
@import "typography/typography";
@import "typography/alignment";

そして、最初に作ったbutton.scssを修正します。

// Button
//
// スタンダードなボタン
/* 省略 */
.btn-primary {
  color: #fff;
  /* 変数を埋め込む */
  background-color: $btncolor;
  border-color: $btnborder;
  &:hover {
    color: #fff;
    background-color: #286090;
    border-color: #204d74;
  }
}

そして、更新して画面右にある「designer tool」をクリックすると、設定画面が開きます。

この右のメニュー上でカラーピッカーや16進数を指定して、「save changes」をクリックすると、ソースコードにもコードが反映されます。すごい!

disableHtml5Mode (boolean, optional, default: false)

謎。調べ中。

basicAuth (object, optional, default: null)

ベーシック認証をかけられます。使いどころはわからないです(誰か教えて)

gulp.task('styleguide:generate', function() {
  return gulp.src('styleguide/**/*.scss')
    .pipe(styleguide.generate({
        title: 'My Styleguide',
        server: true,
        port: 4000,
        rootPath: outputPath,
        styleVariables: "styleguide/styleguide_variables.scss",
        overviewPath: 'styleguide/overview.md',
        basicAuth: {
          username: 'username',
          password: 'password'
        }
      }))
    .pipe(gulp.dest(outputPath));
});

readOnly (boolean, optional, default: false)

trueにすると、先ほど紹介した変数をブラウザから変更することができなくなります。見ることはできます。リードオンリーですね。

customColors (string, optional)

どうもデフォルトの色を変えたりできるっぽいですが、やり方がイマイチわからんです。

parsers (object, optional)

調べ中。

styleguideProcessors (object, optional)

調べ中。

filesConfig (array, optional) (Experimental feature)

調べ中。

additionalNgDependencies (array or string, optional)

調べ中。Angularのなんかができるのかな…。

検索機能

右上のアイコンの検索するところに入力するとリアルタイムで検索してくれます。便利ー。

画像やフォントを使いたい

画像やフォントを使うにはコピーしてください的なことが書かれています。(ここ)

gulp.task('fonts', function() {
  gulp.src(['styleguide/fonts/**'])
    .pipe(gulp.dest(outputPath + '/fonts/'));
});

こんな感じのを記述して、ここに組み込んじゃいましょう。

gulp.task('watch', ['styleguide', 'fonts'], function() {
  // Start watching changes and update styleguide whenever changes are detected
  // Styleguide automatically detects existing server instance
  gulp.watch(['styleguide/**/*.scss'], ['styleguide']);
});

あとは、sassでいつも通り@font-faseとかで読み込めばいけます。ダメ場合はパスが間違ってないかなどみてください。

最後に

オプションの最後は調べ中ばかりですいません。

sc5-styleguideはまだそんなにドキュメントない印象なので、こんな使い方あるよーなどあればぜひ教えて欲しいです。

今回作ったサンプルはGitHubで公開しています。変なところがあればプルリクください!

styleguide-sample

分からないところ

  • styleguide_variablesで個別ページでも変数指定できるっぽいけどやりかた分からない
  • ローカルで動いてるけど、公開したいときどうするの(公開するようなファイルなさそう)
  • 書いたSassコードが自動でスタイルガイドにも反映されたりしないのかな
Tweet
このエントリーをはてなブックマークに追加
Pocket