KSS(Knyle Style Sheets)でstyleguideを作成

ruby

前回はStyleDoccoを試したので、もう一つのKSS(Knyle Style Sheets)も試してみた。

KSSについて

KSSはTomDocをモデルに開発された stlyeguide generatorらしい。
A better future with KSS をみればどんなものか把握できそう。
CSSを文書化して、各UIの状態を視覚化することで保守性を高めらる。また生成されるドキュメントは階層構造を持っているのでスタイルの継承を把握しやすい感じですかな。

Styledoccoと同じくcssやScssなどのファイルにコメント追加するのですが、KSSの場合はフォーマットがあります。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
//
// スタイルに関する仕様や説明を記載。
// Starを付けるbutton
//
// Experimental: A/Bテストなどの実験的要素
//
// Deprecated: 廃止予定の要素
//
// modifiers(修飾子)  要素の状態(疑似クラスなど)を文章化
// :hover             - hover時のハイライト
// .stars-given       - 与えられたStarのハイライト
// .stars-given:hover - StarのHover時のハイライト
// .disabled          -disbled時のスタイル
//
// セクション情報 参照情報(ドット区切り)
// Styleguide 2.1.3.
//

また CSS PreprocessorのHelper(mixinやfunction)などについても説明を使います。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
// 縦方向のグラデーション
//
// $start - 開始点の色(HEX)
// $end   - 終点の色(HEX)
//
// Compatible in IE6+, Firefox 2+, Safari 4+.
@mixin gradient($start, $end){
  background: $start;
  background: -webkit-gradient(linear, left top, left bottom, from($start), to($end));
  background: -moz-linear-gradient(top, $start, $end);
  background: -o-linear-gradient($start, $end);
  background: linear-gradient($start, $end);
  filter: progid:DXImageTransform.Microsoft.gradient(startColorstr='#{$start}', endColorstr='#{$end}');
  zoom:1;
}

KSSはRubyで実装されたParserで、gemでインストールができる。
また、Rails用にkss-railsもあるので既存のRubyでのプロジェクトにも導入しやすそう。

Sinatraで試してみた

今回はSinatraでサンプルを生成してみた。
以下のような構成で、

1
2
3
4
5
6
kss
├── Gemfile
├── app.rb 
└── views
     └── sass
　　　      └── buttons.scss

Gemfile、app.rbは次のような感じ。

1
2
3
4
5
6
7
8
# Gemfile
source :rubygems
gem 'sinatra'
gem 'sinatra-contrib'
gem 'sass'
gem 'compass'
gem 'thin'
gem 'kss'
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
# app.rb
require 'sinatra'
require 'sinatra/capture'
require 'erb'
require 'sass'
require 'kss'

set :partial_template_engine, :erb
set :scss, :style => :compact

 # sassファイルを格納するディレクリをsassに変更した
set :views,   File.dirname(__FILE__)    + '/views/sass'

# kssでパーするファイルの格納ディレクトリ
before do
    @styleguide = Kss::Parser.new('views/sass')
end

helpers do

  # kssでパースするスタイルシートをまとめて出力
  def stylesheets
    stylesheets = ''
    @styleguide.sections.each do |key, val|
      filename = val.filename.split(/.scss/).first
      stylesheets += '<link rel="stylesheet" href="stylesheets/' + filename + '.css" type="text/css" />'
    end
    stylesheets
  end

  # セクション毎のサンプルを出力
  def styleguide_block(section, &block)
    @section = @styleguide.section(section)
    @sample_html = capture{block.call}
    @row_html = ERB::Util.html_escape @sample_html
    @_out_buf << erb(:_styleguide_partial)
  end

end

get '/stylesheets/*.css' do
  content_type 'text/css', :charset => 'utf-8'
  filename = params[:splat].first
  scss filename.to_sym
end

get '/' do
  erb :index
end

get '/:section' do
  # Routing
  case params[:section].to_i
  when 1.0
    erb :button
  end
end

__END__

@@ layout
<!DOCTYPE html>
<html>
<head>
  <meta http-equiv="content-type" content="text/html;charset=UTF-8" />
  <title>Styleguide Example</title>
  <link rel="stylesheet" href="stylesheets/layout.css" type="text/css" />
  <%= stylesheets %>
</head>
<body>
  <header>
    Styleguide
  </header>
  <iv id="wrapper">
    <nav role="main">
       <ul>
        <li><a href="/">Styleguide</a></li>
        <li><a href="/1.0">1.0 Buttons</a></li>
      </ul>
    </nav>
    <%= yield %>
  </div>
  <script src="javascripts/kss.js"></script>
</body>
</html>

