スタイルガイドとは

スタイルガイドとはいわゆるサイトのデザインパターンやモジュールを集めたリストページで仕様や使い方、コードスニペットなどを記載したドキュメントのようなものです。

このスタイルガイド的なものは昔からありましたが手動でhtmlなどを作成していたかと思います。今ではcssのコメントなどから自動生成してくれるツールがいろいろとありその制作時間を短縮してくれます。

ただし自動で生成してくるとはいえデザインパターンやモジュールの更新などは手動で更新しなくていけません。

スタイルガイドを作成するメリットといえば、ソースコードの一貫性や品質を保つことで、サイトのパフォーマンスに一定の品質を担保をすることやサイトデザインの一貫性を保てますし、モジュールの使い方や指針を示すことで実装者が作業短縮でき効率よくサイト運営ができるのではないか思います。

スタイルガイドで検索すると世の中にはStyleDocco、KSS、Hologram、kalei等いろいろあります。

基本的にはCSSファイルのコメントに書かれたMarkdownをパースして、HTMLを生成してれるものです。

とcssに記述が増えるのでファイルの容量が気になるところですが、今はsassやlessなどプリプロセッサに対応しているスタイルガイドジェネレーターがほとんどで、スタイルガイド生成するときはコンパイルする前のものから生成したり、デプロイ時にはminifyなどすることで余計なコメントを削除できるのでcssの記述量が増えるのを気にすることなく使うことができます。

今回はPostCSS導入したのもあり

twitter.com

@morishitter_さんがつくった

postcss-style-guide

github.com

が気になったので使ってみたいと思います。

ビルドツールは前回使ったgulpで進めていきたいと思います。

インストール

$ npm install postcss-style-guide

gulpfile.js

var gulp = require('gulp');

gulp.task('default', function () {
    var postcss = require('gulp-postcss');
    var processedCSS = fs.readFileSync('output.css', 'utf-8');
    return gulp.src('src/*.css')
    .pipe(postcss([
        require('postcss-style-guide')({
            name: "Project name",
            processedCSS: processedCSS
        })
    ]))
    .pipe(gulp.dest('build/'));
});

input.css

/*

@styleguide

type: Element

# バッジ badge.css

使用HTMLタグ

`<i>`
<br>
<br>
<i class="badge is-completion">ほげほげ</i>

    <i class="badge is-completion">ほげほげ</i>

<i class="badge is-unfinished">未読</i>

    <i class="badge is-unfinished">未読</i>

<i class="badge is-required">必須</i>

    <i class="badge is-required">必須</i>

<i class="badge badge--lightGreen">ふが</i>
<i class="badge badge--lightGreen">もげ</i>
<i class="badge badge--lightGreen">はが</i>

    <i class="badge badge--lightGreen">クロス</i>

--------------------
*/
.badge {
    padding: 4px 6px;
    font-size: 12px;
    color: #fff;

    &.is-completion {
        background: #1d1dca;
    }

    &.is-unfinished {
        background: #ca1d1d;
    }

    &.is-required {
        padding: 2px 4px;
        border-radius: 5px;
        background: #f00;
    }

    &--lightGreen {
        background: #99cc67;
    }
}

ビルド

$ gulp

f:id:sekaie:20151218095233p:plain こんな感じにstyleguide.htmlが生成されます。

まとめ

スタイルガイド自動で生成されて非常に便利ではありますが、運営していく中でcssのコメントも同時に更新していかなくてはスタイルガイドとして機能しないので、これをうまい具合に作業フローに乗せて運営できたらと思います。

ほな

sekaie engineers' blog

セカイエ株式会社が主催するエンジニア勉強会について

スタイルガイド導入してみた

スタイルガイドとは

インストール

まとめ