made-frontend-standards.md

SCSS Standards Guide

• file organization
• shared partial usage
• breakpoints
• units
• class naming
• class or id
• nesting
• subclassing
• formatting
• shorthand notation
• z-indexes
• commenting

---

File Organization

• assets/styles - reset file and rendered css file.
  
• assets/styles/scss - shared scss partials.
  
• assets/styles/scss/views - scss partials with names corresponding to views (as needed).

Shared Partial Usage

• _variables - variables, grouped logically.
  
• _mixins - mixins, grouped logically.
  
• _utilities - utility classes.
  
• _grid - styles related to widths, floats, clears and spacing of the grid system.
  
• _typography - styles related to font-family and font-sizing/line-height.
  
• _forms - input/form element styling .
  
• _layout - body/html styling and general layout elements.
  
• _components - shared components (buttons, lists, anchors, breadcrumbs, pagination, etc).
  
• _header - header styling.
  
• _footer - footer styling.
  

Any scss specific to a single view should be placed in a view specific partial.

Breakpoints (responsive builds only)

Determining breakpoints:

"Start with the small screen first, then expand until it looks like shit. Time for a breakpoint!" - @stephenhay

Add breakpoint partials as needed.

Breakpoint partial naming example:

• _grid (baseline)
• _grid-two (first breakpoint)
• _grid-three (second breakpoint)

Units

• breakpoints - em
• font sizes - rem
• line heights - unitless
• margins - px
• padding - px
• widths - %

Class Naming

The majority of classes should be named according to BEM syntax. We'll also use utility classes and state-based modifiers.

BEM (Block, Element, Modifier) Syntax

.block {}
.block__element {}
.block--modifier {}

.person {}
.person__hand {}
.person--female {}
.person--female__hand {}
.person__hand--left {}

Read about BEM here

Utility Classes

Prefixed with "u-" and used for shared utility styles (text-aligns, clears, etc)

.u-clearfix
.u-underline
.u-float-left

State Modifers

Prefixed with "is-" and used to denote state-based modifiers.

.is-expanded
.is-active

Class or ID

ID's should be used strictly as javascript hooks. All css should be handled via classes.

Nesting

No more than four levels deep.
Further Reading.

Subclassing

Subclassing should only be used when it is necessary to modify existing style declarations.

.container {
    height: 200px;
}

.container.is-expanded {
    height: 600px;
}

Formatting

• order of properties - properties organized alphabetically, @includes at bottom.
• line breaks - one property per line.
• indentation - 3 space tab width.
• spacing - single space between property and value, single return between selector blocks.
• color values - use hex values (#333) unless using rgba().
• 0 values - avoid specifying units on 0 value declarations, e.g. margin: 0 instead of margin: 0px;

.header {
    color: $green;
    display: block;
    height: auto;
    line-height: 1.5em;
    @include border-box;
    @include transition-fast;
}

.footer {
    background: $black;
    color: $white;
}

Exception to "one property per line" rule = repetitive single declarations (this shouldn't happen often):

li:nth-child(2) input[type='checkbox'] { color: #666; }
li:nth-child(3) input[type='checkbox'] { color: #E55A5A; }
li:nth-child(4) input[type='checkbox'] { color: #9F92CA; }
li:nth-child(5) input[type='checkbox'] { color: #3285EE; }

Shorthand Notation

Use shorthand when declaring 2 or more values.

Good:

margin: 10px; //all
margin: 10px 0; //top and bottom
margin: 10px 0 0 10px; //top and left
margin: 10px 10px 0 10px; //top, right, left

Bad:

margin: 0 0 0 10px; //left only

Use longhand for any individual values.

margin-left: 10px;

Z-Indexes

Think in actual layers - do not use wildcard values (e.g. z-index: 832).

Good:

z-index: 2;
z-index: 3;
z-index: 4;

Bad:

z-index: 20;
z-index: 87;
z-index: 994;

Commenting

Add a header comment to each main section. Prefix with ! to allow for fast finding.

// !MODULE ---------------------------------------------------------------------
// -----------------------------------------------------------------------------

.module {

}

Break a main section into sub-sections if you'd like:

// module body -----------------------------------------------------------------

.module__body {

}

Pass comments anywhere that you feel would benefit from an explanation. Better too many comments than not enough. Some examples:

.map__container {
    display: block;
    /* height: set via map.js */
    width: 100%;
}

.link--image {
    color: transparent; // hide file name flash on firefox
}

.footer__text:after {
    /* text set via pseudo to allow breakpoint changes */
    content: 'here is some really great text';
}