Cozy-UI Styleguide

Cozy-UI Styleguide

CSS Guidelines

Syntax & Formatting

A few basic rules for syntax and formatting. A linter and a .editorconfig file are keeping a eye on the produced CSS to make sure it respects most of those rules but you should know them nevertheless.

div
    // Positionning
    z-index  5
    position absolute
    top      0
    left     0

    // Box-model
    display    block
    box-sizing border-box
    width      60vw
    margin     0 auto

    // Borders and padding
    border        1px solid
    border-radius 50%
    padding       1rem

    // Colors
    background-color black
    color            white

    // Typo
    font-family MavenPro
    font-size   1rem
    line-height 1.5em

Commenting

There's several type of comment available to you.

Block Comments for sectioning

/*------------------------------------*\
  #SECTION-TITLE
\*------------------------------------*/

To be used on top a file and/or to section a long file.

Note Comment

When you have several comments to do on a chunk of tricky code it may be better to Note Comments

$sprite-width:  920px;
$sprite-height: 212px;

/**
 * 1. Default icon size is 16px.
 * 2. Squash down the retina sprite to display at the correct size.
 */
.sprite {
  width:  16px; /* [1] */
  height: 16px; /* [1] */
  background-image: url(/img/sprites/main.png);
  background-size: ($sprite-width / 2 ) ($sprite-height / 2); /* [2] */
}

Basic comments

As we use Stylus as preprocessor, I recommend the use of // for inline but CSS syntax is tolerated.

// Basic button
.btn
  display    inline-block
  background black
  color      white

You should always comment what you code, especially when what you coded isn't obvious, and nothing is obvious.

KSS Comments

In order to populate the styleguide you need to use specific comments, KSS comments. It basically, very basically, looks like that.

// Title
//
// Description
//
// Markup:
// <button class="button {{modifier_class}}">Button</button>
//
// modifier_class - class description
//
// Reference

Please follow the KSS specs for more details.

Naming Conventions

We use SuitCSS naming convention which in kinda like BEM but with a slightly different syntax.

Selectors

Basically:

Specificity

Principles

The Open/Closed Principle

The open/closed principle states that classes should be open for extension, but closed for modification.

The idea here is to get an easily evolutive CSS while keeping a certain level of backward compatibility.
Further reading: http://csswizardry.com/2012/06/the-open-closed-principle-applied-to-css/

The DRY method

Don't Repeat Yourself! Use @extend as much as possible to keep your code clean but do it well and smartly.