Menu Search
Jump to the content X X
Smashing Conf Barcelona 2016

We use ad-blockers as well, you know. We gotta keep those servers running though. Did you know that we publish useful books and run friendly conferences — crafted for pros like yourself? E.g. upcoming SmashingConf Barcelona, dedicated to smart front-end techniques and design patterns.

An In-Depth Overview Of Living Style Guide Tools

Following the market’s demand for minimalistic and consistent UIs, and the growth in modular web development, we tend to pay more and more attention to documentation and the efficiency of designer–engineer workflow with each project we undertake. Also, since the documentation process is often the weakest spot for modern web teams, we’re constantly looking for the right tools to help us.

Living style guides help front-end developers transform front-end code bases into well-described pattern libraries with the minimum of effort. But to make them really efficient, we need to choose the proper tools — so let’s have a closer look at what our community has to offer.

I’ve arranged the tools by function, highlighting only the most powerful ones worth knowing about. You can find more tools, plus videos, articles and other material about style guides at styleguide.io1.

Before we start, if you are not yet familiar with living style guides, I suggest looking into these resources to get a good grounding in the topic:

In a nutshell, living style guides are designed to aid in building well-organized documentation of front-end codebases. By “living” we mean the documentation remains in constant sync with the actual code.

CSS Documentation Tools Link

The first players in the field are CSS documentation parsing tools. The idea of including descriptions of components in style source code first came from web designers. Combining a creative approach to design style guides with web implementation practices led to the development of KSS5.

Similar to JSDoc6, in KSS, CSS components are described right in the source code as comments.

// A button suitable for giving a star to someone.
//
// :hover             - Subtle hover highlight.
// .star-given        - A highlight indicating.
// .star-given:hover  - Subtle hover highlight.
// .disabled          - Dims the button.
//
// Styleguide 2.1.3.
a.button.star{
  ...
  &.star-given{
    ...
  }
  &.disabled{
    ...
  }
}

KSS allows you to define components by style guide section number and describe their different states. This information is then parsed, generating either a single-page document or a set of static HTML files with rendered examples and code snippets.

Single-page documentation generated by KSS.7
Single-page documentation generated by KSS. (Large preview8)

In other CSS documentation parsing tools, it is also possible to define HTML markup in the comments, whereas KSS only parses the actual CSS selectors and generates simple markup automatically.

Currently, KSS is a documentation solution only, and the parsing tool is not being updated. Although it’s implementations like KSS-node9 are still being improved with custom documentation fields and better templating support.

Alternatives To KSS Link

Since the original KSS, many similar tools have been released to do exactly the same thing. One of the most successful is the SC5 Style Guide Generator4510, which is based on KSS. In addition to encapsulated (using Shadow DOM) rendered component previews, the tool also allows you to edit Sass or LESS styles in the browser. It is also possible to define Angular.js directives or web components as a markup example in CSS comments, which will then be transformed into a fully operational component.

Unfortunately, most CSS documentation tools copy one another’s functionality, without introducing new possibilities (making describing each one somewhat redundant), but available ones include: Sassdown11; StyleDocco12; Kalei Styleguide13 (client-side only); Hologram14; and Styledown15.

One tool, however, is more distinctive. DSS4616 is the only standalone CSS documentation parser that produces JSON for later templating. DSS is based on Node.js with support for all modern preprocessors. Compared to KSS, it is possible to integrate DSS into any other tool or environment, as the original author also did with the DSS Grunt plugin17.

Style Guide Platforms Link

While they are straightforward to implement, CSS documentation parsers are very limited. If you try to describe complex components in CSS, you will end up with bloated and hard to manage styles, containing a lot of copy-and-pasted HTML snippets all over the codebase.

The more duplicated templates and HTML you have, the less living your style guides will be. Without constant syncing between codebase and the pattern library, you may face more problems than if you had no documentation at all.

If you have serious plans for maintaining your own UI components library, it’s better to chose an alternative group of tools I call style guide platforms. Whether they’re static site generators or dynamic environments, style guide platforms provide alternative and scalable solutions for collating your documentation.

Static Style Guide Generators Link

The most basic example of a static front-end style guide generator is Pattern Primer18. It simply concatenates a list of HTML files into a single-page document that you can enhance with brief text descriptions and code examples.

All the other tools I will mention in this section do almost the same thing, but with additional perks on top.

Pattern Lab Link

Pattern Lab19 also concatenates a set of templates into a static style guide website. But on top of that it also provides a set of useful features like navigation, annotation support and smart templating.

