Skip to content

Coding Guidelines

Jump to bottom
Garth Braithwaite edited this page Apr 23, 2018 · 1 revision

CSS

Table of Contents

  1. Approach
  2. Whitespace
  3. Format
  4. Selectors
  5. Comments
  6. Property Order
  7. Layout
  8. Research

  1. Approach

This coding guide is based off of listening to some of the smartest people in the industry. It focuses on making performant, consistent, scalable and maintainable CSS. We all have our opinions and preferences, but have tried our best to put those aside to benefit the greater good with the current data at hand. This is a living document and we welcome contribution. The better the input the better the output. Feel free to help us get it right.

2. Whitespace

Use [2]consistent whitespace.

  • Soft tabs of four spaces
    .btn {
        background: #fff;
    }

3. Format

Use consistent formatting in order to increase understanding and [2]legibility

  • One selector per line
  • Use one space between selector and first bracket
  • Use one space between property and value after :
  • Always add a semicolon after property value
  • Use double quotes
  • Do not specify units for a zero value
  • Include a space after each comma in a comma separated property list
  • Separate each ruleset by an empty line
.selector-1,
.selector-2 {
    box-sizing: border-box;
    display: block;
    font-family: helvetica, arial, sans-serif;
    color: #333;
    background: 0 0 #666 no-repeat url("../img/bg_img.png");
}

.selector-a,
.selector-b {
    padding: 10px;
}

4. Selectors

TopCoat is designed to be modular and component focused. The styles are created to be as portable as possibe while keeping performance as the top goal.

    /* NO */
    #header {
        position: absolute;
    }
    /* NO */
    header {
        color: blue;
    }
  • Do not over qualify selectors because it impacts [1]performance 
    /* NO */
    ul li.button.large.blue {
        background: salmon;
    }
  • Use class names for specificity to increase [1]performance 
    /* YES */
    .list-item {
        border: 1px solid #666;
    }
    /*
     * Base reset components
     * Use the naming convention:
     * {component}-{name}__{subcomponent}--{modifier}
     * 
     */

    /* Component */
    .button-group

    /* Component Modifier */
    .button-group--large

    /* Subcomponent */
    .button-group__button

    /* Subcomponent Modifier */
    .button-group__button--cta

    /*
     * Themed components
     * Use the naming convention:
     * {theme}-{component}-{name}__{subcomponent}--{modifier}
     */

    /* Component */
    .topcoat-button-group

    /* Component Modifier */
    .topcoat-button-group--large

    /* Subcomponent */
    .topcoat-button-group__button

    /* Subcomponent Modifier */
    .topcoat-button-group__button--cta

5. Comments

We depend on Topdoc comments in order to generate a style guide from the css.

 /* topdoc
  name: Button
  description: A simple button
  modifiers:
    :active: Active state
    .is-active: Simulates an active state on mobile devices
    :disabled: Disabled state
    .is-disabled: Simulates a disabled state on mobile devices
  markup:
    <a class="topcoat-button">Button</a>
    <a class="topcoat-button is-active">Button</a>
    <a class="topcoat-button is-disabled">Button</a>
  example: http://codepen.io/
  tags:
    - desktop
    - light
    - mobile
    - button
    - quiet
  blarg: very true
*/
.topcoat-button,
.topcoat-button--quiet,
.topcoat-button--large,
.topcoat-button--large--quiet,
.topcoat-button--cta,
.topcoat-button--large--cta {

6. Property Order

Property order should be in [2]structural order of importance.

.selector {
    /* Positioning */
    position: absolute;
    z-index: 10;

    /* Display & Box Model */
    display: inline-block;
    overflow: hidden;
    box-sizing: border-box;
    width: 100px;
    height: 100px;
    padding: 10px;
    border: 10px solid #333;
    margin: 10px;

    /* Visual styles */
    background: #000;
    color: #fff;
    font-family: sans-serif;
    font-size: 16px;
    text-align: right;

    /* Vendor prefixed styles */
    -webkit-user-select: none;
}

7. Layout

Layout should be handled by a layout specific class. You should not mix layout and visual styling in one class definition.

.topcoat-header--dark {
    background: #c6c8c8;
}

/* ... Layout section */

.span-3 {
    width: 33.333%
}
    <header class="topcoat-header--dark span-3"></header>

8. Research

By importance of inclusion:

Clone this wiki locally