Skip to content

Latest commit

 

History

History
1642 lines (1203 loc) · 24.3 KB

README.md

File metadata and controls

1642 lines (1203 loc) · 24.3 KB
Raw

Weblinc SCSS Style Guide

Weblinc Best Practices

The following rules are recommended best practices for the Weblinc platform. Many come from Harry Robert's CSS Guidelines.

Mobile-first Approach

Reduces file size. Improves readability.

Bad

.foo {
    width: 25%;
}

...

@media screen, and (max-width: $medium-breakpoint) {
    width: 50%;
}

Good

.foo {
    width: 50%;  // styles for small devices 

    @include respond-to($medium-breakpoint) {
        width: 25%;  // styles for medium devices
    }
}

Multiple Files

Each file should serve one and only one purpose. Improves maintainability.

Bad

// components/_foo.scss
.foo { ... }

.bar { ... }

Good

// components/_foo.scss
.foo { ... }
// components/_bar.scss
.bar { ... }

Indenting

Intent BEM elements to showcase relationships. Improves readability.

Bad

.foo { ... }

.foo__bar { ... }

.foo_bar--baz { ... }

Good

.foo { ... }

    .foo__bar { ... }

    .foo__bar--baz { ... }

Meaningful Whitespace

Improves readability.

  • 1 newline to express tight relationships
  • 2 newlines to express loose relationships
  • no newline between comment blocks and their related rule set

Bad

$parent-width: 100px;
$parent-child-width: 800px;
$parent-child-heading-color: $black;

/**
 * The `.parent` UI blah blah blah
 */

.parent { ... }

    .parent__child { ... }

        .parent__child-heading { ... }

    .parent__cousin { ... }

Good

$parent-width: 100px;

$parent-child-width: 800px;
$parent-child-heading-color: $black;

/**
 * The `.parent` UI blah blah blah
 */
.parent { ... }


    .parent__child { ... }

        .parent__child-heading { ... }


    .parent__cousin { ... }

DocBlock Commenting

Use DocBlock style comments. Improves readability.

Bad

.foo { ... } /* some comment */
.foo { ... } // some comment

Good

/**
 * Some Comment
 */
.foo { ... }

Reverse Footnotes in Comments

Improves maintainability. Improves readability.

Bad

.foo {
    position: relative;
    z-index: 30;
}

    .foo__bar {
        position: absolute;
        top: 0;
        left: 0;
        z-index: 20;
    }

Good

/**
 * 1. provides positioning context for `.foo__bar`
 * 2. above `.foo__bar`
 */
.foo {
    position: relative; /* [1] */
    z-index: 30; /* [2] */
}

    /**
     * 1. below `.foo`
     */
    .foo__bar {
        position: absolute;
        top: 0;
        left: 0;
        z-index: 20; /* [1] */
    }

Use proactive !default

Improves maintainability.

Bad

$foo: bar;

Good

$foo: bar !default;

Encapsulate contextual styles

Improves maintainability. Improves readability.

Bad

// components/_foo.scss
.foo {
    margin: 10px 0;

    .bar {
        background: $blue;
    }
}
// components/_bar.scss
.bar {
    background: $red;
}

Good

// components/_foo.scss
.foo {
    margin: 10px 0;
}
// components/_bar.scss
.bar {
    background: $red;

    .foo & {
        background: $blue;
    }
}

Group related selectors on the same line

Improves readability.

Bad

dl,
dd,
ol,
ul,
th,
td { ... }

Good

dl, dd, ol, ul,
table, th, td { ... }

SCSS Lint

The following rules are enforcible via scss-lint. If you're linting your files properly any offenses should be caught automatically.

Add only one space before flag (BangFormat)

Improves readability.

Bad

$color: #000!default;

.foo {
    @extend %placeholder ! optional;
}

Good

$color: #000 !default;

.foo {
    @extend %placeholder !optional;
}

Each BEM element has one and only one parent (BemDepth)

Reduces confusion.

Bad

.block__element__sub-element {}

Good

.block__element {}

Don't "double" modifiers

Reduces confusion.

Bad

.component--modifier--another-modifier {}

Good

.component--modifier {}
.componetn--another-modifier {}

Components must own their modifiers

Reduces confusion. Examples in Haml:

Bad

%h4.heading--1

Good

%h4.heading.heading--1

Remove borders with a zero (BorderZero)

Reduces file size.

Bad

border: none;

Good

border: 0;

Don't chain classes (ChainedClasses)

Reduces specificity. Promotes reusable selectors.

Bad

.foo {
    padding: 5px;
}

.bar {
    margin: 5px;
}

.foo.bar {
    display: block;
}

Good

