A generated styleguide catalogue has many advantages in every day project live (see below), but as most of the available tools did not suite my needs (difficult to set up, too much tool dependencies, bugs, ...) I created my own solution: style-code.

How a generated styleguide will help developing web project teams

It is quote common in web projects, even in bigger ones, that the "Layout" people are responsible for all appeareance topics. Most of the times this is leading to a kind of "PDD": Photoshop Driven Development. Especially (but not only) in these projects it is important to create a kind of "Layout component catalogue".

This won't solve the usability issues (Layout is not usability, as we know), but, if established as part of the layout development, encourages designers and frontend developers (those defining the styles technically, in CSS or any preprocessored technology like SASS, LESS, ...) to think in independent components.

The resulting creation of an inventory of layout definitions (definition of standard font sizes, appearance of links, paragraphs, buttons) or components (visual elements containing more atomic elements, for example teasers, menus, ...) has several advantages:

• Overview over all used styles ("Do we really need 4 different link styles? And 6 different font sizes with 10 different line-height definitions? And, if yes, why?")
• Explaining all the styles and naming them forces designers to think about the reason why this style is needed and should be applied in which cases.
• Consolidation of styles
• CSS style definitions will be more independent as they are designed for each component (avoidance of definitions like .main .right-content .marginal-element:first-child .header {...}).
• First acceptance of visual elements won't depend on a working system, feedback from the designers will (hopefully) focus just on this element, and not on any bug or feature request elsewhere on the site (this might sound strange, but will save a lot of time, according my experiences)
• Reuse of already defined components, technically, which leads to cleaner style definitions

Why style-code?

There are some tools out there to generate styleguides, like StyleDocco,
documentCSS, KSS Stylesheets or Devbridge's Styleguide.

No prerequisites (except java)

All of them do have one requirement in common: The need of (at least) npm, others need even more installed tools, like Ruby, Ruby DevKit. That makes it quite difficult to integrate the styleguide generation into an highly automated and platform independent environment (=> java world). Did you try to run e.g. documentCss from a Jenkins, without needing root access to the underlying operating system?

A lot of the npm tasks can be automated, for example with the maven-frontend-plugin. This works fine until the npm task you use needs a locally installed Ruby. StyleDocco, for example, works, but has bugs with background graphics (the frames used there are no real iframes, but javascript generated iframes, where Firefox is not able to resolve the resource URLs of the graphics).

style-code needs just java.

Separation from productive CSS code

Most of the existing tools are aiming to document the existing CSS code with examples, similar to JavaDoc. That is not what I want in my styleguide. The styleguide should be a separate document, an implementation reference showing how the elements should look like (in any browser, real HTML/CSS/JS) including implementation examples.

At the same time it needs to work with the productive resource files (CSS, JavaScript, Fonts), to be able to develop, test and find regressions without depending on the running system.

The documentation made with style-code is not embedded in any CSS files, it is a separate markdown file, which will be enhanced by iframes and live editing support by some injected JavaScript.

style-code gradle plugin and demo project

There is a demo project using the Gradle plugin to show how a styleguide project can be set up.

There are various possibilities, I am still working on the demo project and will add some more demo projects as well to create showcases for different use cases.