How To Create a Living Style Guide

January 10, 2018

Using a living style guide (LSG) to drive development is a practice that is gaining a lot of popularity because it has many advantages, including code efficiency and UI consistency. But, how can you create one? What should you include? And where do you even start? In this tutorial I will delve into the nitty-gritty details of creating a living style using DocumentCSS.

The Beauty of Living Style Guides

Similar to a standard style guide, a living style guide provides a set of standards for the use and creation of styles for an application. In the case of a standard style guide, the purpose is to maintain brand cohesiveness and prevent the misuse of graphics and design elements. In the same way LSGs are used to maintain consistency in an application and to guide their implementation. But what makes a LSG different and more powerful is that much of its information comes right from the source code, making it easy and efficient to reflect the evolving state of an application. 1-giphy-kramer Even today it’s mind blowing to learn that you can use the source code of your application for building your style guide. If you look at the examples below you will see the common denominators of a LSG are:

A list of the elements that are documented
Succinct documentation with code snippets and interactive UI demonstrations

Lonely Planet Style Guide 3-example-sales-force

Sales Force Style Guide

Another key element of a LSG is that you can use a style guide generator to automate the process. A style guide generator will use your application source code to feed the bulk of your LSG documentation and watch for any changes made in your code, taking care of updating your style guide documentation as your application changes.

Style Guide Generators

There are many flavors to choose from, depending on the code language that you want to document or your project setup. Here are some places to look for options:

An In-Depth Overview of Living Style Guide Tools, Robert Haritonov, Smashing Magazine
Overview of Pattern Library Generators, David Hund, GitHub
Style Guide Generator Roundup, Susan Robertson, A List Apart
Style Guide Tools, Website Style Guide Resources

For this tutorial I will be showing you how you can use DocumentCSS to create your LSG. This tool created by Bitovi is open source and can be used in any project to document CSS (preprocessors like Less and SASS are supported as well). If you are interested in documenting Javascript and other languages, you can easily do it with DocumentCSS, as this tool is a subset of DocumentJS. I won’t be covering that part in this tutorial, but it’s good to keep in mind.

Planning Your Style Guide

Before diving into creating your LSG the first step is planning what will be in it. Like any good website, a well structured Information Architecture (IE) is the key. So let’s get started by using the following set of designs of our sample app called “Vintage Shop” and observe the persistent elements in the UI: 5-vintage-shop-mockups Vintage Shop Mockups At this point I recommend starting with larger groups of elements, such as the navigation, the cart or the forms. For example, we’ll separate our design into these three groups: the steps indicator, the mini cart, and the products in the cart: 6-vintage-shop-elements With these larger groups of elements, you can start going into more detail and identify the “styles” that persist. For example, there is a convention for the typography in general, and more specifically for the headings, the subheadings, and the links vs. regular text. The color of the buttons also persists across the pages. 7-vintage-shop-styles Putting it all together, let’s write down these groups using a diagram: 8-diagram-style-guide-1 Taking a deeper look into these groups you can fine tune them and turn them into categories that you can use in your style guide as it grows. For example:

“Elements” is a very vague term that could refer to any HTML element, so a better name for this group could be “Components” or “Modules. These are still broad terms but are more specific in the nature of the type of elements that would cover.
“Primary vs Secondary” buttons could be part of “Base Elements”, and the color aspect of it could go inside of a “Color Palette” category.

Additionally, you can think about a category where you can include more generic information about your style guide. A good example of that would be a “Guides” section where you could describe how to contribute to the style guide or a “Branding” section where you can include guidelines about your brand that should be kept in mind when designing and implementing your app. With this in mind, here’s what the diagram would look like: 9-diagram-style-guide-2 You can see how this diagram takes the shape of a site map, which is basically what you want to use as a plan when creating your living style guide. Now, dive into the designs and sketch up your own site map, including as many categories as you think would be useful for the future. You can get ideas from other style guides (styleguides.io/examples is a great resource). Once you are done, check this more comprehensive version and compare.

Creating Pages in a Living Style Guide

While the bulk of your LSG documentation will come from special comments that you add to the source code, you can also create standalone pages where you can host other types of content that are not specific to the code (think of design principles, accessibility guidelines, or pull request guidelines). This gives you the advantage of centralizing your documentation in one place: your application living style guide.

