Trésor ILOYI

Introduction

Si vous avez déjà travaillé sur une base de code CSS de grande envergure, vous avez forcément rencontré ces difficultés : des styles qui se surchargent de manière inattendue, la guerre de spécificité sur les sélecteurs, et des feuilles de style de plus en plus difficiles à maintenir.

Lorsque j’ai commencé à travailler sur un Design System pour une plateforme e-commerce, ces défis sont devenus encore plus critiques.

En effet, la performance web est cruciale pour le e-commerce — chaque milliseconde compte en termes de taux de conversion. Ce qui signifie que l’architecture CSS que nous fournissions aux équipes de développement devait être non seulement maintenable, mais aussi optimisée pour la performance.

En choisissant la méthodologie ITCSS (Inverted Triangle CSS) comme fondation de notre architecture, nous avons rapidement réalisé que, bien qu’ITCSS fournisse un excellent cadre, il nécessitait quelques adaptations pour répondre à nos besoins spécifiques.

Dans cet article, je vais vous présenter ce qu’est ITCSS, pourquoi nous l’avons choisi, et comment nous l’avons adapté pour créer une architecture robuste et scalable pour notre Design System.

---

Qu’est-ce qu’ITCSS ?

ITCSS, créé par Harry Roberts, signifie Inverted Triangle CSS (CSS en Triangle Inversé). Il s’agit d’une méthodologie d’organisation des fichiers CSS qui aide à gérer la spécificité et à maintenir une base de code saine.

Le principe fondamental est simple : organiser les feuilles de style du générique vers le spécifique, et de la faible spécificité vers une forte spécificité.

Imaginez un triangle inversé :

• En haut (la partie la plus large), vous avez des styles génériques, à portée large, avec une faible spécificité
• En bas (la partie la plus étroite), vous avez des styles spécifiques, explicites, avec une spécificité plus élevée

Cette organisation garantit que votre CSS compilé suit une progression naturelle de spécificité, réduisant la probabilité de conflits et le besoin de déclarations !important.

Les couches ITCSS originales

Dans sa forme standard, ITCSS propose sept couches :

1. Settings — Variables globales, configuration
2. Tools — Mixins et fonctions
3. Generic — Resets, normalisations
4. Elements — Styles des éléments HTML bruts (h1, a, p, etc.)
5. Objects — Patterns de design structurels (conteneurs, grilles)
6. Components — Composants d’interface
7. Utilities — Classes utilitaires et surcharges

Chaque couche a un objectif spécifique et ne doit contenir que des styles appropriés à son niveau de spécificité.

---

Pourquoi voir choisi ITCSS pour notre Design System ?

Lors de la construction d’un Design System pour une plateforme e-commerce, nous avions plusieurs contraintes en tête :

1. La performance compte — Les sites e-commerce ont besoin de feuilles de style à chargement rapide. Une architecture CSS bien organisée avec une spécificité contrôlée produit un CSS compilé plus propre et plus efficace.
2. La scalabilité — Le Design System serait utilisé par plusieurs équipes. Nous avions besoin d’une structure claire et prévisible que tout le monde puisse la suivre et comprendre.
3. La maintenabilité — Les composants évolueraient au fil du temps. L’architecture devait supporter les changements sans créer d’effets de bord en cascade.

ITCSS répondait à toutes ces préoccupations en fournissant un modèle mental clair pour organiser les styles et une stratégie intégrée pour gérer la spécificité.

---

Notre architecture ITCSS adaptée

Bien qu’ITCSS soit une excellente méthodologie, elle est aussi conçue pour être flexible. Harry Roberts lui-même, encourage les équipes à l’adapter à leurs besoins spécifiques.

Voici à quoi ressemble notre architecture finale :

├── components
│   ├── badge
│   ├── button
│   ├── ...
├── generic
├── layouts
├── settings
├── tools
├── typography
└── utilities

Nous avons apporté plusieurs adaptations à l’approche ITCSS standard.

Laissez-moi vous présenter chaque couche et vous expliquer nos choix.

1. Settings

La couche Settings contient les variables globales qui définissent les valeurs fondamentales de notre Design System — nos design tokens. Ceux-ci sont gérés par une bibliothèque dédiée.

Dans notre adaptation, cette couche contient principalement des mixins et fonctions qui manipulent les design tokens.

