I recently came across a book called CSS Mastery by Andy Budd, Cameron Moll and Simon Collinson. The book introduced me to a couple of new ideas with respect to CSS style sheets.
In recent years, there have been various projects to standardise CSS comments and to extract documentation from these comments.
Cssdoc started out as a CSS commenting convention to help people improve the writing and managing of CSS files.
Inspired by cssdoc, Thomas Kadauke created a Ruby library and command line tool called css_doc. This tool can be used to extract documentation from css files.
The book also discusses the concept of a style guide. A style guide consists of one or more documents or web pages that explain how the code and layout of a site is put together.
Upon further investigation, I discovered that there are now several tools that allow the automatic generation of a style guide from specially formated CSS comments.
Knyle Style Sheets (KSS) is a documentation specification and styleguide format with a ruby library capable of parsing SASS, SCSS and CSS documented using these guidelines.
However, in his talk “Improving your responsive workflow with style guides“, Luke Brooker recommends StyleDocco and KALEI StyleGuide over KSS for the creation of rapid style guides.
StyleDocco is a node package that generates documentation and style guide documents from your stylesheets. Stylesheet comments are parsed through Markdown and displayed in an HTML document. You can write HTML code prefixed with 4 spaces and StyleDocco will create a preview with the styles applied. The CSS markup is also helpfully displayed next to the documentation.
KALEI StyleGuide is another tool that apparently does much the same thing but with the advantage that it does not require a build step. Instead, documentation is generated on the fly using JavaScript. Unlike StyleDocco, it does not display the css markup next to the documentation.
I have started taking a look at StyleDocco. It looks very promising. I also plan to take a look at KALEI StyleGuide and write a blog post about each of them.
ClareWall.org 
I think I’ve been guilty of a certain kind of conceit in the past — presuming that CSS is a ‘toy’ language: a simple, straightforward set of constructions that should be simple to understand. And I suppose that’s been said often enough with JavaScript, but with JS it’s more obvious that it’s a general-purpose language and worthy of more respect.
But CSS is different: although the language is fairly simple, real-world stylesheets are really complex. I worked on a project recently where the CSS was doing some really heavy lifting — responsive layout, positioning shared elements like navbars, and styling page-specific elements.
So all of this makes for a complex environment. CSS deserves a bit more tooling and testing. As developers, are we short-changing designers? I’m looking forward to seeing what these CSS tools can do.
Look forward to the write up on Kalei! Because the community has started to take interest in the project, I’m going to begin some active development on it.