Sass

• Sample

• Shared stylelint configuration

  • This configuration aligns with our team-wide guides below. It does not, however, enforce a particular class naming structure, which is a team decision to be made on a per-project basis.

• When using sass-rails, use the provided asset-helpers (e.g. image-url and font-url), so that Rails' Asset Pipeline will re-write the correct paths to assets.

• Prefer mixins to @extend.

• Use maps and variables to codify and centralize breakpoint values

  • Prefer abstract names such as small, medium, large, etc. instead of specific devices
  • Nest breakpoints inside of the relevant selector
  • If a component needs a specific breakpoint to work, keep it with the relevant component partial. If other components need the same value, integrate it into the centralized breakpoint list

Formatting

• Use the SCSS syntax.
• Use hyphens when naming mixins, extends, functions & variables: span-columns not span_columns or spanColumns.
• Avoid using shorthand properties for only one value: background-color: #ff0000;, not background: #ff0000;
• Use // for comment blocks not /* */.
• Avoid in-line operations in shorthand declarations (Ex. padding: $variable * 1.5 variable * 2)
• Use parentheses around individual operations in shorthand declarations: padding: ($variable * 1.5) ($variable * 2);
• Use a % unit for the amount/weight when using Sass's color functions: darken($color, 20%), not darken($color, 20)
• Use a trailing comma after each item in a map, including the last item.

Selectors

• Use meaningful names: $visual-grid-color not $color or $vslgrd-clr.
• Use ID and class names that are as short as possible but as long as necessary.
• Avoid nesting more than 3 selectors deep.
• Avoid using comma delimited selectors.
• Avoid nesting within a media query.

Organization

• Use a base directory for styling element selectors, global variables, global extends and global mixins.
• Use HTML structure for ordering of selectors. Don't just put styles at the bottom of the Sass file.
• Avoid having files longer than 100 lines.

General syntax and formatting

Declarations block ordering

• Order declarations alphabetically.
• Order items within the declaration block in the following order:
  1. Sass at-rules, e.g. @include
  2. CSS properties
  3. Media queries
  4. Pseudo-classes
  5. Pseudo-elements
  6. Nested elements

Code examples

Alphabetize declarations:

.class {
  display: block;
  text-align: center;
  width: 100%;
}

Alphabetize prefixed properties as if the prefix doesn't exist:

.class {
  font-family: system-ui;
  -webkit-font-smoothing: antialiased;
  font-weight: $weight-variable;
}

Comprehensive example of ordering items within a declaration block:

.class {
  @include size(10px);

  display: block;
  margin: $spacing-variable;

  @media (min-width: $screen-variable) {
    padding: $spacing-variable;
  }

  &:focus {
    border-color: $color-variable;
  }

  &::before {
    content: "";
  }

  .nested-element {
    margin: $spacing-variable;
  }
}

Motivation

Alphabetizing can be automated and is commonly a feature built into code editors (see Resources below).

Linting

Alphabetical declaration ordering can be linted using stylelint with the stylelint-order plugin and its order/properties-alphabetical-order rule.

Resources

• Atom users can use the Sort Lines package, which provides commands and keybindings for alphabetical sorting.
• Sublime Text users can use the Edit > Sort Lines menu item, or press <kbd>F5</kbd> to sort lines alphabetically.