112 lines
5.7 KiB
Markdown
112 lines
5.7 KiB
Markdown
<!-- file: docs/templates/010-WEB_CSS_SASS.md -->
|
|
<!-- version: 1 -->
|
|
|
|
# Guide d'adaptation CSS / Sass
|
|
|
|
## Objet
|
|
|
|
Ce guide accompagne le profil [`../rules/560-CSS_SASS.md`](../rules/560-CSS_SASS.md). Il aide un projet à décider sa chaîne de styles sans transformer Sass, Bootstrap, Vite ou un layout particulier en obligation universelle.
|
|
|
|
PGR ne fournit volontairement pas de `main.scss`, de thème Bootstrap ou de structure `styles/` copiable par défaut : ces fichiers ne deviennent utiles qu'après choix du framework, des entrypoints, du layout et du niveau de personnalisation réel.
|
|
|
|
## Décider d'abord si Sass apporte une valeur
|
|
|
|
CSS seul reste valide lorsque les besoins sont simples ou que les capacités CSS modernes suffisent.
|
|
|
|
Sass est particulièrement pertinent lorsque le projet a besoin de :
|
|
|
|
- variables et configuration de compilation ;
|
|
- mixins, fonctions ou composition de modules ;
|
|
- factorisation d'une chaîne de styles non triviale ;
|
|
- personnalisation d'un package qui expose officiellement des sources Sass/SCSS ;
|
|
- construction sélective d'un framework ou thème sans modifier les sources tierces.
|
|
|
|
La décision doit rester liée au besoin réel. Un smoke ou un petit frontend n'a pas à recevoir Sass uniquement pour ressembler à un autre projet.
|
|
|
|
## Choisir l'implémentation
|
|
|
|
Dans un projet Vite compatible, les sources `.scss` / `.sass` peuvent être prises en charge par Vite lorsque le préprocesseur correspondant est installé. Pour une nouvelle baseline contrôlée, `sass-embedded` est un bon choix de `devDependency` lorsqu'il est supporté ; `sass` reste une alternative légitime.
|
|
|
|
Le package manager, la version et la commande d'installation sont décidés par le projet. Le guide ne transforme donc pas un exemple `npm add -D ...` en commande normative.
|
|
|
|
Hors Vite, utiliser l'intégration officielle du bundler ou du compilateur Sass sélectionné.
|
|
|
|
## Organiser les sources
|
|
|
|
Le projet décide ses noms de répertoires et entrypoints. Une organisation possible peut séparer :
|
|
|
|
```text
|
|
variables / configuration
|
|
modules internes
|
|
adaptations de packages tiers
|
|
styles applicatifs
|
|
entrypoint principal
|
|
```
|
|
|
|
Cette organisation n'est qu'un pattern. PGR n'impose ni `frontend/sass/`, ni `_variables.scss`, ni `main.scss`.
|
|
|
|
Les fichiers sources intentionnels sont versionnés. Les CSS compilées, fichiers minifiés, sourcemaps et copies du build restent générés sauf artefact de distribution explicitement gouverné.
|
|
|
|
## Préférer les modules Sass modernes
|
|
|
|
Pour le nouveau code :
|
|
|
|
```text
|
|
@use
|
|
@forward
|
|
```
|
|
|
|
sont préférés lorsque les dépendances les supportent.
|
|
|
|
`@import` Sass peut rester nécessaire pour une dépendance historique ou une API tierce qui le documente encore. Cette compatibilité doit rester locale ; elle ne doit pas conduire à écrire de nouveau code PGR autour de `@import` lorsque le système de modules fonctionne.
|
|
|
|
Lorsqu'un module accepte une configuration, utiliser son API publique et ses variables configurables plutôt que copier/modifier ses sources dans le projet.
|
|
|
|
## Packages npm et entrypoints de styles
|
|
|
|
Pour une dépendance de styles :
|
|
|
|
1. vérifier l'entrypoint CSS/Sass public documenté par le package ;
|
|
2. vérifier s'il expose une configuration Sass supportée ;
|
|
3. utiliser cet entrypoint public avant d'envisager un chemin interne sous `node_modules` ;
|
|
4. conserver tout override dans un source possédé par le projet ;
|
|
5. ne jamais modifier directement le package installé.
|
|
|
|
Un package peut exposer CSS, Sass, JavaScript ou plusieurs de ces surfaces. Les dépendances `@types/*` ne concernent que les API JavaScript/TypeScript qui en ont réellement besoin ; importer uniquement le Sass/CSS d'un package ne suffit pas à justifier un package de déclarations.
|
|
|
|
## Exemple Bootstrap
|
|
|
|
Bootstrap illustre un package pouvant être utilisé de plusieurs façons : CSS précompilé, API JavaScript et sources Sass configurables.
|
|
|
|
Si le projet choisit Bootstrap avec Sass, il doit suivre l'API Sass de la version réellement sélectionnée, placer ses variables/overrides avant les étapes requises par cette API et conserver les adaptations dans ses propres sources.
|
|
|
|
PGR ne fixe ni Bootstrap, ni Bootswatch, ni un thème, ni un ordre d'import particulier comme baseline universelle. Un projet existant utilisant encore `@import` pour compatibilité MAY le conserver jusqu'à une migration sûre.
|
|
|
|
## Relation avec Vite
|
|
|
|
Lorsque Vite est sélectionné :
|
|
|
|
- l'import d'un entrypoint `.scss` depuis le graphe frontend peut suffire à déclencher la compilation ;
|
|
- `css.preprocessorOptions` MAY adapter le compilateur lorsque le projet en a réellement besoin ;
|
|
- une configuration globale injectée dans chaque fichier doit rester limitée aux symboles nécessaires ; injecter des styles complets partout peut dupliquer le CSS ;
|
|
- les CSS présentes dans `build.outDir` sont des outputs Vite générés, pas de nouveaux sources.
|
|
|
|
Le profil Vite reste propriétaire de `vite.config.ts`, du cache et de l'output ; le profil CSS/Sass reste propriétaire de la chaîne de styles elle-même.
|
|
|
|
## Validation
|
|
|
|
Pour un frontend où Sass est intégré au build Vite :
|
|
|
|
```text
|
|
typecheck preuve TypeScript séparée si applicable
|
|
build preuve Vite + compilation/transformation des styles
|
|
browser smoke seulement si une propriété observable le nécessite
|
|
host gate séparée
|
|
```
|
|
|
|
Ne pas ajouter une commande Sass autonome si elle ne prouve rien de plus que le build déjà exécuté.
|
|
|
|
Si le projet possède au contraire une compilation Sass autonome, un linter ou un package de styles publié séparément, ajouter la preuve officielle correspondante.
|
|
|
|
Le contrat complet est décrit dans [`../validation/005-WEB_FRONTEND_VALIDATION.md`](../validation/005-WEB_FRONTEND_VALIDATION.md).
|