Style guide – what it is and why it is worth using?


Kuba Bergel
Front-end Team Leader
Kuba Bergel
Frontend developer with strong skills in translating UI into CSS magic. After work becomes an actor, script writer and graphic designer.

Style guide – what it is? In definition, style guides are “a set of standards for writing and designing documents, either for general use or for a specific publication, organization, or field”. But how it corresponds with web design?

Imagine the perfect IT world, where the UX team produces views, which are pixel perfect implemented in web site with no problems. Obviously this kind of approach is more idyll, than real life.
And here comes the style guide help! It fulfils the gap between designers and developers. As a front-end developer my role is to prepare project’s style guide, which contain components with proper documentation and code snippets, just ready to implement them on web site. It cuts a lot of problems and makes development as easy as LEGO Bricks ®!

On Internet, you can find at least few style guide generators which are worth mention, like Styleguide.js or Hologram. But the one I chose is Nucleus prepared by PirateTechnologies. This generator gives nice and intuitive UI with good documentation. It also deals great with BEM methodology, which is widely used in our company.


Style guide – what it is?

Usage if this tool is quite simple: all you have to do is to define proper documentation in commentary in your style files. Nucleus crawls through all .scss files in order to find those documentations and then it builds a style guide page. In style guide we can find four tabs, which divide the guide in sections: “Nuclides”, “Atoms”, “Molecules, “Structures”.

First one represents the most basic info, like colour definitions (with variables that fits those colours), mixins and functions usage. Second tab is “Atoms”, which shows the most principle elements, like headers, buttons, links, text formatting. “Molecules” can be treated like components and they can consist of atoms. An example of molecule is definitely a navigation. Both atoms and molecules should be independent and could be used wherever along the site. “Structures” are most complex ones and they can consist of molecules and even other structures, like “header” or “footer”. But how Nucleus knows, wether a class is an atom, molecule or structure? It’s quite simple, all you have to do is to add @atom, @molecule or @structure at the beginning of Nucleus commentary.

In that same commentary you adds a code snippet, which drives the display of the element. Then that snippet is injected in HTML and boom! – you can see your atom, molecule or structure in style guide! Snippet can be easily copied by only one click and then pasted in final web site.

So, the development then is much like using already prepared small pieces of code – it’s clean and fast. Also the classes usage, modifiers – it’s all described in documentation prepared for particular element, so developer knows what can or cannot be done with it. Besides, by style guide, styles can be easily tested in various browsers and devices, even before beginning of web site development itself!


Style guide – why it is worth using?

But of course, the tool isn’t perfect. It doesn’t have well working support for external JS libraries, like Angular. If you want to have working angular components, you have to tweak a templating .pug files a little bit. But after this minor tweaks, everything works fine!
In my opinion style guide should be a part of every project. It makes development much easier and much faster! Creating web sites from predefined elements is elegant and clean. Consider using it in your project too, you won’t regret it.