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
Figure 1. - Rendre disponible le mapping source dans Chrome.
screenshot
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.