Songkick stylelint Config

A boilerplate configuration for stylelint, with SCSS syntax linting by stylelint-scss.

This project is currently an experimental WIP. For the most part it follows existing Songkick and some former CrowdSurge CSS patterns. We'll gradually add/remove rules as we work out what does and doesn't work for us.

What will this do?

This linter is designed to enforce syntax and coding style - rather than any specific architectural patterns. It will generally not force you to write your CSS to fit a certain methodology or practice, but will make sure that CSS is written in a way that looks consistent and familiar across projects.

 Installation and Configuration

In your project run:

npm install stylelint stylelint-scss @songkick/stylelint-config-songkick --save-dev

Add a .stylelintrc file to your project which extends this configuration:

{
    "extends": "@songkick/stylelint-config-songkick"
}

Where the linting rules don't suit a certain project, or cause issues when including the linter in an existing codebase, you can also override and add to these rules as required:

{
    "extends": "@songkick/stylelint-config-songkick",
    "rules": {
        "indentation": 2,
        "declaration-no-important": true
    }
}

Full documentation on the stylelint config file can be found here: http://stylelint.io/user-guide/configuration/#the-configuration-object

Enforced CSS Lints

Indentation

• 4-space soft tabs by default.

Case

• All lowercase everything;
  • Selectors; types, pseudo-selectors (eg. a, div, :hover)
  • Property names (eg. width, height, margin)
  • @-rules (eg. @media, @keyframe)
  • Function names (eg. scale(0.5))
  • Units (eg. px, em, s)
  • Hex codes (eg. #f80046)
• Uppercase only where required; eg. URLs, typeface names.

Rule Structure

• Every rule must be on it's own line. Always include an additional empty line between multi-line rules.
• Include a space between the final selector and the opening brace of a rule.
• The closing brace of a multi-line rule must be on it's own line.

Selector Structure

• Selectors cannot be qualified with an element type. (ie. div.class-name - Note: This excludes attribute selectors).
• Each selector must be placed on a new line.
• In descendent selectors only a single space should separate each. No newlines.
• In multiple selector rules, place the comma at the end of the selector name.

Declaration Structure

• The colon in a declaration must have a space after, but not before (ie. width: 123px;).
• When declaring !important, you must place a space before, but never after the bang. (ie. width: 123px !important;).
• Shorthand properties that override longhand properties will error (eg. Using margin property in a rule after margin-left).
• Rules with multiple declarations must have each on a new line.
• Semicolons must be on the same line as their declaration.
• Always close a declaration with a semicolon - including the last.

@-rules

• Each rule must be on it's own line.
• Include a space after the name of the @-rule (ie. @media (min-width ...)).
• Include a space after the colon of a feature (eg. min-width: 123px).

Functions

• Include a space after each comma in functions where multiple values occur (eg. skew(30deg, 20deg)).
• When declaring multiple functions, include a space between each (eg. transform: scale(1.5) rotateX(10deg);).
• Don't use quotes when declaring URLs (ie. background-image: url(foo.jpg);)

Values

• Don't use multiple redundant shorthand values (eg. margin: 1px 1px 1px 1px; should be margin: 1px;)

 Units

• Don't use units on length values which are zero (ie 0px > 0).
• Units should have no more than 2 decimals of precision (ie. 1.23px).
• Do use leading zeroes in fractional numbers less than 1 (ie. 0.5px).
• Don't use trailing zeroes in fractional numbers (eg. 1.50px).

Fonts

• Use quotes around font names that require it (eg. "Proxima Nova"), not around ones that don't (eg. Arial).

Contributing

Please read the included Contribution Guidelines guide before working on this project.