How To Create a Living Style Guide

Default avatar.
January 10, 2018
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-kramerEven 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
2-example-lonely-planetLonely Planet Style Guide 3-example-sales-forceSales 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: 5-vintage-shop-mockupsVintage 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/​e​x​a​mples 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-giphyYas! 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: 2-terminal-server-runningAnd 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-welcomeThe 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.
6-style-guide-generatorWith 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-contentsDrill 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-aboutInside 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-1The 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-2And if you click on the Welcome” link, you can access the start page: 11-style-guide-about-3Now 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-futureYourself 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-1Now, 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-demoAnd 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-4Demos 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-5Notice 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-buttonsI 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-mdYou 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.

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:

@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-customAnd 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-futureYou, 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. –]

Adriana De La Cuadra

This article originally appeared on Bitovi​.com and is part of a free tutorial series at styleguid​edriven​de​velopment​.com.

Read Next

15 Best New Fonts, May 2023

The choices you make when selecting a typeface have more impact on your design than almost any other decision, so it’s …

10+ Best Tools & Resources for Web Designers and Agencies (2023 updated)

Having the ability to envision a tastefully designed website (i.e., the role creativity plays) is important. But being …

20 Best New Websites, May 2023

This month, there are tons of great new agency websites to get excited about. 3D animated prisms are a popular theme, a…

How to Find the Right White Label Website Builder for Your Agency

Web design agencies face a lot of obstacles in closing the deal with new clients. One of the most common ones is the ar…

Exciting New Tools For Designers, May 2023

There are hundreds of new tools for designers and developers released each month. We sift through them all to bring you…

3 Essential Design Trends, May 2023

All three of the website design trends here mimic something bigger going on in the tech space, from a desire to have mo…

10 Best AI Tools for Web Designers (2023)

It’s time to stop worrying if AI is going to take your job and instead start using AI to expand the services you can of…

10 Best Marketing Agency Websites (Examples, Inspo, and Templates!)

Marketers are skilled in developing strategies, producing visual assets, writing text with high impact, and optimizing …

15 Best New Fonts, April 2023

Fonts are a designer’s best friend. They add personality to our designs and enable fine typography to elevate the quali…

20 Best New Websites, April 2023

In April’s edition, there’s a whole heap of large-scale, and even full-screen, video. Drone footage is back with a veng…

Exciting New Tools For Designers, April 2023

The AI revolution is having a huge impact on the types of products that are hitting the market, with almost every app b…

3 Essential Design Trends, March 2023

One thing that we often think about design trends is that they are probably good to make a list. That’s not always true…