Voici les règles que nous suivons lorsque nous travaillons avec cette couche :

• Les fichiers contiennent des mixins et fonctions qui interagissent principalement avec les design tokens
• De nouvelles variables globales peuvent être définies ici, mais avec parcimonie — la plupart des tokens doivent provenir de la bibliothèque dédiée
• La plupart des mixins et fonctions sont marqués comme @access private car ils sont destinés à un usage interne dans les autres couches, pas pour les développeurs finaux

2. Tools

La couche Tools contient des mixins et fonctions qui peuvent être utilisées à la fois en interne et ainsi que par les développeurs finaux.

Nos règles pour cette couche :

• Toutes les mixins et fonctions sont en @access public par défaut (seuls les helpers internes sont privés)
• Pas de déclarations de variables globales
• Les mixins et fonctions ne peuvent dépendre que d’éléments internes au fichier ou d’éléments de la couche Settings

3. Generic

La couche Generic suit l’ITCSS standard sans aucune adaptation.
Elle contient des styles de haut niveau comme :

• Les resets CSS
• Normalize.css
• Les règles globales de box-sizing

4. Elements

La couche Elements dans l’ITCSS standard est l’endroit où on style les éléments HTML bruts comme <a>, <p>, <h1>, <ul>, etc. Ce sont des styles appliqués directement aux balises HTML sans utiliser de classes.

Nous avons supprimé cette couche car notre Design System n’avait pas besoin de définir des styles par défaut pour les éléments HTML — cette responsabilité était gérée ailleurs dans l’architecture du projet.

Cependant, si votre projet nécessite des styles de base cohérent pour ces éléments HTML, vous devriez absolument conserver cette couche.

5. Objects (renommée depuis Layouts)

Nous avons renommé la couche Objects en Layouts car nous trouvions que cela décrivait mieux l’objectif de cette couche : des patterns de design structurels qui organisent le contenu sur la page.

Cette couche inclut :

• Les systèmes de grille
• Les conteneurs flexbox
• Les utilitaires d’espacement pour la mise en page
• Tout pattern structurel non lié à un composant d’interface spécifique

Le principe clé : cette couche se concentre uniquement sur la structure, pas la décoration. Voyez-la comme le squelette qui maintient vos composants en place.

6. Components

La couche Components est l’endroit où nous stylons les éléments d’interface — boutons, cartes, modales, formulaires, etc. Nous suivons l’ITCSS standard pour cette couche.

Une règle importante que nous avons établie : chaque dossier de composant doit également être organisé selon les principes ITCSS, avec ses propres sous-couches Settings, Tools et Components lorsque nécessaire.

• Les fonctions, mixins et variables définis dans un fichier de composant ne doivent être utilisés que dans des contextes associés à ce composant

7. Utilities

La couche Utilities contient les classes utilitaires, les hacks et les surcharges. Nous suivons l’ITCSS standard ici également.

Nos règles :

• Les fichiers contiennent principalement des classes utilitaires, des helpers et des surcharges
• Pas de déclarations de variables, mixins ou fonctions
• Les classes utilitaires sont construites en utilisant les mixins et fonctions des couches Settings et Tools
• Ces fichiers sont consommés par les utilisateurs finaux, pas en interne par la bibliothèque

---

L’ordre d’import est important

L’un des principaux avantages d’ITCSS est la façon dont il gère la spécificité CSS. Pour y parvenir, les fichiers doivent être importés dans le bon ordre :

Ordre	Couche	Spécificité
1	Settings	Pas de sortie CSS
2	Tools	Pas de sortie CSS
3	Generic	Faible spécificité (sélecteurs d’éléments, resets)
4	Layouts	Spécificité de niveau classe
5	Components	Spécificité de niveau classe
6	Utilities	Spécificité la plus élevée (souvent avec !important)

Cet ordre garantit que votre CSS compilé progresse de la faible spécificité vers la haute, rendant les styles prévisibles et réduisant les conflits.

---

Conventions de nommage

Des conventions de nommage cohérentes sont essentielles pour un Design System scalable. Nous avons établi des conventions à trois niveaux : fichiers, classes CSS, et mixins/fonctions.

Nommage des fichiers

Chaque fichier SCSS est préfixé par la première lettre de sa couche ITCSS :

