About
Foundations
Components
Templates
Getting Started
How to setup and configure this Jekyll-based style guide boilerplate.

Installation

To start you’ll need to download and install Jekyll (3.1 or higher) and the source code from Github.

Sample UI patterns and documentation have been included in this tool to indicate what a finished Style Guide could look like. You can remove the files from src/ and the CNAME file to start from scratch.

To serve the files locally run the following code in terminal:

$ cd /path/to/local/folder/
jekyll serve

Once your style guide is complete you can publish it to Github Pages like any other Jekyll website.

Configuration

jekyll-style-guide/
├── _config.yml
├── index.md
├── README.md
│

All settings are contained in the _config.yml file. To use this tool out of the box, you only need to adjust the pattern settings.

General Settings

These are standard Jekyll configuration settings, check the documentation for information on how to use this.

Style Guide Shell Settings

These settings control the default variables used in the shell, check the Editing the Styleguide section for help on how to use them.

Collection Settings

These settings control how documentation and pattern files are generated, and where they are located. Check the Editing the Styleguide section for help on how to use them.

Pattern Settings

These settings are used in all patterns and should be updated based on your needs.

## Pattern Settings

pattern_author: AUTHOR NAME             ## sets the author in the <head></head> tag
pattern_description: DESCRIPTION        ## sets the description in the <head></head> tag
pattern_language: en                    ## sets the language in the <html></html> tag
pattern_favicon: /src/assets/images/icon.ico

pattern_styles:                         ## (list) add style locations here
  - /src/assets/css/style.css
  
pattern_scripts:                        ## (list) add script locations here
  - /styleguide/js/libs/jquery-2.1.4.min.js  

sass:
  sass_dir: src/assets/_scss            ## sets the location of the stylesheet
  style: :compressed                    ## minifys the stylesheet

Remember you need to $jekyll build or $jekyll serve your site in terminal after changing any of the config files.

Adding Patterns

What is a Pattern?

A ‘Pattern’ is any part of the user interface, by default there are 3 types:

  • Foundations
    • Foundations are global constraints that define the basic parameters of parts of the UI.
    • Example, a Typeface, Primary or Secondary Colors, Icons.
  • Components
    • Components are stand-alone UI patterns that can be directly used in the interface.
    • They can include Foundations, or can be constructed with uniques styles.
    • Example, Primary Button, Secondary Button, Card, Card Group, Table, etc.
  • Templates
    • Templates are pre-determined page layouts.
    • They can include components and foundations, or can be constructed uniquely.
    • Examples, Full-Width Content Page, Sidebar Page, Two Column Page
│   
└── src/ 
    ├── assets/
    │   ├── _scss
    │   ├── css
    │   ├── fonts
    │   └── images
    │
    └── patterns/
        ├── foundations/
        │   ├── ...
        ├── components/
        │   └── ...
        └── templates/
            └── ...

Uploading Patterns

  • Write your HTML pattern in a Markdown file.
  • The pattern must start with Front Matter.
  • Set the title, maturity, and the location of the corresponding styles.
  • Optional: Turn off the Pattern Controls by using control: exclude - this is particularly useful for foundation patterns.
---
title: Default Button
styles: base/button.scss
maturity: ready
control: exclude
---
<a href="javascript:void(0)" class="button">Click Me!</a>
  • Upload your pattern to the corresponding folder in src/patterns.
  • You need to make sure your pattern is 4 folder levels deep to ensure they get linked correctly from the navigation and roadmap, so group you patterns in sub folders
#Example 1: Primary Colors stored in a /color sub folder.
/src/patterns/foundations/color/primary-colors.md

#Example 2: Disabled Card stored in a /cards sub folder.
/src/patterns/components/cards/disabled-card.md

Editing Pattern Assets

  • Pattern assets are stored in the src/assets folder.
  • You can add additional styles/scripts to a pattern via the Pattern Settings in the _config.yml file - styles will automatically be included in the <head>, scripts will automatically be included before the </body> tag in all patterns.

Keep your styles organised. Try this simple SCSS playbook.

Adding Documentation

What is Documentation?

‘Documentation’ is used to store information relating to a pattern (or group of patterns), as well as information about the style guide itself - this page is an example of a document.

By default, documentation is stored in the _docs folder and grouped in directories that correspond to the pattern directories. An additional /about directory is also provided, this can contain general/non-pattern specific contents (like this page).

Patterns are always loaded into a document via an iFrame, so any style guide related styles will not interfere with your pattern.

│
├── _docs/
│   ├── about/
│   │   └── ...   
│   │
│   ├── components/
│   │   └── ...
│   │
│   ├── foundations/
│   │   ├── color.md
│   │   ├── typography.md   
│   │   └── ...
│   │
│   └── templates/
│       └── ...
│

Adding any document into these folders will automatically make it appear in the style guide navigation.

Documentation Settings

These settings are defined in the config.yml file and ensure that each document outputs with the correct Jekyll layout and meta data.

## Collection Settings

## Outputs the _docs collection !Required
collections:
  docs: 
    output: true

## Sets the default attributes for the Documentation and Pattern Files !Required
defaults:
  - 
    scope:
      path: "_docs"
    values:
      layout: doc
      type: doc
  - 
    scope:
      path: "_docs/about"
    values:
      layout: doc
      type: about    
  - 
    scope:
      path: "_docs/foundations"
    values:
      layout: doc
      type: foundation
  - 
    scope:
      path: "_docs/components"
    values:
      layout: doc
      type: component 
  - 
    scope:
      path: "_docs/templates"
    values:
      layout: doc
      type: template

Adding Documentation

  • Create your document file in Markdown format.
  • Your filename can match the pattern URL, but it does not have too.
#Pattern Location.
/src/patterns/foundations/color/primary-colors.md

#Corresponding document file option 1:
/_docs/fondations/color.md

#Corresponding document file option 2:
/_docs/fondations/palette.md
  • The document must start with Front Matter.
  • Set the title.
  • Optional: add info which will be displayed at the top of the document page.
  • Optional: add nav: true into the Front Matter if you would like to display a mini contents menu at the top of the page (like this page).
  • You can use any Markdown in the page content area.
  • To include a pattern in the document page you must include the pattern block and specify a url variable in the include. By repeating this process you can include multiple patterns on the page. See the sample below taken from the button.md file.
  • Note that the pattern controls and maturity are set in the pattern file.

The contents menu will automatically generate a table of contents based on any h1 items on the page.

---
title: Button
info: Use buttons to signal actions.
nav: true
---

# Basic Buttons

A button can contain text. Although any tag can be used for a button, it will only be keyboard focusable if you use a `button` tag or you add the property `tabindex="0"`.

{% include pattern_block.html url='/src/patterns/components/button/default_button.html' %}

{% include pattern_block.html url='/src/patterns/components/button/disabled_button.html' %}

Sample Pages

Coming Soon

Editing the Style Guide

Coming Soon