Sasedev/pgr
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

0.1.1-alpha.5

Browse Source
This commit is contained in:
SinuS von SifriduS
2026-09-27 11:43:09 +02:00
parent 89b8ea88c1
commit 55c6f7b05d
12 changed files with 885 additions and 35 deletions
Download Patch File Download Diff File Expand all files Collapse all files

48
docs/rules/560-CSS_SASS.md
View File

@@ -1,19 +1,25 @@
<!-- file: docs/rules/560-CSS_SASS.md -->
<!-- version: 1 -->
<!-- version: 2 -->
# 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 et classification des CSS générées.
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`](500-LANGUAGES.md). Il ne rend aucun framework CSS particulier obligatoire et ne possède ni Vite, ni le package manager, ni le host.
Il complète [`500-LANGUAGES.md`](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 activé par la simple présence de fichiers CSS.
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 sont versionnés ; les CSS produits uniquement par compilation à partir de sources Sass sont des artefacts générés et SHOULD rester hors du source control sauf besoin explicite de distribution ou de publication.
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
@@ -21,24 +27,44 @@ Pour un frontend contrôlé dont la chaîne de styles est non triviale, Sass **S
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 surcharger des variables. Cette observation n'en fait pas une dépendance PGR universelle.
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.
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.
## Frameworks CSS
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.
## Validation
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`](530-TYPESCRIPT.md) et [`540-JAVASCRIPT_PACKAGE_ECOSYSTEM.md`](540-JAVASCRIPT_PACKAGE_ECOSYSTEM.md).
La compilation Sass et la validation du CSS produit sont distinctes du type-check TypeScript, du build Vite et du smoke navigateur.
## Validation des styles
`0.1.1-alpha.5` précisera les gates de styles et leur intégration à la validation frontend indépendante du host.
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`](../validation/005-WEB_FRONTEND_VALIDATION.md). Le guide [`../templates/010-WEB_CSS_SASS.md`](../templates/010-WEB_CSS_SASS.md) décrit l'adaptation pratique sans imposer de layout ou framework CSS universel.