Code Guidelines

1.1 Architecture Front-End SCSS

Les fichiers SCSS sont organisés selon la méthodologie de l’Atomic Design.

L’alignement sur un vocabulaire partagé est essentiel pour la collaboration entre les équipes produits. Pour cela nous utiliserons la méthodologie de l'Atomic Design de Brad Frost pour nommer notre framework UI. Il est impératif que nos conventions de nommage utilisées dans Sketch correspondent à celles de notre base de code. C’est la garantie que nos ingénieurs, nos designers et nos chefs de produits utilisent tous le même jargon.

1.2 Dossiers SCSS

Nous utilisons la convention de nommage BEMIT (BEM + ITCSS), pour nommer les composants d'une manière facile et compréhensible.

ITCSS (Inverted triangle CSS : Cette convention nous permet de définir la structure des fichiers SCSS selon la méthodologie de l’Atomic design de la manière suivante :

_functions // Fonctions gobales
_helpers // « Class » utilitaire, idéalement préfixés avec h-

_mixins // Vous définissez ici des fonctions et des mixins globalement utilisés, tel que des mixins de taille de police, des fonctions d'assistance rem… etc.

_settings // C'est là que se trouvent tous les paramètres spécifiques au projet. Vous définissez ici les couleurs, les tailles de police, les familles de polices… etc.

@fonts // Déclarations @font-face
base // Normaliser, réinitialiser les styles… etc.
grid // Pour le système de grille… etc.

atoms // Éléments HTML de base et tout ce qui ne peut pas être réduit, idéalement préfixés avec a-
molecules // Combinaisons d’atomes, idéalement préfixés avec m-
organisms // Combinaisons d'atomes et de molécules, idéalement préfixés avec o-
layouts // Partie générique de l’interface
vendor // Fichier CSS où Sass provenant de librairies externes comme Bootstrap où jQuery par exemple.

1.3 SCSS syntax

Namespacing

Chaque « class » est préfixé par un préfixe général : amui- (Cela permet d’éviter tout conflits avec du CSS provenant de librairies externes).

En plus d'un nom global, nous pouvons ajouter des préfixes à chaque « class » pour les rendre plus clair :

• is-- pour les états, comme par exemple .amui-alert .is--active ou .amui-alert .is--disabled.
• js-- pour cibler les fonctionnalités JavaScript, comme par exemple .js--modal-trigger.

BEM (Block Element Modifier)

Présentation officielle de la méthodologie BEM

Cette méthodologie nous permet de nommer nos composants et ainsi de créer un lien entre le code et la méthodologie de l’Atomic Design.

L’idée est de suivre des conventions pour rendre tous les éléments de la page modulaire, ce qui facilite la réutilisation et la maintenance des éléments ainsi que d’être plus descriptif et compréhensible.

Suivant la méthodologie BEM nos Blocks, Elements et Modifiers sont écrits de la manière suivante (x représente le préfixe des dossiers) :

NB : Notre syntaxe SCSS utilise la version modifiée suivante de BEM pour créer les « modifier » :

• Avec BEM : .block--modifier
• Avec notre syntaxe : .block.is--modifier

• .amui-x-block {}
  block représente la racine de l’élément

• .amui-x-block__element {}
  block__element représente l’enfant d’un block

• .amui-x-block.is--modifier {}
  is--modifier représente une variation du block. Un modifier n’est jamais préfixé

Suivant le préfixe général, il y a les préfixes des dossiers :

• a- : pour les atomes
• m- : pour les molécules
• o- : pour les organismes
• l- : pour les layouts (template)
• h- : pour les helpers

Cela permet de savoir rapidement ou le code SCSS de la class CSS se situe.

Conclusion

La combinaison d'un « name spacing global », de préfixes de catégorie et d'une syntaxe BEM donne une chaîne de class explicite qui permet aux développeurs de déduire sa fonctionnalité dans la création de l'interface utilisateur.

Voici un exemple :

.amui-a-btn .is--secondary

• amui- est le « name spacing global » pour tous les styles issus du Guide de Style
• a- est la catégorie de la class, qui signifie atoms
• btn est le nom du block (Block est le B dans BEM)
• is--secondary est le modifier, indiquant une varation du block (Modifier est le M dans BEM)

Un autre exemple :

.amui-l-primary-nav__submenu

• amui- est le « name spacing global » pour tous les styles issus du Guide de Style
• l- est la catégorie de la class, qui signifie layout
• primary-nav est le nom du block (Block est le B dans BEM)
• __submenu est un élément indiquant qu’il est un enfant du block (Element est le E dans BEM)

Nous utilisons le rem, unité relative pour assurer une meilleure accessibilité pour le plus grand nombre (accessible aux personnes à la vue déficiente) ainsi qu’une meilleure intégration pour tous les supports (Mobile, tablette, ordinateur…etc.).

Pour utiliser les rem plus facilement, nous utilisons une fonction rem() permettant de convertir les valeurs pixels en rem.

exemple : font-size: rem(12);