.foo {
    padding: 5px;
}

.bar {
    margin: 5px;
}

.new-class {
    display: block;
}

Never use color keywords (ColorKeyword)

Improves maintainability.

Bad

$color: red;

Good

$color: #ff0000;

Always define colors in variables (ColorVariable)

Improves maintainability.

Bad

.foo {
    background-color: #ff0000;
}

Good

$foo-bg-color: #ff0000;

...

.foo {
    background-color: $foo-bg-color;
}

Prefer traditional CSS comments (Comment)

Increases readability. These are removed during compilation.

Bad

.foo {
    z-index: 30; // above `.bar`, below `.baz`
}

Good

/**
 * 1. above `.bar`, below `.baz`
 */
.foo {
    z-index: 30; /* [1] */
}

Don't commit @debug statements (DebugStatement)

Keep your @debug statements out of the code base.

Maintain a sane declaration order (DeclarationOrder)

Improves readability.

Rule sets should be declared in the following order:

  1. @extend
  2. @include without inner @content
  3. properties
  4. @include with inner @content

Bad

.foo {
    background-color: $bg-color;

    @include icon {
        color: $icon-color;
    }

    @extend %heading;
    @include clearfix;
}

Good

.foo {
    @extend %heading;
    @include clearfix;
    background-color: $bg-color;

    @include icon {
        color: $icon-color;
    }

}

Remove duplicate properties (DuplicateProperty)

Improves maintainability. Reduces errors.

Bad

.foo {
    margin: 10px 0;
    padding: 10px;
    margin: 0;
}

Good

.foo {
    margin: 10px 0;
    padding: 10px;
}

Don't start @else on a new line (ElsePlacement)

Improves readability.

Bad

@if ($toggle) {
    /* do something */
}
@else {
    /* do something else */
}

Good

@if ($toggle) {
    /* do something */
} @else {
    /* do something else */
}

Add newline between rule sets (EmptyLineBetweenBlocks)

Improves readability.

Bad

.foo {
    margin: 0;
    .baz & {
        margin: 10px;
    }
}
.bar {
    padding: 10;
}

Good

.foo {
    margin: 0;

    .baz & {
        margin: 10px;
    }
}

.bar {
    padding: 10;
}

Add newline to end of file (FinalNewline)

Improves diff.

Bad

.foo {
    padding: 10px;
}

Good

.foo {
    padding: 10px;
}

Reduce length of hexadecimals where possible (HexLength)

Reduces file size.

Bad

$red: #ff0000;

Good

$red: #f00;

Use lowercase for hexadecimals (HexNotation)

Reduces file size.

Bad

$red: #F00;

Good

$red: #f00;

Hexadecimal values should be 3 or 6 characters (HexValidation)

Reduces errors.

Bad

$red: #f0;
$blue: #0000f92;

Good

$red: #f00;
$blue: #0000f9;

Don't use IDs as selectors (IdSelector)

Reduces specificity.

Bad

#foo {
    padding: 10px;
}

Good

.foo {
    padding: 10px;
}

Don't use !important (ImportantRule)

Reduces specificity.

Bad

.foo {
    padding: 10px !important;
}

Good

.foo {
    padding: 10px;
}

Import files properly (ImportPath)

Improves best practices.

Bad

@import "foo/_bar.scss";
@import "_bar.scss";
@import "_bar";
@import "bar.scss";

Good

@import "foo/bar";
@import "bar";

Four spaces for indentation (Indentation)

Improves readability.

Bad

.foo {
  padding: 10px;
}

  .foo__bar {
    margin: 10px 0;
  }

Good

.foo {
    padding: 10px;
}

    .foo__bar {
        margin: 10px 0;
    }

Add leading zero to decimals (LeadingZero)

Improves readability.

Bad

.foo {
    margin: .5em;
}

Good

.foo {
    margin: 0.5em;
}

Don't duplicate selectors (MergeableSelector)

Improves maintainability.

Bad

.foo {
    padding: 10px;
}

.bar {
    margin: 10px 0;
}

.bar.ui-menu {
    background: $gray;
}

.foo {
    text-decoration: underline;
}

Good

.foo {
    padding: 10px;
    text-decoration: underline;
}

.bar {
    margin: 10px 0;

    &.ui-menu {
        background: $gray;
    }
}

Use kebab-case for naming (NameFormat)

Improves readability.

Bad

@function fooBar { ... }
@mixin BarBaz { ... }
%baz_qux { ... }
$quux_corge: ...;

Good

@function foo-bar { ... }
@mixin bar-baz { ... }
%baz-qux { ... }
$quux-corge: ...;

Don't nest selectors past a depth of 3 (NestingDepth)

