#### Table des matières

* [Formatting Rules](#formattingRules)
* [Style Rules](#styleRules)
  + [File System Architecture](#fileSystemArchitecture)
  + [Declaration Order](#declarationOrder)
  + [Nesting](#nesting)
  + [Variables](#variables)
  + [Media queries](#mediaQueries)
  + [Compile with source map](#compileSourceMap)
  + [Don't commit css files](#commitCssFiles)
* [Links](#links)

[Back to top](#top)

# SASS Guideline

## Formatting Rules

Le formattage Sass doit suivre toutes les règles de formatage appliquées au CSS.

## Style Rules

Les règles directrices de Sass doivent suivre toutes les règles directices appliquées au CSS.

### File System Architecture

Utilisez le 7-1 Pattern (7 folders, 1 file) pour organiser votre code sass.

```

// Recommended
sass/
|-- abstracts/
|   |-- _variables.scss    # Sass Variables
|   |-- _functions.scss    # Sass Functions
|   |-- _mixins.scss       # Sass Mixins
|   |-- _placeholders.scss # Sass Placeholders
|-- base/
|   |-- _reset.scss        # Reset/normalize
|   |-- _typography.scss   # Typography rules
|   |-- _animations.scss   # Animation keyframes definitions
|   ...                    # Etc.
|-- components/
|   |-- _buttons.scss      # Buttons
|   |-- _carousel.scss     # Carousel
|   |-- _gallery.scss      # Cover
|   |-- _dropdown.scss     # Dropdown
|   ...                    # Etc.
|-- layout/
|   |-- _navigation.scss   # Navigation
|   |-- _grid.scss         # Grid system
|   |-- _header.scss       # Header
|   |-- _footer.scss       # Footer
|   |-- _sidebar.scss      # Sidebar
|   |-- _forms.scss        # Forms
|   ...                    # Etc.
|-- pages/
|   |-- _home.scss         # Home specific styles
|   |-- _about.scss        # About specific styles
|   |-- _contact.scss      # Contact specific styles
|   ...                    # Etc.
|-- themes/
|   |-- _theme.scss        # Default theme
|   |-- _admin.scss        # Admin theme
|   ...                    # Etc.
|-- vendors/
|   |-- _bootstrap.scss    # Bootstrap
|   |-- _jquery-ui.scss    # jQuery UI
|   ...                    # Etc.
 - main.scss               # Main Sass file

```
#### Pages style and deployment

Les fichiers de style spécifiques à une page peuvent ne pas être fusionnés dans le fichier main.scss. Il faut alors les référencés directement dans la page HTML.

#### Themes folder is optional

L'existence du dossier thème est spécifique à chaque projets. Il est donc normal que le dossier thème n'existe pas dans le projet si cela n'est pas nécessaire.

#### Main file

Le fichier main.scss devrait contenir uniquement des `@import` et des commentaires.

###### Exemple de fichier main.scss

```

// Recommended
@import 'abstracts/variables';
@import 'abstracts/functions';
@import 'abstracts/mixins';
@import 'abstracts/placeholders';

@import 'vendors/bootstrap';
@import 'vendors/jquery-ui';

@import 'base/reset';
@import 'base/typography';

@import 'layout/navigation';
@import 'layout/grid';
@import 'layout/header';
@import 'layout/footer';
@import 'layout/sidebar';
@import 'layout/forms';

@import 'components/buttons';
@import 'components/carousel';
@import 'components/cover';
@import 'components/dropdown';

@import 'pages/home';
@import 'pages/contact';

@import 'themes/theme';
@import 'themes/admin';

```

### Declaration Order

Listez en premier les déclarations **@extend**.

```

// Recommended
.selector {
  @extend %module;
  ...
}

```

Listez en suite les déclarations **@include**.

```

// Recommended
.selector {
  @extend %module;
  @include transition(all 0.3s ease-out);
  ...
}

```

Listez en suite les déclarations **standards**.

```

// Recommended
.selector {
  @extend %module;
  @include transition(all 0.3s ease-out);
  display: inline-block;
  ...
}

```

Listez en suite les **pseudo-éléments** et les **pseudo-classes**.

```

// Recommended
.selector {
  @extend %module;
  @include transition(all 0.3s ease-out);
  display: inline-block;

  &:hover {
    text-decoration: underline;
  }

  &::before {
    display: block;
    content: "text";
  }
  ...
}

```

Listez enfin les **sélecteurs imbriqués**.

```

// Recommended
.selector {
  @extend %module;
  @include transition(all 0.3s ease-out);
  display: inline-block;

  &:hover {
    text-decoration: underline;
  }

  &::before {
    display: block;
    content: "text";
  }

  .selector-nested {
    @include transform(rotate(90deg));
    background-image: url(path/image.jpg);
  }
}

```

### Nesting

Ne dépassez pas trois niveaux d'imbrications.

Evitez l'imbrication des sélecteurs sauf si cela s'avère nécessaire.

Imbriquez les pseudo-classes et les pseudo-éléments à l’intérieur du sélecteur initial.

Ne dépassez pas les 50 lignes de codes pour un bloc de déclaration.

### Variables

Nommez vos variables en respectant le pattern Generic to Specific.

```

// Not Recommended
$border-color;
$dark-border-color;
$light-color-border;
$highlight;
$link;
$link-dark;
$text;
$color-text;
$link-color-light;
$lightest-text-color;

```
```

// Recommended
$color-border;
$color-border-dark;
$color-border-light;

$color-highlight;

$color-link;
$color-link-dark;
$color-link-light;

$color-text;
$color-text-light;
$color-text-lightest;

```

Stockez tous les nombres propre à votre application dans des variables.

```

// Not Recommended
.header {
  z-index: 2000;
}
.overlay {
  z-index: 5000;
}
.message {
  z-index: 5050;
}

```
```

// Recommended
$zHeader: 2000;
$zOverlay: 5000;
$zMessage: 5050;
.header {
  z-index: $zHeader;
}
.overlay {
  z-index: $zOverlay;
}
.message {
  z-index: $zMessage;
}

```

Stockez toutes les couleurs dans des variables.

Si vous voulez nuancer les couleurs, utlisez les fonctions couleurs de Sass.

```

// Not Recommended
.selector {
    color: #ABCD56;
}

```
```

// Recommended
$colorSecondary: #ABCD56;
.selector {
    color: $colorSecondary;
}

```

### Media queries

Privilégiez l'approche **mobile first** dans le cas ou vous développez une application **responsive design**.

Ajoutez des **breakpoints** pour styliser le rendu pour des devices spécifiques.

Nommez et imbriquez vos **breakpoints** afin de gagner en maintenance et en lisibilité.

```

// Not Recommended
.selector{
    ...
    @media screen and (max-width: 1024px) {
        ...
    }
}

```
```

// Recommended
@mixin breakpoint($name) {
  @if $name == "small" {
    @media (max-width: 767px) {
      @content;
    }
  }
  @else if $name == "medium" {
    @media (max-width: 1024px) {
      @content;
    }
  }
  @else if $name == "large" {
    @media (min-width: 1025px) {
      @content;
    }
  }
}
.selector{
    ...
    @include breakpoint("medium"){
        ...
    }
}

```

### Compile with source map

Dans un environnement de développement, ajoutez les sources map via l'attribut --sourcemap dans la commande de compilation
pour bénéficier d'un mapping du code au travers des outils de développement.

`$ sass sass/screen.scss:stylesheets/screen.css --sourcemap`

![Animation explicative](images/chrome-enable-source-map.gif)

Figure 1. - Rendre disponible le mapping source dans Chrome.

![screenshot](images/view-original-source.gif)

Figure 2. - Zoom sur le débuggueur de code sass dans Chrome.

### Don't commit css files

Ne sauvegardez pas les fichiers css sur un système de **source control**.

En effet, les fichiers css seront produit à partir des fichiers Sass lors de la compilation avant le déploiement.

## Links

Bibliographie (Resources utilisées) :

* [Sass Guidelines](http://sass-guidelin.es/fr/)
* [css-tricks.com: Sass Style Guide](https://css-tricks.com/sass-style-guide/)
* [Primer: Guidelines](http://primercss.io/guidelines/)