Every tool must have a workflow and Pattern Lab does it best, combining structure with an atomic design20 approach. This is an ideal combination for easy prototyping and passing HTML markup to clients or back-end developers. However, you might find that its rigorous stance on technologies and file naming may interfere with your existing codebase and individual requirements.

21
Pattern Lab in action. (Large preview22)

Pattern Lab sets up a _patterns directory with subfolders for each component, following the naming convention. Each folder contains a set of logicless Mustache templates with HTML markup.

Folder structure and Pattern Lab generated navigation.23
Folder structure and Pattern Lab generated navigation. (Large preview24)

Data for templates is defined on a global level, or may be set locally next to the markup itself:

pages/article.mustache
pages/article.json

All that’s left is to link project styles into a generic page template and run the Pattern Lab builder. View the resulting demo page of generated pattern library.

Other Static Site Generators Link

There are a few more tools, following similar. Fabricator25 collates HTML and Markdown files, providing you greater flexibility in structuring component documentation.

Fabricator-compatible folder structure and produced page screenshot.26
Fabricator-compatible folder structure and produced page screenshot. (Large preview27)

Pattern Lab allows you to define template data next to Mustache sources; with Fabricator it is possible to define Markdown files with text descriptions next to the HTML source. Documentation processing is done using a Gulp build task, which also includes live reload for ease of development. Here is an example output28 generated by Fabricator.

LivingStyleGuide Gem Link

Another tool worth mentioning is LivingStyleGuide Gem29, based on Sass and Markdown.

To define markup, you can choose between HTML and Haml. UI elements are described using Markdown with custom syntax for imports and data definition.

@haml
@full-width
***.concept-page***
  ***.concept-page--container***
    %h1***.concept-page--title*** Concept
    ***.concept-page--section***

Here is a list of demo components used as an input to LivingStyleGuide Gem and the resulting single-page doc30.

Since it follows a quite opinionated technology stack, most benefits will be gained only by using a Ruby ecosystem.

Dynamic Style Guide Platforms Link

To get even more flexibility and richer sets of features you can choose dynamic style guide platforms. The difference from the tools mentioned so far is that rather than static websites, they provide full-featured web applications.

At the moment, there are only two good examples of dynamic style guide platforms: Rizzo4931; and SourceJS503432.

Compared to CSS-focused tools, style guide platforms are more engineer-driven, covering the full development and integration processes, not just the HTML markup and web design aspects.

Rizzo Link

Rizzo is a small Ruby application that pulls UI component assets via a special API that the master (main product) application provides. Instead of copying templates and markup into the style guide repository, component sources are pulled there automatically. It is currently the best way to develop truly living style guides that are constantly in sync with the real codebase, thus providing more flexibility than CSS documentation parsers.

Unfortunately, Rizzo is highly opinionated and is not yet suited for easy reuse in other applications. However, I definitely suggest you read more about the ideas behind it33 on the Lonely Planet engineering blog.

SourceJS Link

Compared to Rizzo, SourceJS503432 is a scalable open source solution. The dynamic app environment allows you to configure any custom routing and on-the-fly API-based documentation generation. This provides more freedom for integration with your main application sources than with Rizzo.

Out of the box, SourceJS allows you to use Markdown files and special template pages for describing UI components. With official plugins, it is also possible to use CSS Documentation35 and Jade36-based templates. Choose your preferred syntax or combine everything at once (see examples37).

SourceJS introduction video

The application’s core is highly modular, containing only the most common features and APIs used for developing custom plugins38. The platform is built with Node.js but does not provide any opinion on technologies you might want to integrate, such as different templating languages and CSS preprocessors.

Components-Oriented Link

SourceJS workflow is mostly focused on component libraries organization and supports living style guide-driven development rules. This helps to develop and test components right in the documentation pages.

Such an approach allows you to combine multiple sets of components in one environment, even for different web projects. Simply place the main application next to the SourceJS app and link CSS styles, JavaScript and templates into your documentation pages.

If the project codebase is already focused on standalone UI components, link their folders to the SourceJS spec catalog:

sourcejs/specs/
    menu-component/
        menu.css
        menu.js
        menu.html
        readme.md
        [index.src]

The engine will parse the readme.md file or special index.src template with examples of how the components will render and expose a rich documentation page39. Use this page to list all component states with different data, making it easier to test and share among team members.

Request a consultation session40 with the authors of the SourceJS platform to see how it could be integrated with your codebase, or use GitHub issues and Gitter chat41 to ask questions.

Starter Kits Link

The most common misunderstanding I see in compilations of style guide tools is that starter kits are often mixed in with generators and parsers. They should only really be regarded as boilerplates for your style guide. Here are three such starter kits:

