npm package: @songkick/stylelint-config-songkick
Description: Boilerplate configuration for Stylelint CSS linter
Author: Songkick
Latest version: 1.0.0

# Songkick stylelint Config

A boilerplate configuration for [stylelint](https://github.com/stylelint/stylelint/), with SCSS syntax linting by [stylelint-scss](https://github.com/stylelint/stylelint/).

___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:

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

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

```json
{
    "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:

```json
{
    "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](https://github.com/CrowdSurge/stylelint-config/blob/master/CONTRIBUTING.md) guide before working on this project.