Reduces specificity.

Bad

.foo {
    .foo__bar {
        .foo__baz {
            &:hover {
                ...
            }
        }
    }
}

Good

.foo { ... }

    .foo__bar { ... }

        .foo__baz {
            &:hover {
                ...
            }
        }

Don't nest selectors within a media query

Improves maintainability.

Bad

.component { ... }

.component--modifier { ... }

    .component__element {
        @include respond-to($medium-breakpoint) {
            color: $element-color;

            .component--modifier & {
                color: $modified-element-color;
            }
        }
    }

Good

.component { ... }

.component--modifier { ... }

    .component__element {
        @include respond-to($medium-breakpoint) {
            color: $element-color;
        }

        .component--modifier & {
            @include respond-to($medium-breakpoint) {
                color: $modified-element-color;
            }
        }
    }

Only extend placeholder selectors (PlaceholderInExtend)

Reduces file size.

Bad

.foo {
    @extend .bar;
}

Good

.foo {
    @extend %bar;
}

Maintain a sane property sort order (PropertySortOrder)

Improves maintainability. Properties within this list should be ordered appropriately. Properties not within this list should come below ordered properties.

display

position
top
right
bottom
left
z-index

margin
margin-top
margin-right
margin-bottom
margin-left

margin-collapse
margin-top-collapse
margin-right-collapse
margin-bottom-collapse
margin-left-collapse

padding
padding-top
padding-right
padding-bottom
padding-left

width
height
max-width
max-height
min-width
min-height

float
clear

color

font
font-style
font-family
font-weight
font-variant
font-smoothing

line-height
letter-spacing
word-spacing

text-align
text-indent
text-shadow
text-overflow
text-rendering
text-transform
text-decoration
text-size-adjust

word-break
word-wrap

white-space

background
background-size
background-color
background-image
background-repeat
background-position
background-attachment

border
border-top
border-right
border-bottom
border-left

border-image
border-spacing
border-collapse

border-color
border-top-color
border-right-color
border-bottom-color
border-left-color

border-style
border-top-style
border-right-style
border-bottom-style
border-left-style

border-width
border-top-width
border-right-width
border-bottom-width
border-left-width

border-radius
border-top-right-radius
border-bottom-right-radius
border-bottom-left-radius
border-top-left-radius
border-radius-topright
border-radius-bottomright
border-radius-bottomleft
border-radius-topleft

box-shadow

Spell properties correctly (PropertySpelling)

Reduces errors.

Bad

.foo {
    dipslay: none;
}

Good

.foo {
    display: none;
}

Control property value units (PropertyUnits)

Supports best practices.

  • line-height should be unitless

Bad

.foo {
    font-size: 16px;
    line-height: 20px;
}

Good

.foo {
    font-size: 16px;
    line-height: 1.25;
}

Use two colons to prefix pseudo-elements (PseudoElement)

Improves readability. Supports best practices.

Bad

.foo {
    &:before { ... }
    &::hover { ... }
}

Good

.foo {
    &::before { ... }
    &:hover { ... }
}

Don't prefix selectors with elements (QualifyingElement)

Reduces specificity.

Bad

div.foo { ... }

input[type=text] { ... }

div#foo { ... }

Good

.foo { ... }

[type=text] { ... }

#foo { ... }

Don't write selectors past a depth of 3 (SelectorDepth)

Reduces specificity.

Bad

.foo .bar .baz .qux { ... }

.foo {
    .bar .baz .qux { ... }
}

Good

.foo .bar .baz { ... }

.foo {
    .bar .baz & { ... }
}

Use BEM-like syntax (SelectorFormat)

Improves maintainability. Improves readability. More info here.

Bad

.foo {
    background: $white;

    &.active {
        background: $yellow;
    }
}

    .foo-child {
        padding: 10px;
    }

Good

.foo {
    background: $white;
}

.foo--active {
    background: $yellow;
}

    .foo__child {
        padding: 10px;
    }

Use shorthand properties wherever possible (Shorthand)

Reduces file size.

Bad

.foo {
    margin: 10px 0 10px 0;
}

Good

.foo {
    margin: 10px 0;
}

Each property should appear on it's own line (SingleLinePerProperty)

Improves readability.

Bad

.foo {
    margin: 10px 0; padding: 10px;
}

Good

.foo {
    margin: 10px 0;
    padding: 10px;
}

Add one space after comma (SpaceAfterComma)

Improves readability.

Bad

.foo {
    color: rgba(0,0,0,.5);
}

Good

.foo {
    color: rgba(0, 0, 0, .5);
}

Add one space after comment (SpaceAfterComment)

Improves readability.

Bad

/**
 *Foo
 */

