document CSS with KSS ( Knyle Style Sheets)

Documenting CSS code is often not that easy. Especially structuring big CSS files can be a challenge. Living styleguides can be a solution and there are many different generators for creating them. Also pattern libraries can be a solution, for example based on Patternlab.

But these are often not framework agnostic, need different setups per project and are either not actively maintained anymore or are rapidly changing.

Kyle Neath saw this and other problems and created Kyle Style Sheets (KSS). KSS is completely framework agnostic and can be used in any project and for any type of CSS to create living styleguides and document the CSS code. This greatly helps to write maintainable and scalable CSS.

There are different implementations of KSS in different programming languages. kss-node for NodeJS is one of them and it is currently the most actively maintained and mature solution. The setup is very easy. First you have to install it globally:

yarn global add kss npm i -g kss

Then you have to document your CSS code with specific comments.

/*
Button

Your standard button suitable for clicking.

:hover   - Highlights when hovering.
.shiny   - Do not press this big, shiny, red button.

Markup: button.html

Style guide: components.button
*/
.button {
}
.button.shiny {
}

The comment block consists of different sections which are separated by empty lines:

• component name
• component description
• modifiers with description
• reference to file with the markup for this component (needed for preview and code block)
• category in generated living styleguide

You can use handlebars (default setting) nunjucks and twig. This is processed and converted to the final markup for the living styleguide. You can generate a simple living styleguide with just a few files and a single command:

kss --css ../styles/style.css --source styles

The --css flag is used to generate a link tag which points to your final generated stylesheet and which is applied to the generated living styleguide. The --source flag points to the source directory with the documented components.

CSS code with the needed comments:

/*
Button

Your standard button suitable for clicking.

.success   - Everything fine, click to accept.
.warning   - Warn the user, a click might be dangerous.
.error     - Indicate that an action failed.

Markup: ../components/button.hbs

Style guide: components.button
*/
.button {
    background: transparent;
}

.button.success {
    background: green;
}

.button.warning {
    background: orange;
}

.button.error {
    background: red;
}

The (default) homepage of the living styleguide:

# This is the generated styleguide

The markup file for the button component:

<button class="button {{modifier_class}}">test</button>

You can find the used files here. kss-node has many more interesting features which are also described in the wiki. Additionally there is a flexible JavaScript API. The files of the official demo can be found here.