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.

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

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:

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. 

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:

  1. npm run develop
  2. 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:

And in the browser:

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:

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.

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.

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:

@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`:
 

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.

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.

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.

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:

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

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 :

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:

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

Leave a Reply

Your email address will not be published. Required fields are marked *