css-guidelines.md

CSS guidelines (SASS)

These are guidelines, and if you think it's necessary to deviate feel free to do so, but please be sensible and do this only because it's necessary.

• Be familiar with SCSS
• Read this
• Read this
• Use SCSS, but only nest one level
• Be sensible
• Don't break the windows
• DRY
• Use single-direction margin declarations

Content

1. Comments
2. File structure
3. Naming and states
4. Declaration order
5. Media queries
6. Javascript
7. Exceptions and deviations

1. Comments

---

• Place inline comments on a new line above the subject

/**
 * File name
 *
 * Optional description
 *
 * @author author name
 */


/* Section comment
 *
 * Optional description
 *
 * ========================================================================== */


/* This is an inline CSS comment (use this in css files) */

// This is an inline SCSS comment (use this in scss files)

2. File structure

• Files that contains multiple words are separated with dashes e.g. _my-module.scss

Example

sass/
  base/
    _base.scss
  base_modules
    _base-button.scss
    _base-list.scss
  layout/
    _layout.scss
  modules/
    _my-module.scss
    _search.scss
    _form.scss
  patterns/
    _patterns.scss
    _search-patterns.scss
  theme/
    _theme-vars.scss
    _buttons.scss
  styles.scss

3. Naming and states

Naming

Naming are based (very) loosely on BEM. Module elements is separated with two dashes, and the module name itself can have single dashes if needed.

.module-name {
}

.module-name--element-1 {
}

.module-name--element-2 {
}

.search {
}

.search--button {
}

.search--field {
}

###Structue Structure the sass modules as logical patterns.

Folders

• Base: default base styles. Should be included in every project to set som reasonable defaults sitewide.
• Base-module: folder holding the default/fallback styles for all components in the project (and across projects). This folder can be used as reference for developers, and should be very well documented on flow and usage. This folder could be part of the boilerplate.
• Layout: Holds classes for the general page layout, often including the selectors that extend grid styles.
• Modules: Site specific styles extending patterns and adding custom code. Each module should have a logical and isolated usage.
• Pattern: Components should hold mostly if not only silent classes (%list, %list--item, %list--link etc.)
• Theme: For site specific default variables, mixins and global silent classes

States

If states are needed prefix it with .is-, .has- etc., also check out the javascript guidelines.

<a href="http://example.com" class="button">This is a link button</a>

<a href="http://example.com" class="button is-active">This is a link button</a>

.button {
  background-color: $gray;

  &.is-active {
    background-color: $green;
  }
}

4. Declaration order

• One selector per line
• Add a single space after the colon of the declaration
• @extend goes in the top so we know if the ruleset inherits another
• Normal rules goes next
• @include goes last

.class {
  @extend %placeholder();

  /* Positioning */
  position: absolute;
  z-index: 10;
  top: 0;
  right: 0;
  bottom: 0;
  left: 0;


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

  /* Other */
  background: $color;
  color: $white;
  font-family: $font-family;
  font-size: $font-size;
  text-align: right;

  @include mixin();
}

5. Media queries

• Add media query @includes after other @includes and @extends

.class {
  background-color: $blue;

  @include breakpoint(10em) {
  	background-color: $red;
  }

  @include breakpoint(20em) {
  	background-color: $green;
  }

  @include breakpoint($breakpoint) {
  	background-color: $white;
  }
}

6. Javascript

• Don't use .js- for styling

See javascript guidelines

7. Exceptions and deviations

• You can nest two levels when using pseudo classes
• You can nest two levels when using media queries mixins
• If you have to deviate from the one limit nesting rule (except mentioned in this section), explain why in an inline comment