Préfixe	Couche
_s.	Settings
_t.	Tools
_g.	Generic
_l.	Layouts
_c.	Components
_u.	Utilities

Ainsi, quand un développeur ouvre un fichier, il sait instantanément dans quelle couche il travaille.

Nommage des classes CSS

Nos classes CSS sont préfixées par m (pour la première lettre du nom de notre Design System) suivi de la première lettre de la couche :

Préfixe	Couche
.ml-*	Layouts
.mc-*	Components
.mu-*	Utilities

Le préfixe m évite les collisions avec d’autres frameworks CSS ou outils qui pourraient être utilisés en parallèle de notre Design System.

Notez que les couches Settings et Tools ne produisent pas de classes CSS — elles ne fournissent que des fonctions, mixins et variables.

Nommage des mixins et fonctions

Nous avons établi des préfixes pour clarifier l’objectif de chaque mixin et fonction :

Préfixe	Objectif
set-*	Mixins qui appliquent ou configurent des styles
get-*	Fonctions qui récupèrent ou calculent des valeurs
make-*	Mixins qui génèrent du CSS
generate-*	Mixins qui produisent plusieurs styles liés
import-*	Mixins qui gèrent l’import de ressources externes

Privé vs public : la convention de l’underscore

Nous avons introduit une distinction claire entre les fonctions et mixins privés et publics.

Pourquoi est-ce important ?

Dans la première version de notre Design System, toutes les fonctions et mixins étaient également accessibles, sans indication claire de ceux qui étaient destinés à un usage externe et ceux qui étaient des utilitaires internes. Cela créait des risques :

• Les développeurs pouvaient utiliser des fonctions internes qui n’étaient pas censées être stables
• Faire évoluer le code interne pouvait accidentellement casser des implémentations externes
• La surface de l’API n’était pas claire

Notre solution :

• Les mixins et fonctions publics font partie de l’API stable — nous maintenons la rétrocompatibilité
• Les mixins et fonctions privés (préfixés par _) sont réservés à un usage interne — ils peuvent évoluer sans être considérés comme des breaking changes
• Les fonctions et mixins privés sont exclus de notre documentation SassDoc

Cette convention s’aligne avec la façon dont SCSS gère les fichiers partiels (préfixés par _), ce qui la rend intuitive pour les développeurs.

Avantages :

• Classification claire de ce qui est public et de ce qui est interne
• Interface publique stable pour les développeurs externes
• Liberté d’optimiser le code interne sans impacter les utilisateurs
• Documentation plus propre qui ne montre que ce que les développeurs doivent réellement utiliser

---

Points clés à retenir

Adapter ITCSS pour notre Design System m’a enseigné plusieurs leçons précieuses :

1. Les méthodologies sont des cadres, pas des règles — ITCSS est conçu pour être adapté.
   N’hésitez pas à le modifier pour répondre aux besoins de votre projet.
2. La gestion de la spécificité est cruciale — Surtout pour les projets de grande envergure, avoir une stratégie pour la spécificité CSS économise d’innombrables heures de débogage.
3. Les conventions de nommage se cumulent — Une nomenclature cohérente à chaque niveau (fichiers, classes, fonctions) crée un système facile à naviguer et à maintenir.
4. Public vs privé — Distinguer clairement les APIs stables des utilitaires internes vous donne la liberté de faire évoluer votre base de code tout en maintenant la confiance de vos utilisateurs.
5. La documentation suit la structure — Une architecture bien organisée rend la documentation presque auto-explicative.

---

Conclusion

ITCSS a fourni une excellente fondation pour l’architecture CSS de notre Design System. En l’adaptant à nos besoins spécifiques — en supprimant la couche Elements, en renommant Objects en Layouts, et en établissant des conventions de nommage claires — nous avons créé un système scalable et maintenable qui sert bien notre plateforme e-commerce.

Si vous construisez un Design System ou travaillez sur une grande base de code CSS, je vous encourage à explorer ITCSS. Commencez par la méthodologie standard, comprenez ses principes, puis adaptez-la à votre contexte. La flexibilité est l’une de ses plus grandes forces.

Vous avez des questions ou vous voulez partager vos propres adaptations d’ITCSS ? N’hésitez pas à me contacter — j’adorerais entendre comment d’autres équipes résolvent ces défis.

---