KSS Styleguide

DZone 's Guide to

KSS Styleguide

KSS (Knyle Style Sheets) is a documentation for CSS, quite clear for developers and well-structured for programmatic processing. Let's take a look at it.

· Web Dev Zone ·
Free Resource

What is KSS?

KSS (Knyle Style Sheets) is a documentation for CSS, quite clear for developers and well-structured for programmatic processing. For a better understanding, I recommend reading this very nice article about KSS concept.

How does it look in code? An example of a buttons.css file:


A button suitable for giving stars to someone.

: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.

Styleguide 2.1.3.











As seen in the example, CSS documentation is provided via the comments in the following way: the first line is a description of this section. Next, there is a list of modifier classes and pseudo-classes, which we are documenting and their order. Wherein, it is not necessary to make documentation for each CSS element. It  is enough to specify the behavior of the main elements and the most used ones.

The last line of the comment defines location of the description: 2.1.3 - in this case it is section 2 with the indication of items and sub-items. The hierarchy can be different depending on the developer’s needs. For instance:

1. Text styling

2. Buttons

  2.1 Form Buttons


  2.2 Other buttons


3. Forms

  3.1 Text fields

  3.2 Radio and checkboxes

According to this documentation, a special styleguide page is generated and in this page you can see the documented CSS with description. An example:


If you use preprocessors (sass, less), it is rather convenient to describe mixins and their parameters:

// Creates a linear gradient background, from top to bottom.


// $start - The color hex at the top.

// $end - The color hex at the bottom.


// Compatible in IE6+, Firefox 2+, Safari 4+.

@mixin gradient($start, $end){



What is it Meant for?

Does it make sense to bother with it if you are a single developer in a small project? Practice shows that even a small project requires at least a basic maintenance and modifications: to add a banner or enlarge a text. Sometimes, there are quite many slight edits which can spoil even a crystal clean CSS.

The advantages of documented CSS:

  • It is easy to maintain such CSS. It remains clean and readable, which reduces time for writing new CSS code.

  • CSS is structured by files. This allows to quickly find existing styles, use them and avoid duplication.

  • Writing such CSS helps in developing a good habit.

  • It simplifies keeping consistency in the project.

At Which Stage Should We Use It?

I would recommend to introduce it in the initial stage, when the project is not spoiled with the style sheets yet, which you have to delve into to find the necessary elements.

Ideally, the practical side of marking up should be organized like this:

  • Building the HTML-structure

  • Describing the main CSS styles, buttons, blocks and other elements in accordance with KSS documentation

  • Creating other unique CSS styles

In other words, it should be the first stage of the layout creation process: defining and documenting the main page elements (forms, buttons, headings, text, UI elements, etc.) and only after that can more elaborate things can be done. Thus, we move from the general to the special.

What Framework to Choose?

The principal idea of the frameworks is quite simple: in styles, the descriptive part goes in comments in the beginning of the file. And by headings, they are automatically added to the list of guides.

Creating the descriptions-docs is a kind of tests for CSS. They can and should be defined before writing the styles in order to specify what exactly should be contained in the given block.

At GitHub, you can find an excellent example of Styleguide. Of course, it would be nice to have the documentation also in HTML and JS.

The Alternatives

Along with KSS, there are other handy tools with a similar principle of operation:

css, css / style sheets, web dev

Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}