Good

/**
 * Foo
 */

Add one space after property colon (SpaceAfterPropertyColon)

Improves readability.

Bad

.foo {
    padding:10px;
}

.foo {
    padding:    10px;
}

Good

.foo {
    padding: 10px;
}

Don't add spaces after property name (SpaceAfterPropertyName)

Improves readability.

Bad

.foo {
    padding : 10px;
}

Good

.foo {
    padding: 10px;
}

Add one space after variable colon (SpaceAfterVariableColon)

Improves readability.

Bad

$foo:bar;
$foobar:baz;

Good

$foo:     bar;
$foobar:  baz;

Don't add spaces after variable name (SpaceAfterVariableName)

Improves readability.

Bad

$foo : bar;

Good

$foo: bar;

Add a space around operators (SpaceAroundOperator)

Improves readability.

Bad

.foo {
    width: $bar-width+$bar-width;
}

Good

.foo {
    width: $bar-width + $bar-width;
}

Add one space before curly brace (SpaceBeforeBrace)

Improves readability.

Bad

.foo{
    padding: 10px;
}

.bar
{
    padding: 10px;
}

.bar--baz{ padding: 10px 0 0; }
.bar--corge{ padding:  0 0 10px; }

Good

.foo {
    padding: 10px;
}

.bar {
    padding: 10px;
}

.bar--baz   { padding: 10px 0 0; }
.bar--corge { padding: 0 0 10px; }

Don't add spaces between parenthesis (SpaceBetweenParens)

Improves readability.

Bad

.foo {
color: rgba( 0, 0, 0, .5 );
}

Good

.foo {
    color: rgba(0, 0, 0, .5);
}

Use single quotes for string literals (StringQuotes)

Reduces file size. Double quotes can be used when avoiding escape characters.

Bad

.foo {
    content: "bar";
}

Good

.foo {
    content: 'bar';
}

.foo {
    content: "bar 'baz' qux";
}

End statements with a semicolon (TrailingSemicolon)

Supports best practices. Reduces errors.

Bad

$foo: bar

.foo {
    margin: 10px 0;
    padding: 10px
}

Good

$foo: bar;

.foo {
    margin: 10px 0;
    padding: 10px;
}

Remove whitespace from line endings (TrailingWhitespace)

Reduces file size. Improves diffs.

Don't add unnecessary trailing zeros to measurements (TrailingZero)

Reduces file size.

Bad

.foo {
    font-size: .500em;
}

Good

.foo {
    font-size: .5em;
}

Explicitly specify transitions (TransitionAll)

Improves maintainability. Reduces errors.

Bad

.foo {
    transition: all .5s ease-in;
}

Good

.foo {
    transition: color .5s ease-in,
                margin-bottom .5s ease-in;
}

Measurements should not contain unnecessary decimals (UnnecessaryMantissa)

Reduces file size.

Bad

.foo {
    margin: 1.0em;
}

Good

.foo {
    margin: 1em;
}

Don't use unnecessary parent references (UnnecessaryParentReference)

Reduces file size.

Bad

.foo {
    & > .bar {
       padding: 10px;
    }
}

Good

.foo {
    > .bar {
        padding: 10px;
    }
}

Use relative paths for assets (UrlFormat)

Reduces errors.

Bad

.foo {
    background-image: url('https://foo.com/assets/image.jpg');
}

Good

.foo {
    background-image: url('assets/image.jpg');
}

Wrap URLs in single quotes (UrlQuotes)

Improves readability.

Bad

.foo {
    background-image: url(assets/image.jpg);
}

Good

.foo {
    background-image: url('assets/image.jpg');
}

Prefer functional variables (VariableForProperty)

Improves readability. Improves maintainability. Enforced for:

  • color
  • font
  • font-size
  • font-family
  • background
  • background-color
  • border
  • border-top
  • border-right
  • border-bottom
  • border-left
  • border-radius
  • box-shadow

Bad

.foo {
    color: #ff0000;
    background-color: #00ff00
}

Good

// in settings/_colors.scss
$red: #ff0000 !default;
$green: #00ff00 !default;

// in components/_foo.scss
$foo-color: $red;
$foo-bg-color: $green;

.foo {
    color: $foo-color;
    font-family: $foo-bg-color;
}

Don't use vendor prefixes (VendorPrefix)

Improves developer efficiency. Automatically added by autoprefixer.

Bad

.foo {
    -webkit-transition: none;
    transition: none;
}

Good

.foo {
    transition: none;
}

Don't add a unit for zero values (ZeroUnit)

Reduces file size.

Bad

.foo {
    margin: 0px;
}

Good

.foo {
    margin: 0;
}