Sass style guide

Stay organized with collections Save and categorize content based on your preferences.

Marketing is only supporting the use of SCSS (main) syntax and not original Sass. http://sass-lang.com/documentation/file.SASS_REFERENCE.html

From the Sass website: Sass (first letter capitalized) is the correct expression as this stands for Syntactically awesome stylesheets whereas SCSS is all caps as it stands for Sassy CSS.

This document should be kept in-sync with the internal Marketing SCSS style guide.


File structure

File extension naming for development in Goro.

.scss            <- containing only uncompiled Sass/SCSS
.css             <- containing only uncompiled css - not to contain Sass/SCSS.
.min.css         <- A collection of scss and css files surrounded by a filter tag.

When using Goro, .scss and .css file types should be checked into the templates directory. All of these should be compiled into one (or more for larger projects) .min.css file.

Large project

project/scss/
    _mixins.scss              <- for mixins and other functional Sass code
    _vars.scss                <- for global variables (if necessary.)
    _extends.scss             <- a collection of base classes to extend.
    _<name>.scss              <- a functional group of Sass in a new file.
    _<component>.scss         <- Sass for specific component (e.g. header.scss)
    <specific-subfolder>/     <- a subfolder for a sub-page or component
          _mixins.scss
          _<name>.scss
project/css/
    <component>.css           <- A file containing un-minified css.
    base.min.css              <- All sass files are included and compiled here in a single filter.

Small project

project/scss/
    _<name>.scss      <- File containing uncompiled Sass, mixins, variables and extends.
project/css/
    <name>.css         <- contains uncompiled project css.
    base.min.css       <- contains a compilation filter that included .scss and .css files.*

* Note that this applies to the files as checked into the templates directory. When exported from Goro, the .min.css file will contain minified and compiled css.


Code structure

  • If the file contains code that is not compiled, place uncompiled items before the filter tag. (e.g. @import, Django tags, etc.)
  • Place variables at the top of the file/filter block
  • Place mixins after the variables
  • Place classes to be extended after mixins
  • Place rulesets, nested selectors and nested media queries after the mixins and extends
  • Place any un-nested media queries after the selectors.
Example default.min.css for medium and larger projects
For Bracket projects
@import '_extends.scss';
@import '_vars.scss';
@import '_mixins.scss';
@import '_base.scss';
For Goro projects
\{\% filter csscomp:"scss" \%\}
  \{\% include "www.google.com/project/scss/_extends.scss" \%\}
  \{\% include "www.google.com/project/scss/_vars.scss" \%\}
  \{\% include "www.google.com/project/scss/_mixins.scss" \%\}
  \{\% include "www.google.com/project/scss/_base.scss" \%\}
\{\% endfilter \%\}
Example base.min.css file for smaller projects.
\{\% filter csscomp:"scss" \%\}
  // Specifications for the fishes.
  $water-blue: #1122ee;
  $fish-green: #bada55;
  $eye-size: 20px;
  $small: 480px;

  // Creates a circle shape based on a size variable.
  @mixin circle($size) {
    border-radius: $size / 2;
    width: $size;
    height: $size;
  }

  .fish-eye {
    color: #000;
    @include circle($eye-size);
    .inner {
      color: #fff;
      margin: $eye-size / 2;
      @include circle($eye-size / 2);
    }
    @media (min-width: $small) {
      // Use a quarter size because the eye looks big on mobile.
      .inner {
        margin: $eye-size / 4;
        @include circle($eye-size / 4);
      }
    }
  }
\{\% endfilter \%\}

* Note that the filter is only required when using Goro


Good practices

Variablize colors and other constant values

When you have a color or constant that is used more than once, make it a variable included at the top of the file or in your project variables file. Using a map is a great way to keep your constants and settings organized and reference-able throughout your stylesheets - particularly in a larger project. Use color constants (or maps for collections of colors) in component-specific variables.

// Color palette.
$light-grey: #e1e5f2;

// Color definitions.
$page-background-color: $light-grey;
$button-text-color: $light-grey;

Try not to nest selectors more than 3 levels deep unless absolutely necessary.

Deep nesting can make it very difficult to trace back where a selector will apply. Be kind and make sure another developer can understand your style and don't make selector nesting more complex than it has to be.

Use provided extends mixins and variables whenever possible

D.R.Y. SCSS is the best and will be the easiest to read. Re-creating mixins and extends will reduce the maintainability of your Sass.


Comments

Use // or /* */ according to the Google javascript style guide.

 // This is a comment that is way too long to be on
 // one line. It will be removed by the compiler but
 // will be visible to developers.
 $color: #fff; // Inline comments are also OK to use.

Use this style for comments at the top of a file for overviews or the description of a section. It will be filtered out of the compiled CSS as well.

/* This comment is several lines long.
 * since it uses the CSS comment syntax,
 * it will appear in the CSS output. Rarely use this. */

Selectors and declarations

  • List @extends first.
  • List declarations second (according to CSS style guide rules)
  • List @includes third (and other @rules).
  • Finally, list all nested selectors.
  • Add a line before and after selectors (according to CSS style guide)
