Product Design Lessons

Intro to Foundation  |   Lesson #116

Creating your coded styleguide


Coded Style guides are everywhere today and teams all around the globe rely on them to create consistent experiences across their websites and apps. With the release of Foundation 6 the Foundation team here at ZURB also released our Style guide helper named StyleSherpa. In this lesson we’ll take a look at adding your components into the StyleSherpa template to fit your company's unique brand.

Getting StyleSherpa

StyleSherpa is included with the ZURB Template stack, so to get started we’ll be installing a fresh project. While the ZURB template can be installed straight from Github we’ll be using the Foundation CLI. Head to your terminal and with the CLI installed you can simply add the following command:

Now we can cd into our project and run npm start

StyleSherpa Overview

To get started with our StyleSherpa we’ll be navigating into our project and head into src/styleguide, which contains both of the files you need to build your style guide.

Index.html: Is a Markdown file that file contains the contents of your style guide.

template.html: This is a Handlebars template that’s responsive for the outer shell of your style guide and your index.html are inserted into this template as HTML. The final file is included in the dist/ folder of your project as styleguide.html

Editing your style guide description

We’ll start by opening up the template.html file and renaming our style guide name and editing it’s description a bit. We’ll scroll through the code till we get to our h1 tag on line 51 and replace the content with our own.

Something we include on every style guide is a title complete with version number for larger projects. This helps ensure as different properties use the same code base we know when each one needs to be upgraded. Next we state who owns and maintains the style guide and any additional links that will help send employees to the right place in case of questions.

We’ll save this file and watch they styleguide recompile with our updates.

Adding Components

The style guide comes complete with a markdown file that’s been pre-filled with many of the common components found both in Foundation and a style guide. We can use Markdown to add new items anywhere within the index.html, but we need to keep in mind a few rules that make StyleSherpa work.

The style guide is divided into sections. Generally, each component in your codebase—think buttons, panels, modals, form controls, and so on—will have its own section. Sections are titled with a Markdown heading, which is a single hash mark and new sections are defined by 4 line breaks:

A style guide should always have HTML examples, which explain how to build something. To create a code block in Markdown, surround the code with three backticks. You can also set the language of the code block after the first set of backticks. Style Sherpa will color the syntax for you in the final output. Finally we can also get StyleSherpa to both print out the code for a component and example of that component like this:

Next Steps

Now that you understand the basics of StyleSherpa you can add your own custom components, or edit the components that come with it. You can even change the base CSS for the template.html file, so you can get a custom look for your style guide.

About the instructor


Brandon Arnold is a Foundation mastermind. He contributed several key components of the latest version of our framework, and walks you through getting started with Foundation for Emails.