スタイルガイドに KSS を導入

grunt css

StyleDocco より kss のほうがナウそうなので使ってみる

インストール

npm install grunt-kss

Gruntfile.js の設定例は以下

kss: {
  options: {
    includeType: 'css',
    includePath: 'path/to/style.css'
  },
  dist: {
    files: {
      'docs/styleguide': ['path/to/source_dir']
    }
  }
}

意味はこんな感じ

  • path/to/source_dir 以下のスタイルシート(scssとか)をパース
  • docs/styleguide ディレクトリにスタイルガイド用の HTML などを生成
    • 自動生成されないので事前に対象ディレクトリを作成しておくこと (2014/06/19追記)
  • path/to/style.css を生成したHTMLで読み込む

kss-node のバグなのか知らんけど .scss なファイルを --sass オプションで指定しても 0バイトな css が生成されてどーにもならなかったのでとりあえず .css を使うことにした

grunt.registerTask('styleguide', ['compass', 'kss']);

Sass にスタイルガイド用のコメントを書く

kss はコメントの記述をパースしてスタイルガイドを生成するらしい

以下、記述例

// A button suitable for giving stars to someone.
//
// description desu yo
// description desu ze
//
// :hover             - Subtle hover highlight.
// .stars-given       - A highlight indicating you've already given a star.
// .stars-given:hover - Subtle hover highlight on top of stars-given styling.
// .disabled          - Dims the button to indicate it cannot be used.
//
// Markup:
// <button class="button {$modifiers}">Button (button.button)</button>
// <a href="#" class="button {$modifiers}">Button (a.button)</a>
//
// hogefugahogefuga
//
// Styleguide 1.1.
html {
    .button {
        background-color: #CCC;
        &:hover {
            font-weight: bold;
        }
        &.stars-given {
            color: #FFFFCC;
            &:hover {
                color: white;
            }
        }
        &.disabled {
            color: #AAA;
        }
    }
}

スタイルガイド用コメントのルールはなんとなく以下な感じ

  • コメント1行目はタイトルになる
  • タイトルの下に1行開けて文を書くと説明文になる
  • :hover とか .class-name とかを1行ずつ書くとスタイルガイドにHTMLが生成される
  • Markup:: :hover とかで指定した要素を HTML として書き出し
    • {$modifiers} を指定すると指定した .class-name とかが挿入される
  • Styleguide <ref>.: Styleguide の後ろに数字+.を繋げると章番号になる
    • ex. Styleguide 1.2. == Chapter 1.2
  • タイトルや説明文などのセクション？は空行で区切る

grunt-kss は内部で kss-node を実行しているらしいので記法とかの詳細は以下を参照

hughsk/kss-node

実行

grunt styleguide