Styleguide

Styleguide

A style guide is a set of visual elements and guidelines for specific web project of specific organization. The goal of the style guides is to enforce consistency across the project.

Installation

1. Copy the styleguide source files to your project directory frontend-toolkit/.

2. Make sure your project has SSI (Server Side Includes) enabled. We use html includes to construct the styleguide template. To enable SSI on IIS server add following to your Web.config file:

       <system.webServer>       
           <handlers>
               <add name="SSI-html" path="*.html" verb="*" modules="ServerSideIncludeModule" resourceType="Unspecified" />
               <add name="ServerSideIncludeModule" path="*.html" verb="*" modules="ServerSideIncludeModule" resourceType="File" />
           </handlers>
       </system.webServer>

3. Setup Grunt to automatically update sidebar navigation:

   1. Before using Grunt make sure you have node.js installed on your machine.
   2. Double check if you have copied gruntfile.js and package.json to your project root directory.
   3. In CMD go to your project directory and run:
      1. npm install grunt -g.
      2. npm install grunt-cli -g.
      3. npm install.
      4. grunt watch.

Usage

Before you start using the styleguide you need to include CSS references of your project to the template's header '/styleguide/template/header.shtml'. Once it's done, paste your html code (snippets) inside custom tags described below.

Snippets

All snippets have to be defined inside the 'snippets' folder. Each file in the folder represents separate component and will be listed in the sidebar menu as separate item. We use Grunt to automatically construct sidebar menu but it can be done manually by updating '\styleguide\scripts\snippets.txt' file.

To create a new snippet:

1. Wrap your code with a <snippet> custom html tag.
2. Add a title to it using a <title> tag.

Example:

<snippet>
    <title>Name of the snippet</title>
    <!-- Your code goes here -->
</snippet>

You can use optional tags to enhance your snippet:

Add type="important" attribute if you want to make your description more visible:

<description type="important"></description>

If you need an extra wrapper to handle your snippet, add a <holder> tag. With the holder element you can apply custom CSS to the snippet and it won't be visible in the code view:

<snippet>
    <title>Name of the snippet</title>
    <holder style="...">
        <!-- Your code goes here -->
    </holder>
</snippet>

Static snippets

Static snippets represent global styles of the project like colors or fonts. They are located inside the 'static/index.shtml' file. Currently we have three static snippets; colors, fonts and typography.

Colors snippet

To use the color snippet, put your SCSS color variables inside <palette><color> tags:

<palette>
    <colors>
        $blue: #26A9E0;
        $green: #39B54A;
        $red: #EE4036;
    </colors>
</palette>

If you have two level variable declaration, you can show them by wrapping the code in to a <vars> tag:

<palette>
    <colors>
        $blue: #26A9E0;
        $green: #39B54A;
        $red: #EE4036;
    </colors>
    <vars>
        $border-color: $blue;
        $bg-color: $green;
        $text-color: $red;
    </vars>
</palette>

Fonts snippet

To use the fonts snippet, put your SCSS font declaration variables inside a <fonts> tag:

<fonts>
    $font-oswald: 'Oswald', sans-serif;;
    $font-droid: 'Droid', serif;
</fonts>

If you want to show different font styles (e.g. bold, italic) of the same font, you can place them after the font variable:

<fonts>
    $font-oswald: 'Oswald', sans-serif;
    $font-oswald: 'Oswald', sans-serif; font-weight: 700;
    $font-oswald: 'Oswald', sans-serif; font-weight: 700; font-style: italic;
</fonts>

Typography snippet

Typography snippet is hardcoded and doesn't have any options. It represents the default styles of headings and text.