We will look at what a living style guide is, why you want one, and some tools to help you get there
What
Living style guides have popping into the Trial ring of the Thoughtworks Radar. One of the best examples of a living style guide is the excellent Twitter Bootstrap documentation.
Thoughtworks have the following to say about living style guides:
A living CSS style guide is a page on your site that uses your current CSS styles and acts as a reference for all the currently available visual elements and design patterns. This helps to tightly integrate design into your delivery process by promoting co-ownership of the UI and avoids duplication of styling across your application. Styling changes are visible in the guide immediately and changes propagate across your site from a central location. A sensible way to do this is with a well organized SASS/LESS file structure with semantically named elements that separates structure, aesthetics, and interaction.
Thoughtworks Tech Radar - living css style guides
How
There exist a number tools for building a live css style guide:
I used Hologram for the following reasons:
...
Setup
Setup was surprisingly easy:
gem install hologram
hologram init
Edit the values in the hologram_config.yml file that is created. Run:
hologram
To create your docs.
Automation with grunt
Automation with grunt is pretty easy. See: grunt-hologram
Automation with jenkins
Assuming you've got ruby setup and the hologram gem installed on your CI server, you can quite easily build the docs with something like:
cd static && hologram
(where static is the directory containing our hologram_config.yml file.
This builds our docs. We can now publish these on jenkins too:
- Install the HTML Publisher plugin
- Add a post build step to publish the docs generated by hologram to Jenkins
- Profit