.selector {
  @extend %module;
  [declarations…]
  @include mixin(arg1 arg2 arg3);
  @at-root {
    [selectors...]
  }
  .subselector {
    @extend %module
    [declarations...]
    @include mixin(arg1 arg2 arg3);
  }
}

Nested Properties

Treat nested properties the same as other declarations.

.selector {
  [declarations…]
  font: {
    family: "Open Sans";
    size: 30px;
    weight: bold;
  }
}

@Rules

@import in Goro

If using Goro, do not @import inside the Sass filter compilation block. Use the Django equivalent tag

\{\% include "www.google.com/_filepath.scss" \%\}

If not using Goro, please use @import for all included SCSS files.

@at-root

Place this after the declarations with the other @rules.

@warn and @debug

Do not use these when using Sass in Goro. They won’t work. as designed.


Control Directives and Expressions

@if and @else

Follow the Google js style. Control statements always use brackets followed by a newline.

$animal: whale;
.selector {
  @if $animal == giraffe {
    color: #ff0; // yellow
  } @else if $animal == whale {
    color: #808080; // grey
  } @else if $animal == bear {
    color: #a52a2a; // brown
  } @else {
    color: #000; // black
  }
}

@for loops

Follow the Google js style guide. Always wrap in {} followed by a newline.

 @for $i from 1 through 3 {
   .item-#{$i} { width: 10px + $i; }
 }

@each

Follow Google js style guide. Wrap in {} with a newline after bracket.

@each $animal in 'eagle', 'badger', 'seagull' {
  background-image: url(images/#{$animal}.png);
}

@while

Use newlines after brackets and follow CSS style guide.

$i: 0;
@while $i < 5 {
  .item-#{$i} {
    width: 20px * $i;
  }
  $i: $i + 1;
}

Operators

Use space before and after operators.

$max-width: 1em + (2em * 3);
$min-width: 20px / (2 + (3 * $x));

Mixins and Functions

Place mixins and functions after variables but before selectors at the top of the file.

// Sets the border style (color and width) for an element.
@mixin border($color: #333333, $width: 5px) {
  border: $width solid $color;
}

// A function to get a map property by name.
// Get a breakpoint with:
//     get-breakpoint(small);
@function get-breakpoint($name: small) {
  @return map-get($breakpoints-map, $name);
}
.selector {
  @include border(#0000ff);
}

.selector {
  @include border(#5500ff, 1em);
}

Mixins and functions names should use a dash separator (and not using camelCase or underscores.) A good practice is to add a comment above each mixin or function describing its purpose and maybe an example usage. A set of mixins should be placed in a separate mixins.scss file when they will be re-used in one or more css or scss files.


Variables

Since Sass doesn’t scope variables, always use a unique variable name. Use a descriptive variable name. Use a dashed style to separate words to be consistent with general Sass style and CSS selector style.

$head_r                       No    use a descriptive name
$camelCaseComponent           No    don’t use camel-case
$_many_underscores            No    just dashes, no underscores

$header-background-color      Yes
$lightbox-top-offset          Yes

Namespace your variables when they might conflict with other variables - particularly where the scss is intended to be reusable and might be included for compilation with other scss files. For example, a common variable name like $small could easily be overwritten by another file.

Variable Formatting

$var: value;
$project-var-name: value;    // namespaced variable. e.g. $sometrek-border-color: #dddddd

Variable data types

// numbers: use value and optional unit
$num: 10;
$num: 2rem;

// strings: use single quotes.
$string: 'this is some text';
$animal: 'monkey';

// colors: use any color expression according to Google’s HTML/CSS Style Guide.
$color: #c0ffee;
$color: hsl(164, 100%, 88%);
$color: rgba(192, 255, 238, .5);

// booleans
$var: true;
$var: false;

// nulls (e.g. null)
$var: null;

Lists

Commas are preferred for separating lists for better readability.

$animals: 'monkey', 'hippo', 'squirrel';

List functions use similar syntax to JS functions. Use a comma followed by a space to separate arguments.

$i: index($animals, 'hippo');

Maps

Use the following format:

$map: (key1: value1, key2: value2, key3: value3);

Media Queries

Nest media queries whenever possible. When nesting media queries, place them at the bottom of the CSS selector block and order them by size smallest to largest. Add other types of queries before these (e.g. pixel ratio selectors.) Add a newline before nested media queries.

If a media query can’t be nested, media queries should be placed at the bottom of the CSS file. If there is a mixin for a certain media query available, always use that to keep the media query usage consistent throughout all scss and css files. Example:

.selector {
  [declarations...]
  .nested-selector {
    [declarations...]
    @media screen and (max-size: 350px) {
      [selectors…]
    }
  }

  @media screen and (-webkit-min-device-pixel-ratio: 1.5) {
    [selectors...]
  }
  @media screen and (max-size: 350px) {
    [selectors…]
  }
  @media screen and (min-size: 960px) {
    [selectors…]
  }
}
// Global media queries.
@media screen and (min-size: 960px) {
  [selectors…]
}