@@ index
  <p>各セクションにスタイルガイドブロックを配置することでスタイルガイド生成できます。</p>

@@ button
  <% styleguide_block '1.1' do %>
    <button class="button $modifier">Button</button> 
    <a href="#" class="button $modifier"><span>Button</span></a>
  <% end %>

  <% styleguide_block '1.2' do %>
    <button class="small $modifier">Small</button> 
    <a href="#" class="small $modifier"><span>Small</span></a>
  <% end %>

@@ _styleguide_partial
<iv class="styleguide-example">
  <h3><%= @section.section %> <em><%= @section.filename %></em></h3>
  <iv class="styleguide-description">
    <p><%= @section.description %></p>
    <% if @section.modifiers.any? %>
      <ul class="styleguide-modifier">
        <% @section.modifiers.each do |modifier| %>
          <li><strong><%= modifier.name %></strong> - <%= modifier.description %></li>
        <% end %>
      </ul>
    <% end %>
  </div>
  <iv class="styleguide-element">
    <%= @sample_html %>
  </div>
  <% @section.modifiers.each do |modifier| %>
    <iv class="styleguide-element styleguide-modifier">
      <span class="styleguide-modifier-name"><%= modifier.name %></span>
      <%# $modifier を modifier に置換 %>
      <%= @sample_html.gsub('$modifier', "#{modifier.class_name}") %>
    </div>
  <% end %>
  <pre class="styleguide-code"><%= @row_html %></pre>
</div>

で、コメントを付きのScssファイルは以下のような感じ。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
// Buttons styles
//
// :hover    - Hovering highlights.
// :disabled - Disabled Style.
// .primary  - Primary action button style.
//
// Styleguide 1.1

@mixin gradient($start, $end){
  background: $start;
  background: -webkit-gradient(linear, left top, left bottom, from($start), to($end));
  background: -moz-linear-gradient(top, $start, $end);
  background: -o-linear-gradient($start, $end);
  background: linear-gradient($start, $end);
  filter: progid:DXImageTransform.Microsoft.gradient(startColorstr='#{$start}', endColorstr='#{$end}');
  zoom:1;
}

%button {
  padding: 5px 15px;
  border-radius: 3px;
  box-shadow: 0 1px 4px rgba(0, 0, 0, 0.15);
  text-decoration: none;
  font-weight: bold;
  font-family: "Helvetica Neue", Helvetica;
  line-height: normal;
  cursor: pointer;
}

.button {
  @extend %button;
  @include gradient(#fefefe, #e6e6e6);
  min-width: 120px;
  border: 1px solid #d0d0d0;
  color: #666;
  text-shadow: 0 1px rgba(255, 255, 255, 0.9);
  font-size: 12px;
  &:hover {
    @include gradient(#f2f2f2, #E2E2E2);
    border-color: #C5C5C5;
  }
  &:disabled {
    opacity: 0.5;
  }
}

.primary, 
.primary:hover {
  @extend .button;
  @include gradient(#007fcc, #0045cc);
  min-width: 120px;
  border-color: #0062b8;
  box-shadow: 0 1px 4px rgba(0, 0, 0, 0.2);
  color: #fff;
  text-shadow: 0 -1px 0 rgba(0, 0, 0, 0.4);
}

// Smaller uuttons styles
//
// :hover               - Hovering highlights.
// :disabled            - Disabled Style.
// .small-primary       - Primary action button style.
// .small-primary:hover - Primary action button hovering highlights 
//
// Styleguide 1.2

.small {
  @extend %button;
  @include gradient(#fefefe, #e6e6e6);
  border: 1px solid #d0d0d0;
  color: #666;
  text-shadow: 0 1px rgba(255, 255, 255, 0.9);
  font-size: 10px;
  &:hover {
    @include gradient(#f2f2f2, #E2E2E2);
    border-color: #C5C5C5;
  }
  &:disabled {
    opacity: 0.5;
  }
}

.small-primary {
  @extend .small;
  @include gradient(#85d868, #61b145);
  border-color: #74bb5a;
  box-shadow: 0 1px 4px rgba(0, 0, 0, 0.2);
  color: #fff;
  text-shadow: 0 -1px 0 rgba(0, 0, 0, 0.4);
  &:hover {
    @include gradient(#67cd43, #4c8c36);
    border-color: #4a993e;
  }
}

なかんじでやると、以下のような画面が生成されます。

GithubやTwitter BootstrapでみるStyleguideですね。
セクションで管理することで、要素のスタイルの継承が明確にできる点がいいですね。オブジェクティブなスタイルシート構成であればあるほどわかりやすいドキュメントを作成できそう。

RubyのプロジェクトならKSSを使うのも良さそうだ。

今回のサンプル

Comments