#### Table des matières

* [Formatting Rules](#formattingRules)
  + [Programming](#programming)
  + [Indentation](#indentation)
  + [Scaffold](#scaffold)
  + [Selectors](#selectors)
  + [Property value pair](#propertyValuePair)
* [Style Rules](#styleRules)
  + [File System Architecture](#fileSystemArchitecture)
  + [Stylesheets](#stylesheets)
  + [Comments](#comments)
  + [Namespace](#namespace)
  + [Naming](#naming)
  + [Naming convention](#namingConvention)
  + [Selector](#selector)
  + [Selector Performance](#selectorPerformance)
  + [Inheritance](#inheritance)
  + [Ordering](#ordering)
  + [Shorthand properties](#shorthandProperties)
  + [Vendor Prefixes](#vendorPrefixes)
  + [Colors](#colors)
* [Links](#links)

[Back to top](#top)

# CSS Guideline

## Formatting Rules

### Programming

Programmez en **anglais**.

### Indentation

Utilisez une indentation de 4 espaces.

N'utilisez pas de tabulations.

```

// Recommended
.selector {
    color: #FFFFFF;
}

```

### Scaffold

Ajoutez une ligne vide entre chaque bloc de déclaration.

```

// Not Recommended
.selector1 {
}
.selector2 {
}

```
```

// Recommended
.selector1 {
}

.selector2 {
}

```

### Selectors

Utilisez la syntax **semi-expanded** pour chaque bloc de déclaration.

\*Exception, la syntaxe **collapsed** est autorisée lorsque qu'il n'y a qu'une seule déclaration par bloc.

```

// Not Recommended
.selector {}

```
```

// Recommended
.selector {
}

```

Ajoutez un espace après le dernier sélecteur.

```

// Not Recommended
.selector{
}

```
```

// Recommended
.selector {
}

```

Ecrivez chaque sélecteur sur une nouvelle ligne.

```

// Not Recommended
.selector1, .selector2, .selector3 {
}

```
```

// Recommended
.selector1,
.selector2,
.selector3 {
}

```

Les sélecteurs ciblant un élément HTML doivent être écrit en **lowercase**.

```

// Not Recommended
A {
}

```
```

// Recommended
a {
}

```

Les sélecteurs ciblant la valeur d'un attribut doivent entourer la valeur de l'attribut par des doubles quotes.

```

// Not Recommended
input[type=text]
}

```
```

// Recommended
input[type="text"] {
}

```

### Property-Value Pair

Chaque déclaration est composée d'une propriété et d'une valeur.

Ecrivez chaque déclaration sur une nouvelle ligne.

```

// Not Recommended
.selector {
    padding: 10px; margin: 5px;
}

```
```

// Recommended
.selector {
    padding: 10px;
    margin: 5px;
}

```

Les propriétés doivent être suivies d'un double point (**:**) et d'un espace.

Chaque déclaration se termine par un point-virgule (**;**).

```

// Not Recommended
.selector {
    position:absolute;
    left:0;
    top:0
}

```
```

// Recommended
.selector {
    position: absolute;
    left: 0;
    top: 0;
}

```

Les propriétés et les valeurs doivent être écrites en **lowercase**.

\*Exception: pour les **fonts name** et les propriétés **vendor-specific**.

```

// Not Recommended
.selector {
    FONT-SIZE: 12PX;
}

```
```

// Recommended
.selector {
    font: 12px;
}

```

Les valeurs multiples doivent être séparée par une virgule suivi d'un espace.

Les valeurs multiples verbeuses peuvent être indentées sur plusieurs lignes si nécessaire.

```

// Not Recommended
.selector {
    font-family: Helvetica,sans-serif;
}

```
```

// Recommended
.selector {
    font-family: Helvetica, sans-serif;
}

```
```

// Recommended
.selector {
    background-image:
        linear-gradient(#fff, #ccc),
        linear-gradient(#f3c, #4ec);
    box-shadow:
        1px 1px 1px #000,
        2px 2px 1px 1px #ccc inset;
}

```

Les valeurs contenant un espace doivent être entourés par une double quote.

```

// Not Recommended
.selector {
    font-family: Lucida Grande, sans-serif;
}

```
```

// Recommended
.selector {
    font-family: "Lucida Grande", sans-serif;
}

```

Les urls ne doivent pas être entourées par une double quote.

```

// Not Recommended
.selector {
     background-image: url("images/image.jpg");
}

```
```

// Recommended
.selector {
    background-image: url(images/image.jpg);
}

```

## Style Rules

### File System Architecture

Organisez votre code css comme ci-dessous:

```

// Recommended
css/
|-- base/
|   |-- reset.css
|   |-- typography.css
|   |-- animations.css
|   ...
|-- components/
|   |-- buttons.css
|   |-- carousel.css
|   |-- gallery.css
|   |-- dropdown.css
|   ...
|-- layout/
|   |-- navigation.css
|   |-- grid.css
|   |-- header.css
|   |-- footer.css
|   |-- sidebar.css
|   |-- forms.css
|   ...
|-- pages/
|   |-- home.css
|   |-- about.css
|   |-- contact.css
|   ...
|-- themes/
|   |-- theme.css
|   |-- admin.css
|   ...
|-- vendors/
|   |-- bootstrap.css
|   |-- jquery-ui.css
|   ...
 - main.css

```
#### 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.

### Stylesheets

N'écrivez pas de code **inline style**.

Utilisez des feuilles de style externe.
\*Exception pour les changements dynamique de style via un script.

Séparez le code par module ou par section dans différents fichiers.

Ces règles sont un point cruciale à respecter pour des raisons de maintenance.

```

// Not Recommended
<p style="font-weight: bold; color: #333;"> ... </p>

```
```

// Recommended
// In stylesheet site.css
.class {
    font-weight: bold;
    color: #333;
}
// In view index.html
<p class="class"> ... </p>

```

### Comments

Commentez le code lorsque cela est nécessaire.

Utilisez les commentaires pour expliquer le code; lorsque celui-ci est complexe, si le code présente des limites ou lorsque qu'une correction a dû être apportée.

Utilisez les commentaires pour marquer une action a faire; TODO, TOREMOVE, TOMOVE, TOFIX, ...

Aidez vous des commentaires pour identifier les différentes sections si cela est nécessaire.

Ajoutez un espace entre le délimiteur de commentaire et le texte du commentaire.

```

// Recommended
// This is a short comment
/**
 * TODO: This is a todo statement that describes
 * an task to be completed later.
 */

/* ==========================================================================
   Section
   ========================================================================== */
/* Sub-section
   ========================================================================== */

```

### Namespace

Si nécessaire, utilisez un préfixe devant chaque classe css afin de simuler un **namespace** et ainsi éviter les collisions de style.

```

// Recommended
.ns-class {
}

```

### Naming

Utilisez un sélecteur clair et lisible qui décrit l'élément sur lequel le style est appliqué.

**N'utilisez pas un sélecteur décrivant le style appliqué.**

\*Exception, un nom decrivant le style appliqué est autorisé pour les classes utilitaires.

```

// Not Recommended
.frame-red-bordered {
    background-color: #f2dede;
    border: 1px solid #ebccd1;
    color: #a94442;
}

.left-blue-menu {
}

.small-footer-links {
}

.blue {
}

.bold {
}

```
```

// Recommended
.danger {
    background-color: #f2dede;
    border: 1px solid #ebccd1;
    color: #a94442;
}

.secondary-menu {
}

.sub-links {
}

.primary-color {
}

.highlight-text {
}

```

### Naming convention

Utilisez le lower hyphens case pour le nom des composants.

```

// Recommended
.box { }
.button { }

```

Utilisez le lower hyphens case pour le nom des sous-composants.

Précédez le nom des sous-composants par le nom du composant séparé par un trait d'union (-) ou un trait de soulignement (\_).

```

// Not Recommended
.box .title { }
.button .icon { }

```
```

// Recommended
.box-title { }
.button-icon { }

```
```

// Recommended
.box_title { }
.button_icon { }

```

Utilisez le lower hyphens case pour le nom des modifiers.

Suivez le nom des modifiers par le nom du composant séparé par un trait d'union (-).

```

// Not Recommended
.box.x-large { }
.button.default { }
.button-icon.small { }

```
```

// Recommended
.x-large-box { }
.default-button { }
.button-icon.small-icon { }
.button_icon.small-icon { }

```

Préfixez les classes utilitaires par la lettre "u" suivit d'un trait d'union (-).

Une classe utilitaire ne devrait contenir qu'une seule définition par classe.

Une classe utilitaire peut utiliser le hack !important pour surcharger un style existant.

```

// Not Recommended
.text-center {
    text-align: center;
}

.u-highlight-text {
    background-color: yellow;
    font-weight: bold;
}

.u-red-border {
    border: 1px solid #ebccd1;
}

```
```

// Recommended
.u-text-center {
    text-align: center !important;
}

.u-highlight-text {
    background-color: yellow !important;
}

.u-text-bold {
    font-weight: bold !important;
}

.u-border {
    border: 1px solid;
}

.danger-box {
    border-color: red;
}

```

Préfixez les classes thèmes par la lettre "t" suivit d'un trait d'union (-).

```

// Recommended
.t-dark-blue {
    background-color: #333;
}

```

Préfixez les états par les lettres "is", "has", "can" suivit d'un trait d'union (-).

Les états peuvent être affecté à l'élément html via l'attribut `class="..."` ou via l'attribut `data-state="..."`.

```

// Not Recommended
.disabled { }
.selected { }
[data-collapse="true"] { }

```
```

// Recommended
.is-disabled { }
.is-selected { }
[data-state="is-collapse"] { }

```

Préfixez les classes behavior avec les lettres "js" suivit d'un trait d'union (-).

Cette classe a pour but de servir de sélecteur marqueur pour le javascript.

N'utilisez pas ce selecteur pour styliser l'élément.

```

// Not Recommended
.js-accordeon {
    border: 1px solid #DDD;
}

```

Préfixez les workarounds et les hacks par un trait de soulignement (\_).

```

// Not Recommended
.ie-clip-path { }
.clearfix { }

```
```

// Recommended
._ie-clip-path { }
._clearfix { }

```

### Selector

N'utilisez pas un sélecteur "surqualifié".

N'ajoutez pas le nom d'un élément ou le nom d'une classe à un sélecteur par ID.

```

// Not Recommended
div#id.class {
}

```
```

// Recommended
#id {
}

```

N'ajoutez pas le nom d'un élément à un sélecteur par classe.

```

// Not Recommended
div.class {
}

```
```

// Recommended
.class {
}

```

Evitez les sélecteurs descendants.

Préférez les sélecteurs spécifiques les plus court possible.

```

// Not Recommended
html body #table > tbody > tr.odd {
}

```
```

// Recommended
.odd-row {
}

```

### Selector Performance

Rappel: le système de matching des règles css lit les sélecteurs de droite à gauche.

Restez particulièremenet attentif au **key selector** c'est-à-dire à la dernière partie du sélecteur.

C'est un point crucial dans les performance du rendu d'une page HTML.

Evitez l'utilisation des sélecteurs universels.

```

// Not Recommended
* {
}

[hidden="true"] {
}

tree > [collapsed="true"] {
}

```

### Inheritance

Exploitez la mécanique de hériarchie de styles pour simplifier votre code.

```

// Not Recommended
#bookmark > .bookmark-item {
    list-style-image: url(path/image.png)
}

```
```

// Recommended
#bookmark {
    list-style-image: url(path/image.png)
}

```

### Ordering

Regroupez logiquement les déclarations par type en suivant cet ordre :

* Display
* Positioning
* Box model
* Typography and colors
* Other

Gardez l'ordre suivant pour les propriétés exploitant les directions :

* Top
* Right
* Bottom
* Left

```

// Not Recommended
.selector {
    color: #000;
    z-index: 1;
    left: 0;
    top: 0;
    position: absolute;
    font-family: serif;
    margin-left: 10px;
    border: 1px solid #333;
    display: inline-block;
    padding: 4px;
    background-image: url(path/image.jpg);
    width: 50%;
    min-height: 150px;
    cursor: pointer;
}

```
```

// Recommended
.selector {
    // Display
    display: inline-block;
    // Positioning
    position: absolute;
    top: 0;
    left: 0;
    z-index: 1;
    // Box model
    width: 50%;
    min-height: 150px;
    margin-left: 10px;
    padding: 4px;
    border: 1px solid #333;
    background-image: url(path/image.jpg);
    // Typography and colors
    font-family: serif;
    color: #000;
    // Other
    cursor: pointer;
}

```

### Shorthand properties

Utilisez les super propriétés quand cela est possible.

```

// Not Recommended
.selector {
    margin-top: 4px;
    margin-right: 8px;
    margin-bottom: 4px;
    margin-left: 8px;
}

```
```

// Recommended
.selector {
    margin: 4px 8px;
}

```

### Vendor Prefixes

Evitez les **vendor prefixes** sauf si cela est nécessaire.

Ajoutez toujours en dernier la propriété standard.

```

// Not Recommended
.selector {
    webkit-text-size-adjust: 100%;
}

```
```

// Not Recommended
.selector {
    -moz-border-radius: 4px;
    -ms-border-radius: 4px;
    -webkit-border-radius: 4px;
}

```
```

// Recommended
.selector {
    -moz-border-radius: 4px;
    -ms-border-radius: 4px;
    -webkit-border-radius: 4px;
    border-radius: 4px;
}

```

### Colors

Utilisez la notation hexadecimal.
Toutes les lettres doivent être écrites en **uppercase**.

Privilégiez la notation courte pour les couleurs hexadecimal lorsque cela est possible.

Utilisez la notation rgba() pour préciser la couleur et la transparence d'une couleur (alpha).

```

// Recommended
.selector {
    color: rgba(0, 0, 0, .25);
    border-color: #D1D1D5;
    background-color: #FFF;
}

```

## Links

Bibliographie (Resources utilisées) :

* [idiomatic-css](https://github.com/necolas/idiomatic-css)
* [Mozilla Developer Network: Writing efficient Css](https://developer.mozilla.org/en-US/docs/Web/Guide/CSS/Writing_efficient_CSS)
* [Google: Css style rules](https://google.github.io/styleguide/htmlcssguide.xml#CSS_Style_Rules)
* [ThinkUp: Css Code Style Guide](https://github.com/ThinkUpLLC/ThinkUp/wiki/Code-Style-Guide%3A-CSS)
* [Wordpress: CSS Coding Standards](https://make.wordpress.org/core/handbook/best-practices/coding-standards/css/)
* [Primer: Guidelines](http://primercss.io/guidelines/)
* [css {guide: lines;}](http://cssguidelin.es/)
* [OOCSS](http://oocss.org/)
* [SMACSS methodology](https://smacss.com/)
* [BEM methodology](https://en.bem.info/methodology/quick-start/)
* [Css naming namespace](https://csswizardry.com/2015/03/more-transparent-ui-code-with-namespaces/)