You could almost think of the living style guide as the “game rules” of your app. Inside of “the rules” is all the information that is needed on how to “play” the game: The building blocks and the rules for creating and making building new blocks. Including how other members of your team can contribute to it and help maintaining it as a living document. 1-giphy _{Yas! Believe it. You can have all of your docs consolidated in one single place!} With this in mind, let’s get started by installing the sample application that we will use for this tutorial.

Installing the Sample Application

The installation process has 3 steps:

1. Installing Node

First, make sure you have Node installed. You will need at least version 6.

2. Installing the App

Then, download this zip file: sgdd-tutorial.zip to your Desktop and unzip it. This is important as another location would break the install commands. Then open the terminal and enter the following command:

cd ~/Desktop/vintage-shop-sgdd-tutorial && npm install

It will take a few seconds to install the app and its dependencies.

3. Running the App

Once the installation is done enter the following commands:

npm run develop
In a new tab enter: npm run document

Now, let’s break this down:

npm run develop

Starts a server where you can see your app running at: http://localhost:8080. You will see in the terminal: 2-terminal-server-running

And in the browser: 3-app-home

npm run document

Generates the living style guide at http://localhost:8080/styleguide. You can add the flag -- -w to this command to watch for changes in your code and then generate an update in the living style guide, like this:

npm run document -- -w

Switching to the browser you should see: 4-style-guide-welcome

The generated living style guide uses DocumentCSS, so let’s take a look at how does this work.

How does DocumentCSS Work?

DocumentCSS is a static site generator. This means it looks for specially formatted comments in your code and creates a static website. This site is called “static” because it remains unchanged until a command (in this case documentjs) is run again. This workflow works well for generating a living style guide as changes to your stylesheets are also changes to the Living Style Guide static site. To build a living style guide, DocumentCSS does the following:

