Style Guide

This topic applies to

Applies to

Kilimanjaro

 

A style guide helps developers and designers use the various style elements defined for a site. Contributors can refer to a style guide to create new pages and elements or customize existing ones. A style guide can also ensure that your best practices for site design are being met by multiple contributors.

You can use the developer tools to create a style guide automatically. To do so, the source BaseSassStyles module uses KSS notation to document and define Sass elements. As a best practice, build any Sass customizations using KSS notation as defined in this section.

To create a style guide using the developer tools:

  1. In your local developer environment, open a command line or terminal and access the top-level development directory.

  2. Run the following command:

    gulp theme:local styleguide

  3. Point your browser to:

    localhost:3000

You should see your style guide appear, looking similar to the following example:

KSS Notation

SuiteCommerce uses Knyle Style Sheets (KSS) notation to automate the creation of a Sass style guide. KSS is simply a documentation syntax for CSS, written in a human-readable way. A style guide serves as a place to publish KSS documentation and visualize different states of user interface elements defined in your Sass.

Note

KSS does not affect the performance or rendering of CSS in any way. It is meant to document your styles in a human-readable way and automate the creation of a related style guide.


The following elements of this notation appear before each element defined in a Sass file. These are parsed and used to create a style guide automatically using the developer tools.

  • Title – defines the element. Best practice is to use an intuitive, human-readable title.

  • Description – briefly explains the intended purpose and implementation of the element.

  • Markup – provides the HTML markup used to generate the element.

  • Index – defines where the element exists within the style guide structure.

    For example:

    2.0
    2.1
       2.1.1
       2.1.2
    2.2
       2.2.1

The following example comes from the base Sass style atom _buttons.scss and highlights the basics of KSS notation as used by SuiteCommerce Advanced.

//... // Primary buttons (This is an example of the Title element) // // The primary action is generally the action that completes a task or desired action. // Primary buttons use bright and use saturated colors to provide stronger visual weight that catches the users attention to avoid confusion and competing with secondary actions. (This is an example of the Description element) // // Markup: // <button class='button-primary button-medium">Button Primary</button> (This is an example of the Markup element) // // Styleguide 2.1.1 (This is an example of the Index element) .button-primary { color: white; font-weight: $sc-font-weight-normal; background: $sc-color-button-primary; display: inline-block; border: 1px solid $sc-color-button-primary; border-radius: $sc-border-radius; //...