CSS / SCSS Style Guide

Package name: stylelint-config-neurony

Setup

1. In project root run:

npm i stylelint-config-neurony

Configuration

In your project root run:

npm i -g stylelint
npm i stylelint-config-neurony --save-dev

In your project root create a file called .stylelintrc and paste this into it:

{   
  "extends": "stylelint-config-neurony"
}

In this file you can specify any extra rules or settings.

4. Append this line to package.json scripts: (your js path may differ)

"stylelint": "stylelint resources/assets/sass/front/*.scss --fix",

Running

npm run stylelint

Documentation

There are some rules in place that are undocumented here. They keep you from writing invalid css, using invalid media queries etc.

Should I use [BEM] (http://getbem.com/) or not?

If you're the one who starts the project, it's your choice. This guide does not interfere with it. It's the responsibility of the future developers to adhere to naming conventions already in place.

Formatting

stylelint: at-rule-name-space-after block-opening-brace-space-before block-opening-brace-newline-after block-closing-brace-newline-before

Those rules will enforce you write clean CSS like:

    .class-name {
        color: black;
    }

Maximum nesting 4 levels

stylelint: max-nesting-depth

Your rules are getting way to specific above those levels and will never be reused. It's also difficult to read when stylesheets become long.

    .class {
        .some-class {
            .getting-deep {
                stop-here {
                
                }
            }
        }
    }

No ID selectors

stylelint: selector-max-id

Your rules can not be reused this way.

#not-cool {
    display: none
}

Prefer dashed named variables for scss

Your variables names should also contain the group they belong to as the first word.

$font-size-subtitle: 18px;
$color-darkgray: #2f2f2f;

Use z-index with variables

It's recommended that you assign your z-index values to variables with names that give a hint of the value and intent. Easier to keep track what's on top of what, rather than using magic numbers.

    $z-index-navmenu: 10;
    $z-index-alert: 100;
    $z-index-popup: 1000;

Comments

Prefer one line comments for properties/classes with a space between slashes and first word.

   // comment

Prefer block comments for explanations at the beggining of the module. (if necessary)

 /* block comment 
    probably multiline
 */    

Javascript Hooks

Even if you are not using [BEM] (http://getbem.com/), you should avoid binding to the same class in both your JavaScript and CSS. Conflating the two often leads to, at a minimum, time wasted during refactoring when a developer must cross-reference each class they are changing, and at its worst, developers being afraid to make changes for fear of breaking functionality. JS hooks should use a camelCased name prefixed with js-.

    <button class="js-startSlideshow"> </button>