These starter templates could be used in any of the tools I’ve mentioned, as markup examples.

Summing Up Link

The technologies on which these tools are based are rarely important, because in most cases it does not matter if a generator or dynamic server is running on Ruby or Node.js. The things that really matter are the organizational structure, the templating engines used and platform flexibility.

Starting Small Link

For simple CSS frameworks and small web projects, that are not going to require long-term support, I would suggest using SC5 Style Guide Generator4510 or DSS4616. Both of them are really easy to set up and master.

Simple CSS Components Library from Heroku.47
Simple CSS components library from Heroku. (Large preview48)

More Complex Component Libraries Link

If you need to support components more complex than buttons and forms, components that contain several technologies like templates and JavaScript, the best choice will be one of the style guide platforms. Compared to CSS documentation parsers, platforms encourage you to follow style guide-driven development with all its benefits.

This combination will help you maintain really living pattern libraries, keeping your codebase well structured and easy to reuse.

Flexible Solutions For Deep Integration Link

The only efficient and long-lasting way of supporting living style guides is having no code duplication at all. Rizzo4931 and SourceJS503432 allow you to seamlessly integrate your development workflow with the documentation process. Write code once and use it both in the application product and in the style guide with descriptions and representations of different states.

With SourceJS, it is possible to repeat almost all the workflows offered by other tools, but with wider possibilities for custom integration and a powerful plugins infrastructure.

The Future Of Style Guides Link

I am the main contributor to SourceJS and I hope you’ll let me mention a few additional benefits of the engine, and share our team’s vision about the future of style guides.

We believe that style guides must serve as an entry point to any front-end-related workflows for the whole team. Therefore, style guides should be treated more seriously than just regular documentation or brand guidelines.

Using plugins like comments51 or crowd-voice52, teams are able to communicate between different departments within the style guide, leaving their remarks and feedback in the place where components are developed, tested and maintained.

SourceJS plugin for commenting on the rendered UI examples.53
SourceJS plugin for commenting on the rendered UI examples. (Large preview54)

As well as in-place communication, we can combine different development tools in one place; run live reload, linting and testing tools with a single command all together within the style guide platform; integrate performance metrics and provide optimization suggestions right on the documentation page. The possibilities are endless.

We are working on getting further different interactive documentation and various front-end infrastructure dashboards in one place, making an ultimate tool for the web developers.

If you believe in the future of style guides and are willing to support this movement, we will be happy to welcome you to the SourceJS community.

Resources Link

(og)

Footnotes Link

  1. 1 http://styleguides.io/tools.html
  2. 2 http://alistapart.com/article/creating-style-guides
  3. 3 http://24ways.org/2011/front-end-style-guides
  4. 4 https://speakerdeck.com/hagenburger/style-guide-driven-development
  5. 5 http://warpspire.com/kss/
  6. 6 https://github.com/jsdoc3/jsdoc
  7. 7 https://www.smashingmagazine.com/wp-content/uploads/2015/04/styleguide_screenshot-large-preview-opt.jpg
  8. 8 https://www.smashingmagazine.com/wp-content/uploads/2015/04/styleguide_screenshot-large-preview-opt.jpg
  9. 9 http://kss-node.github.io/kss-node/
  10. 10 http://styleguide.sc5.io/
  11. 11 https://github.com/nopr/sassdown/
  12. 12 http://jacobrask.github.io/styledocco/
  13. 13 http://kaleistyleguide.com/
  14. 14 http://trulia.github.io/hologram/
  15. 15 https://github.com/styledown/styledown
  16. 16 https://github.com/darcyclarke/DSS
  17. 17 https://github.com/darcyclarke/grunt-dss
  18. 18 https://github.com/adactio/Pattern-Primer
  19. 19 http://patternlab.io/
  20. 20 http://bradfrost.com/blog/post/atomic-web-design/
  21. 21 https://www.smashingmagazine.com/wp-content/uploads/2015/04/pattern-lab-large-preview-opt.jpg
  22. 22 https://www.smashingmagazine.com/wp-content/uploads/2015/04/pattern-lab-large-preview-opt.jpg
  23. 23 https://www.smashingmagazine.com/wp-content/uploads/2015/04/pattern-lab-files-large-preview-opt.jpg
  24. 24 https://www.smashingmagazine.com/wp-content/uploads/2015/04/pattern-lab-files-large-preview-opt.jpg
  25. 25 http://fbrctr.github.io/
  26. 26 https://www.smashingmagazine.com/wp-content/uploads/2015/04/fabricator-large-preview-opt.jpg
  27. 27 https://www.smashingmagazine.com/wp-content/uploads/2015/04/fabricator-large-preview-opt.jpg
  28. 28 http://fbrctr.github.io/demo/
  29. 29 http://livingstyleguide.org/
  30. 30 http://livingstyleguide.com/eurucamp/
  31. 31 https://github.com/lonelyplanet/rizzo
  32. 32 http://sourcejs.com/
  33. 33 https://github.com/lonelyplanet/rizzo
  34. 34 http://sourcejs.com/
  35. 35 https://github.com/sourcejs/sourcejs-contrib-dss
  36. 36 https://github.com/sourcejs/sourcejs-jade
  37. 37 http://sourcejs.com/specs/
  38. 38 http://sourcejs.com/docs/api/plugins/
  39. 39 http://sourcejs.com/docs/spec/
  40. 40 mailto:r@rhr.me
  41. 41 http://gitter.im/sourcejs/Source
  42. 42 http://bjankord.github.io/Style-Guide-Boilerplate/
  43. 43 http://barebones.paulrobertlloyd.com/
  44. 44 https://developers.google.com/web/starter-kit/
  45. 45 http://styleguide.sc5.io/
  46. 46 https://github.com/darcyclarke/DSS
  47. 47 https://www.smashingmagazine.com/wp-content/uploads/2015/04/small-comp-lib-large-preview-opt.jpg
  48. 48 https://www.smashingmagazine.com/wp-content/uploads/2015/04/small-comp-lib-large-preview-opt.jpg
  49. 49 https://github.com/lonelyplanet/rizzo
  50. 50 http://sourcejs.com/
  51. 51 http://github.com/sourcejs/sourcejs-comments
  52. 52 http://github.com/sourcejs/sourcejs-crowd-voice
  53. 53 https://www.smashingmagazine.com/wp-content/uploads/2015/04/sourcejs-commnets-large-preview-opt.jpg
  54. 54 https://www.smashingmagazine.com/wp-content/uploads/2015/04/sourcejs-commnets-large-preview-opt.jpg
  55. 55 http://styleguides.io/
  56. 56 https://github.com/davidhund/styleguide-generators
