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.

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:

Editor friendly shortcode: wp.mce.views

One of the coolest features WordPress offers us is the shortcode. They give the possibility to render a complex design with a lot of properties and connect an interface to it to input the values. It also can render an actual template as preview of is final result. The UI can be powered with AJAX … Continued

WordPress permalink and redirect made simple

If you are using WordPress inside a company, will come the time to change the permalink structure of your custom posts type (CPT), as request by the SEO department. I said company, because almost nobody will invest so much money for such a thing. In my case, the request has been to create a structure … Continued

Everyday Git usage

Taking the chance to work in a team environment with different developers, I’ve faced many times a lack of documentation for everyday Git commands, which personally define mandatory to avoid mess. To be clear, these occurring errors have been dictated by a change of OS which I usually work with, from Windows to Mac OS … Continued

New theme from scratch (with free download)!

Even I still wonder where I found the time to code a new website, through I have no free time at all, I finally accomplished to develop a theme also for me from scratch, using the starter theme Sage (ver 9 cames with bootstrap and needs to be cleaned, duh). The whole to-do list planned … Continued