Reads through files specified in its configuration (for this tutorial it will be looking at .less and .md files)
Looks for comments that uses special “tags” (like @page, @stylesheet or @styles.
Generates html files and connects them to build the site.

With this in mind let’s jump into using DocumentCSS to create a new page in the LSG.

Creating a Page

To begin, first open the sample application in your code editor. You should see the following file structure: 7-project-contents

Drill down into src , and find base/markdown. Here you will find pages that already exist in the style guide. Create a new markdown file and name it “about” (with the extension .md). Your file structure should now look like this: 8-project-contents-about

Inside of this new file, add the tag @page followed by two strings:

@page about about

Now let’s break this down:

@page

The tag @page declares the file as a page and tells DocumentCSS that the information in this file should be displayed as a page in the style guide. This serves to differentiate it from stylesheets, javascript, or other types of files in your documentation.

about

This is the unique name for the page and is used as a reference to other tags. So keep it short, lowercase and simple as it will be used as the url for the page. For our example, the url for our new page will be: http://localhost:8080/styleguide/about.html

About

This is the title of the page that will be used for display purposes in the generated site. Here you can use multiple words with spaces or other characters. To view the newly created page run documentjs in the terminal again (unless you have it watching for changes), and then go to http://localhost:8080/styleguide/about.html to view the new page. 9-style-guide-about-1

The next step is to add your page to the navigation. For this add a second line to your file as follows:

@page about About@parent index

The tag @parent allows to specify a parent for your document. In this case we want the “About” page to show under the home section. Now, you can rerun the docs and see the page appear below the “Welcome” link: 10-style-guide-about-2

And if you click on the “Welcome” link, you can access the start page: 11-style-guide-about-3

Now we are good to add content to this page using markdown or html. To finish the exercise, let’s add the following dummy content:

@page about About
@parent index
## Hello World!
This is the first page of my style guide. Here I can add any type of content that shouldn’t live with the code. Like who are the main contributors of the style guide or contact info.
For example here's an animated gif inside of an `iframe`:
<iframe class="giphy-embed" src="https://giphy.com/embed/3o7TKMt1VVNkHV2PaE" width="480" height="480" frameborder="0" allowfullscreen="allowfullscreen"></iframe>

And here’s the output: 12-style-guide-about-4

Documenting a Stylesheet in a Living Style Guide

The heart of creating a LSG is the ability to put your documentation right where it belongs: in the source code. Chances are that you are already documenting your code, which is a great opportunity to take it to the next level by using a style guide generator that can turn those comments into an organized site, letting others (and yourself from the future) know why and what has been done in the code. 1-giphy-back-to-the-future

Yourself from the future after reading the docs you wrote in the past.

Documenting a Stylesheet

Documenting a stylesheet follows a similar pattern to documenting a page, but in this case the documentation will go inside of a comment, right next to the code (that’s the beauty!). To get started open the stylesheet: buttons-custom.less. 2-buttons-custom

Inside of this file, and inside of a comment block, add the tag @stylesheet followed by two strings:

/**
@stylesheet buttons.less Buttons
*/

Note that the documentation comment needs to start with /** for the parser (in this case JSDoc) to recognized it. Now let’s break this down:

@stylesheet

The tag @stylesheet declares the file as a stylesheet and tells DocumentCSS that the information in this file should be displayed a such in the style guide. This serves to differentiate it from other types of documents, like pages, components, and models, among others (read here about the full list of document types).

buttons.less

This is the unique name for the stylesheet and is used as a reference to other tags. While you can use any type of name, I recommend using the name of the stylesheet file, as this will help finding the file when referencing the documentation. Do keep in mind that this will affect the url of your document. For this example the url will be: http://localhost:8080/styleguide/buttons.less.html

Buttons

Similar to creating a page, this is the title of the stylesheet that will be used for display purposes in the generated site. Here you can use multiple words with spaces or other characters. To view the newly created page run the following command unless you have it watching for changes):

documentjs

And then go to http://localhost:8080/styleguide/buttons.less.html to view the new page. 3-style-guide-buttons-1 Now, let’s add this new doc to our navigation. For this we will follow the same convention we used when we created the page by using the @parent tag:

/**
 * @stylesheet buttons.less Buttons
 * @parent styles.base
 */

Note that in this case we have added .base to specify this page should appear under the group “Baseline” shown in the sidebar (you can also create groups in your subnav! We will dig into that in a little bit). Re-running the docs and refreshing the page should look like this: 4-style-guide-buttons-2 Now for the meaty part! With our page in place we can do a few things:

We can add an overall description for the doc
We can add all sorts of content using both markdown or plain HTML
And best of all, we can add demos for our code ?

Let’s add a quick description and a demo for our buttons doc:

/**
 * @stylesheet buttons.less Buttons
 * @parent styles.base
 * @description
 * Global style definitions for all button elements.
 * @iframe src/base/bootstrap-custom/buttons/buttons-custom.html
 */

Rerun the docs, and ?: 5-style-guide-buttons-3

As you can see the @iframe tag allows to add an iframe with a demo to your doc. This demo is really just a simple html file with a script tag that imports the CSS of your app at run time. Let’s open the demo buttons-custom.html : 6-buttons-demo And see how the code looks like:

<script src="/node_modules/steal/steal.js" main="can/view/autorender/">
<import "vintage-shop/styles.less";
</script> <a class="btn btn-default" href="#" role="button">Link</a><button class="btn btn-default" type="submit">Button</button>
<input class="btn btn-default" type="button" value="Input">
<input class="btn btn-default" type="submit" value="Submit">
<hr />
<button type="button" class="btn btn-default">Default</button>
<button type="button" class="btn btn-primary btn-checkout">Primary</button>
<button type="button" class="btn btn-success">Success</button>
<button type="button" class="btn btn-info">Info</button>
<button type="button" class="btn btn-warning">Warning</button>
<button type="button" class="btn btn-danger">Danger</button>
<button type="button" class="btn btn-link">Link</button>

The only thing required in this file is the script tag, which should be the same for any demo that you create in this app. The rest of the code is the markup with the styles that you want to show in the demo. Additionally you can use the tag @demo to also show the snippet of code used in it. Like this:

/**
 * @stylesheet buttons.less Buttons
 * @parent styles.base
 *
 * @description
 * Global style definitions for all button elements.
 * @demo src/base/bootstrap-custom/buttons/buttons-custom.html
 */

Which will output like this: 7-style-guide-buttons-4

Demos credit goes to Bootstrap Docs where we snap the code from.

Now, before you go bananas with this, there are a couple of more goodies that you can take advantage of:

Creating Style Sections
Creating Stylesheet Groups

Creating Style Sections

To create a style section you can use the tag @styles. This tag is sweet because it allows you to break down your stylesheet doc into sensible chunks that you can talk about and understand better. For instance, in our example, we have styles for defining buttons in general, regardless of the markup that is used ( either a <button/> vs <a/> tag). And then we have definitions of color. With the @styles tag we can break the color definitions into their own section, not only to talk about them separately, but to be able to hyperlink to that section directly. This is how it works. In the same file buttons-custom.less, we are going to add the tag @styles right after the first block of styles and before the color variables. Here’s how it should look like:


/**
 * @stylesheet buttons.less Buttons
 * @parent styles.base
 *
 * @description
 * Global style definitions for all button elements.
 * @demo src/base/bootstrap-custom/buttons/buttons-types.html
 */
 
 .btn {
 display: inline-block;
 ...}
 
/**
 * @styles buttons-colors Button Colors
 *
 * @description
 * Buttons can be displayed in the following colors:
 * @demo src/base/bootstrap-custom/buttons/buttons-color.html
 */
 
 @btn-default-color: #333;

There are a couple of things to point at here:

I updated the first demo to show only the button types.
I added a new comment block using the @styles tag. Here I gave it a unique name button-colors and the title of Button Colors. I also gave it a @description and added a@demo for it that only shows the button colors.

And here’s the output: 8-style-guide-buttons-5 Notice that the new comment block is now a section within the “Buttons” doc, which you can also access directly using this url: http://localhost:8080/styleguide/buttons-colors.html 9-style-guide-buttons-6-buttons I personally find this super useful because you can point people to a specific section in the style guide, vs saying: “is in x page, under x section, then you need to scroll…and blah, blah, blah”. Instead you can provide a direct link to it, and end of the story.

Creating Stylesheet Groups

Additionally, you can also create sections or groups in the sidebar of the style guide. For this, open the file styles.md, located in the markdown directory. 10-styles-md

You will notice here a new tag called @group.

@page styles Styles
@group styles.theme 0 Theme
@group styles.base 1 Baseline
The styles shown in this section show how elements are styles with definitions from the Bootstrap framework, in addition to any customizations made for this specific project. Therefore they will be available for use in any part of the application.

Now let’s break down the second line:

@group

The @group tag allows you to create a section in the sidebar that appears under the parent section. For example, the groups: “Theme” and “Baseline” will appear under the parent section of “Styles”.

styles.theme

This is the unique name for the group. A good practice to follow here is to use the name of the parent section, in this case “Styles” as a namespace. In this way, if you want to create another group with the same name, but under a different section, the name of the group will remain unique.

This is the order in which the group should appear, which starts with 0. If no order is assigned, then the list of groups will be shown in alphabetical order.

Theme

This is the actual name that will show in the sidebar, so you can use multiple words with spaces and other characters. To see groups in action, let’s add a new group as follows:

@page styles Styles
@group styles.theme 0 Theme
@group styles.base 1 Baseline
@group styles.forms 2 Forms
The styles shown in this section show how elements are styles with definitions from the Bootstrap framework, in addition to any customizations made for this specific project. Therefore they will be available for use in any part of the application.

Finally, let’s add an existing doc under this new section. For this open the file forms-custom.less: 11-forms-custom

And on line 3, replace styles.base for styles.forms.

/**
 * @stylesheet forms-custom.less Form Elements
 * @parent styles.forms
 **/

Then run the docs and refresh the browser. You will now see the “Form Elements” doc under the group “Forms” in the sidebar. 12-style-guide-forms

Wrap Up

Living Style Guides are a tool to create more consistent and cohesive UI designs, and you can really take advantage of them when applying the Style Guide Driven Development Approach and when designing in a Modular Way. 13-giphy-back-to-the-future

You, building living style guides at this point! At this point, if you have been following along you should now have a running Living Style Guide, and a well thought-out plan to create a LSG that you can use as a baseline for other projects. [– Originally posted on the Bitovi blog, republished with the author’s permission. –]