6.2 KiB
Profil CSS et Sass
Rôle et applicabilité
Ce profil possède les règles réutilisables de la chaîne de styles frontend : sources CSS, prétraitement Sass lorsqu'il est sélectionné, dépendances de styles, points d'entrée publics et classification des artefacts générés.
Il complète 500-LANGUAGES.md. Il ne rend aucun framework CSS particulier obligatoire et ne possède ni TypeScript, ni Vite, ni le package manager, ni le host.
Le profil s'applique à un projet qui possède réellement des sources CSS/Sass ou une chaîne de styles correspondante. La présence d'un frontend sans styles n'oblige pas à créer des fichiers CSS/Sass artificiels.
CSS comme baseline
Un frontend Web peut utiliser directement CSS sans préprocesseur. Sass n'est donc jamais requis par la simple présence de fichiers CSS.
Les styles sources intentionnels SHOULD être versionnés. Les CSS produits uniquement par compilation à partir de sources Sass, les variantes minifiées, les sourcemaps et les copies placées dans un output de build sont des artefacts générés et SHOULD rester hors du source control, sauf besoin explicite de distribution ou publication gouverné comme tel.
Un artefact généré MUST NOT être modifié manuellement comme s'il constituait un second source. La correction appartient au source ou à la configuration qui le produit.
PGR MUST NOT imposer un nom de répertoire universel tel que css/, styles/ ou sass/. Le layout appartient au projet ou au skeleton qui le compose.
Recommandation Sass pour les projets contrôlés
Pour un frontend contrôlé dont la chaîne de styles est non triviale, Sass SHOULD être préféré lorsqu'il apporte une valeur claire de composition, factorisation ou configuration.
Cette recommandation est particulièrement forte lorsqu'une dépendance installée par le package manager expose un entrypoint Sass/SCSS, des variables configurables, maps, mixins, fonctions ou modules permettant de personnaliser la bibliothèque à la compilation sans modifier ses sources.
Bootstrap constitue un exemple concret de cette catégorie : ses sources Sass permettent de sélectionner des parties de la bibliothèque et de configurer des variables. Cette observation n'en fait pas une dépendance PGR universelle.
Un frontend petit, un smoke minimal ou un projet dont les besoins sont couverts proprement par CSS MAY rester sans Sass.
Implémentation Sass et intégration au build
Le profil Sass ne dépend d'aucun bundler particulier.
Lorsqu'un projet utilise Vite et sélectionne Sass, il MAY utiliser sass ou sass-embedded selon la compatibilité de sa toolchain. Pour une nouvelle baseline contrôlée compatible, sass-embedded SHOULD être préféré lorsque son intégration est supportée et apporte un gain proportionné ; ce choix reste une devDependency du projet réel et n'est pas prérempli dans un template PGR générique.
Un autre bundler ou une compilation Sass autonome MAY utiliser l'implémentation officielle adaptée à son environnement. PGR MUST NOT installer un plugin Vite spécifique uniquement pour activer Sass lorsque Vite prend déjà en charge le préprocesseur sélectionné.
Modules Sass et compatibilité
Pour du nouveau code contrôlé, le système de modules Sass moderne (@use / @forward) SHOULD être préféré lorsque les dépendances et la toolchain le permettent.
L'ancien @import Sass est déprécié dans Dart Sass. Il MAY toutefois rester nécessaire à titre de compatibilité lorsqu'une bibliothèque tierce, une version existante ou sa documentation l'impose encore. PGR ne doit pas forcer une migration syntaxique qui casse une dépendance supportée.
Lorsqu'une bibliothèque expose une API Sass publique et configurable, le projet SHOULD suivre cette API documentée. Avec le système de modules, une configuration par @use ... with (...) ou un entrypoint réexporté via @forward est préférable lorsqu'elle est réellement supportée.
PGR SHOULD NOT dépendre de chemins internes non documentés sous node_modules ou d'une arborescence privée d'un package si celui-ci expose un entrypoint Sass public. Une compatibilité historique MAY justifier temporairement un chemin interne, mais cette dépendance doit rester explicite et révisable.
Frameworks CSS et packages de styles
Bootstrap, Tailwind CSS ou une autre bibliothèque de présentation restent des décisions de skeleton/projet ou d'un futur owner spécifique si un contrat réutilisable distinct apparaît.
Le profil CSS/Sass possède uniquement la façon de traiter leurs sources/styles lorsqu'elles passent par CSS ou Sass ; il ne choisit pas la bibliothèque à la place du projet.
Un package npm apportant uniquement des styles n'impose pas l'ajout de déclarations @types/*. Les déclarations TypeScript sont requises seulement lorsque des API JavaScript/TypeScript réellement consommées en ont besoin, conformément à 530-TYPESCRIPT.md et 540-JAVASCRIPT_PACKAGE_ECOSYSTEM.md.
Validation des styles
La validation doit prouver la chaîne réellement utilisée sans dupliquer artificiellement la même propriété.
Lorsque Sass est compilé à l'intérieur du build Vite et qu'aucune compilation Sass indépendante n'existe, un build Vite réussi peut constituer la preuve de compilation des styles. PGR SHOULD NOT imposer en plus une seconde compilation Sass identique uniquement pour ajouter une commande à la gate.
Lorsqu'une compilation Sass autonome, un linter CSS/Sass ou une autre transformation possède un contrat distinct, sa commande officielle MAY être ajoutée comme preuve séparée.
Une validation de styles ne remplace ni le type-check TypeScript, ni le build frontend complet, ni un smoke navigateur nécessaire à un comportement observable, ni la validation du host.
Le contrat de validation frontend indépendant du host est décrit dans ../validation/005-WEB_FRONTEND_VALIDATION.md. Le guide ../templates/010-WEB_CSS_SASS.md décrit l'adaptation pratique sans imposer de layout ou framework CSS universel.