index.md 27KB
title: Living Style Guide Tools In-depth Overview
url: https://medium.com/@operatino/living-style-guide-tools-in-depth-overview-28cfffb92d05
hash_url: ff9dd5355d
Intro
This overview is the outcome of a research on the current open source solutions followed by my personal feedback.
Arranging the tools by functional aspects, I will highlight only the most powerful ones worth knowing. You can find more tools as well as videos, articles and other materials about Style Guides at styleguide.io.
Before we start, if you are not yet familiar with Living Style Guides topic, I would suggest looking into these materials:
In a nutshell, Living Style Guides are designed to aid building well-organized documentation of Front-end codebase. The “Living” part of it, means that documentation remains in constant sync with the actual code.
CSS Documentation
The first players in the field are CSS Documentation parsing tools. The idea of combining description of components with styles source code first came from Web Designers. Combining creative approach and Design Style Guides success with web implementation practices has led to KSS development.
As you most probably have heard about it, I will quickly recap on the main idea behind it. Similar with JSDoc, CSS component description is set right in the source code 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 to define component section number and different states description. Which is then parsed by special tools, generating a single-page documentation or a set of static HTML files with rendered examples and code snippets.
In similar CSS Doc parsing tools, it is also possible to define the HTML markup in comments, when KSS only parses the actual CSS selectors and generates simple markup automatically.
Currently KSS is positioned as a documentation solution only, and the parsing tool is not getting new updates.
KSS alternatives
Since the original KSS, many similar tools have been presented to do exactly the same thing. One of the most successful implementations is SC5 Style Guide. In addition to encapsulated (using Shadow DOM) rendered component previews the tool also allows to edit SASS or LESS styles right in the browser. It is also possible to define Angular directives or Web components as a markup example in CSS comments, which will then be transformed into a fully operational component.
Unfortunately, most of the CSS Documentation tools are somewhat copying each other, without introducing any new possibilities. That is the reason why it is not worth to describe each tool separately, so I will just list the ones you can find out there — StyleDocco, Kalei Styleguide (client-side only), Hologram and Styledown.
Yet there is a tool with distinction. DSS is the only standalone CSS documentation parser, that produces JSON for later templating. Based on Node.js with support of all modern pre-processors. Comparing to KSS, it is possible to integrate DSS into any other tools and environments, as the original author also did with Grunt plugin.
Style Guide Platforms
The problem with CSS Documentation parsers is that they are very limited, nevertheless they are the easiest to implement. Trying to describe more complex components in CSS, you will end up with bloated and hard to manage styles, containing tons of copy-pasted HTML snippets all over the codebase.
The more of duplicated templates and HTML markup you have, the less Living are your Style Guides. Without constant sync between codebase and the pattern library, you may face more problems than with having no documentation at all.
Having big plans for maintaining own UI components library, it’s better to chose an alternative group of tools called Style Guide Platforms. Using both static-site generators and running dynamic environments, they provide more alternative and scalable solutions for collecting your documentation.
Static Style Guide Generators
Most basic example of static Front-end Style Guide generator is Pattern Primer. All it does is concatenating a list of HTML files into the one-page documentation, which you can enhance with a small text description and code examples.
The reason I started with it is that all the other tools I will mention in this section are doing almost the same thing, but with separate additional perks on top.
Pattern Lab
Pattern Lab is another tool for concatenating a set of templates into a static website. But on top of that it is also providing 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 opinionated structure with Atomic design approach. This is an ideal combination for easy prototyping and passing HTML markup to client or back-end developers. Yet the opinion on technologies and file naming may interfere with existing codebase and special needs.
As an input to Pattern Lab static-site generator, user should prepare a _patterns catalog with folders for each component, following the naming convention. Each folder therefore contains a set of Mustache templates with HTML markup.
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
Then all is 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 generators
There are a few more tools, following same site-generator principles. Fabricator is gathering HTML and Markdown files, providing you better flexibility on structuring components documentation.
As the Pattern Lab allows to define template data next to Mustache sources, with Fabricator it is possible to define Markdown file with text description next to the HTML source.
Documentation processing is done by using Gulp build task, which also includes Live reload for ease of development. Here is an example output generated by Fabricator.
Living Style Guide Gem
Another tool worth mentioning is Living Style Guide Gem, based on SASS and Markdown.
To define markup, you can choose between HTML and HAML. UI elements are described by 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 Living Style Guide generator and the resulting single page doc.
Since it follows quite opinionated technology stack, most benefits will be revealed only by utilizing Ruby ecosystem.
Dynamic Style Guide Platforms
To get even more flexibility and richer set of features you can choose Dynamic Style Guide Platform. The difference from all other tools mentioned above is the fact that it does not produce static website sources, but instead provides a full-featured web application.
For the time being, there are only two good examples of dynamic Style Guide Platforms — Rizzo and SourceJS.
Comparing to CSS focused tools, Style Guide Platforms are more engineer-driven, covering full development and integration process, not only the HTML markup and web design aspects.
Rizzo
Rizzo is a small Ruby application, that pulls UI component assets via special API that 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 re-use in other applications, but I definitely suggest you reading more about ideas behind it on Lonely Planet engineering blog.
SourceJS
Compared to Rizzo, SourceJS is a scalable open source solution. The dynamic app environment allows to configure any custom routing and on the fly API based documentation page generation. Giving more freedom for integration with your main application sources like it’s done in Rizzo.
Out of the box, SourceJS allows to use Markdown files and special template pages for describing UI components. With official plugins, it is also possible to use CSS Documentation and Jade based templates. Chose preferred syntax or combine everything at once (see examples).
Core of the application is highly modular, containing only the most common features and API’s used for developing custom plugins. Platform is built with Node.js but does not provide any opinion on technologies you might want to integrate, like different templating languages and CSS pre-processors.
Components Oriented
SourceJS workflow is mostly focused on component libraries organization and is supporting Living Style Guide driven development rules. That helps to develop and test components right in the documentation pages.
This approach allows to combine multiple sets of components in one environment, even for different web projects. Simply put the main application next to SourceJS app and link CSS styles, JS and templates into documentation pages.
If project codebase is already focused on standalone UI components, link their folders to SourceJS spec catalog:
sourcejs/specs/
menu-component/
menu.css
menu.js
menu.html
readme.md
[index.src]
Engine will parse the readme.md file or special index.src template with component representation examples and expose rich documentation page. Use this page to list all component states with different data, making it easier to test and share among team members.
Request a consultation session with the authors of the SourceJS platform to see how it could be integrated with your codebase. Or use GitHub issues and Gitter chat for questions.
Starter Kits
Most common misunderstanding I see around Style Guide tool compilations is that Starter kits are mixed together with generators and parsers. Treat them only as HTML5 boilerplate for upcoming Style Guide:
These starter templates could be used in any of mentioned tools, as a markup examples.
Summing up
If you find it hard to choose the right tool, let me help solving this question by summing up the main concerns.
I won’t focus on technologies on which these tools are based, because in most cases it does not matter if a generator or dynamic server is running on Ruby or Node.js. The thing that really matters is the organizational structure, used templating engines and platform flexibility.
Starting from small
For simple CSS Frameworks and small web projects, that are not planned for long-time support, I would suggest using SC5 Style Guide or DSS. Both of them are really easy to set up and master.
For more complex component libraries
If you need to support components more complex than buttons and forms, containing many technologies like templates and JavaScript, the best choice will be the Style Guide Platforms. Comparing to CSS Documentation, Platforms allow following Style Guide Driven Development with all it’s benefits.
This combination will help you maintain a really Living pattern libraries, keeping codebase well structured and easy to reuse.
Flexible solutions, for deep integration
The only efficient and long-lasting way of supporting Living Style Guides is having no code duplication at all. Rizzo and SourceJS approach allows to seamlessly integrate development workflow with the documentation process. Write code once and use it both in the product application and in the Style Guide with descriptions and different states representation.
With SourceJS, it is possible to repeat almost all the workflows that other tools are offering, but with wider possibilities for custom integration and powerful plugins infrastructure.
The future of Style Guides
Since I am the main contributor to SourceJS, I will let myself mention few additional benefits of the engine, sharing our team’s vision about Style Guides future.
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 a regular documentation or a brand guideline.
Using plugins like comments or crowd-voice, 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.
Apart from 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 withing the Style Guide Platform. Integrate performance metrics results and provide optimization suggestions right on the documentation page. The possibilities are endless.
We are working on getting more different interactive documentation and various front-end infrastructure dashboards in one place, making an ultimate tool for the web developers.
If you also believe in the future of Style Guides and are willing to support this movement, we will be happy to see you in SourceJS community.
Further Research
- Element CSS — interesting approach of hosted service with on the fly Style Guide creation
- Patternry — a service for storing and organizing Front-end Style Guides online
- styleguides.io — a collection of tools, articles and other materials on the Style Guides
- An overview of Pattern Library Generators
And here is the video of my latest talk on the corresponding topic: