Documentation in CSS with KSS

In the last three projects I’ve been using something new that I would like to share with you. It’s called KSS.

KSS is a methodology for documenting CSS stylesheets and it’s mainly used for generating styleguides. Basically it’s a set of simple rules for defining comments in a CSS stylesheet. These stylesheets can then be parsed by KSS to generate a styleguide for your application.

Why it helps

Creating a styleguide with KSS has some big advantages:

You start thinking in components instead of pages

When I was working on my first styleguide I immediately noticed that I shifted from thinking in pages to components. Before KSS when I found a button in the design I started to build it in the page right away. This could lead to double declarations for similar buttons and some page specific CSS. When you make a styleguide you start by searching the design for reusable elements, this really makes your CSS cleaner.

You document all your stylesheets

This one is a little bit obvious because you need the comments to generate a styleguide you are forced to write simple documentation.

You have living documentation of your CSS

The styleguide is generated with the css of your application, so it will always be up to date.

Refactoring is less scary

Refactoring (changing old code) is less scary because you always have a bird’s-eye view of all the design elements you have on your site. This means you see what’s happening to element X, Y and Z when you change A.

It’s easier to do cross browser testing

It’s really easy to open your styleguide in every browser you have. Most of the times the styleguide doesn’t require any database connection or login which means it’s really easy to access.

It shows the HTML implementation to other developers

In the fork I created for KSS-rails (a Rails plugin for KSS) the source code of the HTML snippet is automatically rendered under every styleguide element. This shows the implementation of your design to other developers.

It shows all (defined) variations

In the KSS comment block you can define variations (as shown in the example below). These variations can also include :hover and :active states.

It can be used to test content edge cases

I use the styleguide to test content edge cases. For example, what happens when there is a lot of text in a certain box. Or what happens if there are two of these blocks next to each other.

How to use it

This is an example of a styleguide element from my latest project:

The CSS code

The important part of the CSS file is the comment on the first few lines

/*
Follow status button

.following      - A user is already following
.not_following  - A user is not following
.unknown        - A user is not signed in

Styleguide 2.3
*/

.follow-status {
  display: block;
  overflow: auto;
  border: #E4E4E4 solid 1px;
  position: relative;

  $height: 45px;
  $tick_width: 50px;
  $margin: 5px;
  background-color: white;

  // ###############################################
  // # full scss code can be found at:
  // # https://gist.github.com/6356813ac75a1e297330
  // ###############################################

}

The HTML template code

<%= styleguide_block '2.3' do -%>
  <a href="" class="button $modifier_class">Text on button</a>
<% end -%>

Hello, I'm Jankees van Woezik

Like this post? Follow me at @jankeesvw on Twitter