SmashingConf Barcelona 2016

Hold on, Tiger! Thank you for reading the article. Did you know that we also publish printed books and run friendly conferences – crafted for pros like you? Like SmashingConf Barcelona, on October 25–26, with smart design patterns and front-end techniques.

↑ Back to top Tweet itShare on Facebook

Advertisement

Passionate Front-end developer, evangelist and automation geek. Loves to speak about technologies and build cool things for the web community. Previously worked as a Head of Front-end at top 10 world social network and now is a Senior Front-end Consultant at Backbase.
Creator of SourceJS Style Guide Platform, DevShelf.us articles hub and MCSS methodology.

  1. 1

    We use Trulia’s Hologram gem (https://github.com/trulia/hologram) at CoachUp and love it. We’ve got a live demo as well: https://www.coachup.com/style/

    I like that it’s a bit more customizable and self-documents the CSS via comments.

    Did you guys like the LivingStyleGuide gem? Does it help in documenting the CSS?

    0
    • 2

      It is hard to take this article seriously when two of the key points made against kss are not true.

      1. Kss has a version that works with node (and grunt): kss-node
      2. Kss parses inline HTML templates, external HTML files or even external handlebar templates

      When these two facts have been overlooked for KSS it makes me wonder about the quality of analysis of the other solutions.

      1
      • 3

        Hi Al,

        Thanks for highlighting the right points. It’s true that I didn’t mentioned all of KSS based tools, and Node.js version supports inline HTML as well as SC5 Style Guide. There are also KSS ports in PHP, Python and Java, but still, they provide not that much features as mentioned SC5 solution.

        Official thoughts from KSS author about inlining markup in CSS https://github.com/kneath/kss/pull/97#issuecomment-40745312.

        I was pointing only on the original version, which states itself as “Documentation for any flavor of CSS that you’ll love to write.” and “KSS is a documenting syntax for CSS” http://warpspire.com/kss/

        It is possible to combine KSS parser with external templates, but it is not an out of the box solution. You may use parser API to develop your own Style Guide systems, which is close to writing your own tool with DSS for example.

        6
        • 4

          I think it would have been better if there was an inclusion of the possibilities of using KSS notation with kss-node or other alternatives that can directly answer the points you make.

          KSS-node also addresses the points made in the referenced “official thoughts” made in April 2014.

          KSS-node is an out of the box solution that functions with templates and requires no parser API and it is shame that your article creates a negative impression about KSS and doesn’t highlight any of this for a balanced point of view.

          This would also be useful to people who already have CSS, SASS or LESS files with KSS comments that could continue to be used.

          1
          • 5

            Thanks again for the feedback, It will be definitely useful to other readers. I’ve added KSS-node mention to the article as well.

            For those who already use KSS, I recommend taking in mind SC5 Style Guide; which is totally compatible with KSS and goes further with new possibilities.

            I can’t describe each CSS Documentation parsing tool, since most of their features are redundant. That is why initially only the original KSS and the best alternative (imho) were highlighted.

            1
  2. 6

    Marco Solazzi

    April 14, 2015 8:27 am

    Great article! Living style guides are a hot topic lately.

    Another tool I’m currently using in my workflow is a Grunt plugin called Sassdown (https://github.com/nopr/sassdown). It uses markdown and a custom parser to implement a living styleguide.

    What i really like is that it doesn’t force you to its own syntax making it the right tool if you already use Sass/Scss and have your own coding guidelines fir styles / comments etc

    2
  3. 8

    I’ve taken a slightly different approach to the living style guide.

    For me, the number of objective of a living style guide is that it should tell the truth. If the css changes, so must the style guide – full stop. My day time job is working with a large CMS-like system.

    None of the existing style guide approaches didn’t really work for us, so what I did (of course…) was to create a new way of dealing with style guides. It works like this:

    1) Developer creates documentation by commenting the scss/less/css/whatever.
    2) The style guide generator searches all style files and generates a single html document from those comments.
    3) As part of the build process, that HTML document is then read and uploaded as an _article_ to the CMS. Of course that article is only visible for developers. As the HTML document does only contain markup (html) and not any css, the element gets their look and feel from the *actual* css currently being in use on the site. It always tells the truth.

    If interested, I’ve made the generator open source: https://www.npmjs.com/package/markdown-styleguide-generator

    3
    • 9

      It is *highly* inspired by https://github.com/nopr/sassdown main difference is that this tool creates a single html file – ready to be uploaded to the site, where sassdown creates multiple files.

      0
      • 10

        That’s a really interesting use case! Would love to develop something similar as a stand-alone module for SourceJS, to upload the contents of Spec to different sources.

        But one thing though, don’t you want to collaborate with other tools more, instead of creating a new one? Improving sassdown, and making it more modular and flexible will provide bigger impact for the community, and yourself in the future.

        5
        • 11

          Sure I do! If you take a look at my Github page you’ll see that my last pull request to another repo was made yesterday.

          The markdown-styleguide-generator was created out of a need we had in house, and to be honest it was easier to hack it together in an hour or two.

          That being said; in hindsight, it could probably have been made just as quick building on sassdown. I’d love to implement the functionality in sassdown and deprecate it. But you know, so much to do, so little time and this is somewhere in on the lower half of my wish/todo list.

          1
  4. 12

    Great Article Robert!

    Check out our gem for rails apps! It’s a component library/living styleguide generator inspired by Rizzo.

    Sadly we are late to your article haha :( https://github.com/jgnatch/mountain_view

    2
    • 13

      Matt Hinchliffe

      August 31, 2015 9:52 am

      Ex-LP dev here – love what you’ve done with Mountain View, I actually recommended it to somebody the other day who was asking about Rizzo =)

      1
  5. 14

    super useful thanks.
    And speaking of “the market’s demand for minimalistic and consistent UIs..”

    You will find this a very good read:
    http://www.elischiff.com/blog/2015/4/7/fall-of-the-designer-part-i-fashionable-nonsense

    0
  6. 15

    Tom Dell'Aringa

    May 6, 2015 7:42 pm

    I’ve seen a lot about living style guides, and they are all focused on web/responsive design solutions. But what about native apps – iOS and Android.

    When a UX team has to provide the typical wires/visuals/spec/content matrix it can get very messy. Some kind of living style guide would be great – but few UX people are versed in xcode, etc.

    Especially with Agile teams where oftentimes the development group is offshore, a living document would be fantastic.

    1
  7. 16

    Thanks for share this information. Very nice post!!

    Offices for Rent in Kings Cross | Mitdown Bars

    -2
  8. 17

    I love this idea, and I tried using the Styleguide Boilerplate for a recent website being built in Drupal.

    This doesn’t work so well if all members of a team are not on board with having a central living style guide. Just for example, I could develop a typographic system using standard html heading elements, but the markup generated in Drupal doesn’t use html headings. And the styleguide/pattern library resides in a separate place on the server from the Drupal project and is not incorporated into the developer’s IDE at all.

    So, I wonder, is there value in using one of these things if just the designer is going to use it?

    1

↑ Back to top