How To Create a Living Style Guide

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.

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:

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:

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:

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:

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.

Putting it all together, let’s write down these groups using a diagram:

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:

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.

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.

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:

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:

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:

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.

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:

And if you click on the “Welcome” link, you can access the start page:

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:

<code class=" language-markdown">@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> </code>

And here’s the output:

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.

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.

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

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):

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:

Now for the meaty part! With our page in place we can do a few things:

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:

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:

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.

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.

You will notice here a new tag called @group.

<code class=" language-markdown">@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.</code>

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.

0

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:

<code class=" language-markdown">@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.</code>

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