Skip to content

Latest commit

 

History

History

sass

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
.stylelintrc.json
.stylelintrc.json
 
 
README.md
README.md
 
 
sample.scss
sample.scss
 
 

README.md

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 F5 to sort lines alphabetically.