Styleguide framework: kss

If you or your company is planning to recreate a framework, it’s mandatory to have a sort of inventory of all the components, with a word styleguide. This not only will help you to remember the markup, but will be necessary for your colleague to understand how to create elements and avoid repetition, which means code bloat.

To do not underestimate also it’s important in terms of communication with people from other departments, mostly designers, since design guide and style guide go along. If they do not have one (duh), this will help them to understand how easy can turn their life.

 

Introduction to living styleguide

If you want to create a styleguide and keep documented your code (please do it), it’s a common practice to comment all the parts of it. From this common practice comes the idea of automate the generation of the styleguide, to keep it updated withoutrepeat yourself and save time.

There’s online a good amount of frameworks which do not need to be listed here, but personally I opted for a robust, simple and not opinionated: kss.

 

KSS tree explanation and setup

Though the result it’s quite satisfying, the documentation it’s not equally straightforward about the settings, that’s why I will list below as it has required to match my build and written some articles.

To create a documentation about your component, you must define a name and structure. The last one can be numerical or literal.


// Style documentation name
//
// Markup: this one can be inlined or linked to an HBS/HTML file, with path relative to the SCSS container
//
// Description of the guide
//
// .modifier - you must define a modifier, it can be a status or a class
//
// Style guide: parent.name

As you can see you must insert an empty line to divide the sections.

The markup and the result displayed will be generated from the markup.

 

Config example

Here is the list of the option which can be used for the kss-config.json:


"title": "Here goes the title",
"mask": "*.scss",

"//": "location relative to the config file, remember to scale up parents folder before access to the folder",
"//": "the source folder of your commented guide to be generated",
"source": "src/styles/",
"//": "where the styleguide will be stored",
"destination": "dist/styleguide",
"//": "If you want to write the index and change the location",
"homepage" : "../styleguide/homepage.md",

"//": "this is the asset which you want to use to make your styleguide works and looks",
"css": [
   "../styles/common.css",
   "../styles/common.min.css"
],
"js": []

 

Coming to Gulp and Jenkins

Besides the multiple themes available online which helps you to compile through Gulp/Grunt, such like SC5 and Michelangelo, if you have compiled your config file it’s possible to add just a command to your build:

kss --config kss-config.json

The only cons of this, it’s the lack of a clean task to remove unused files, so you must configure your pipeline to do so.

Related content: