Portail ⋞Galactic-Shrine⋟
Codage · 1.0.0

Galactic-Shrine SCSS Coding Standard

Ce standard définit la manière d’écrire le code **SCSS** dans les projets Galactic-Shrine.

Markdown source Retour à la section
SCSSCodageProjets SCSSDesign SystemsUI KitsFrameworks CSS

Galactic-Shrine SCSS Coding Standard

Version: 1.0.0
Auteur / Author: ⋞Galactic-Shrine⋟
Portée / Scope: Projets SCSS / Design Systems / UI Kits / Frameworks CSS / Applications Web / Interfaces d’administration / Sites et produits front-end

1. Objectif

Ce standard définit la manière d’écrire le code SCSS dans les projets Galactic-Shrine.

Il a pour objectifs :

  • d’uniformiser la structure SCSS ;
  • d’améliorer la maintenabilité du style ;
  • de limiter la dérive de sélecteurs, variables et mixins ;
  • d’aligner le nommage applicatif avec Galactic-Shrine.

2. Principes généraux

Le code SCSS Galactic-Shrine doit être :

  • structuré ;
  • lisible ;
  • modulaire ;
  • prévisible ;
  • raisonnablement découplé.

Le code doit privilégier :

  • des tokens cohérents ;
  • des composants réutilisables ;
  • une profondeur de nesting limitée ;
  • des noms de classes explicites ;
  • une séparation claire entre base, layout, composants, utilitaires et thèmes.

3. Décisions officielles Galactic-Shrine pour SCSS

Décisions officielles :

  • variables, mixins et fonctions SCSS : PascalCase ;
  • paramètres de mixins et fonctions : PascalCase ;
  • placeholders : nom explicite et stable ;
  • classes CSS produites : convention projet, stable et lisible ;
  • fichiers partiels : nom aligné sur la responsabilité ;
  • tokens et maps : regroupés par domaine.

Exemple :

$PrimaryColor: #20c997;
$DangerColor: #e42217;

@mixin ButtonVariant($BackgroundColor, $TextColor) {
    background-color: $BackgroundColor;
    color: $TextColor;
}

4. Convention de nommage

  • variables SCSS : $PascalCase ;
  • mixins : PascalCase ;
  • fonctions : PascalCase ;
  • paramètres : $PascalCase ;
  • placeholders : %PascalCase ;
  • maps : $PascalCase ;
  • classes CSS : convention choisie par le projet, mais stable sur l’ensemble du système ;
  • fichiers partiels : _Button.scss, _Form.scss, _Spacing.scss, etc.

5. Structure recommandée d’un fichier SCSS

Ordre recommandé :

  1. @use / @forward ;
  2. variables ou maps locales ;
  3. fonctions ;
  4. mixins ;
  5. placeholders ;
  6. règles de composants ou utilitaires.

Règles :

  • éviter de mélanger tokens, composants et overrides ad hoc ;
  • un fichier doit avoir une responsabilité identifiable ;
  • centraliser les tokens partagés ;
  • éviter les dépendances circulaires entre partiels.

6. Style d’écriture

6.1 Nesting

  • limiter la profondeur de nesting ;
  • éviter les sélecteurs difficiles à surcharger ;
  • ne pas reproduire toute la structure DOM dans le SCSS.

6.2 Spécificité

  • garder une spécificité faible autant que possible ;
  • éviter !important hors cas justifiés ;
  • préférer la composition à l’escalade de sélecteurs.

6.3 Tokens

  • utiliser des variables de design plutôt que des valeurs dupliquées ;
  • centraliser couleurs, espacements, rayons, tailles et z-index critiques ;
  • éviter les “magic numbers” répétées.

6.4 Mixins et fonctions

  • créer un mixin ou une fonction seulement si le gain réel existe ;
  • éviter les API SCSS trop abstraites ;
  • garder des signatures courtes et compréhensibles.

7. Règles spécifiques SCSS

  • séparer base, layout, components, utilities, themes quand le projet le justifie ;
  • documenter les tokens structurants ;
  • éviter les dépendances implicites à un ordre de chargement fragile ;
  • utiliser @use / @forward de préférence aux anciens patterns si l’outillage le permet ;
  • rester prudent avec les placeholders complexes et les @extend.

8. Gestion des erreurs et robustesse

  • valider les entrées de fonctions ou mixins critiques lorsque possible ;
  • fournir des valeurs par défaut raisonnables ;
  • éviter les générateurs SCSS trop “magiques” difficiles à tracer ;
  • garder les thèmes et variantes explicitement pilotables ;
  • faire apparaître clairement les dépendances à des tokens externes.

9. Types d’éléments à revoir en priorité

Relire en priorité :

  • tokens globaux ;
  • mixins de composants ;
  • systèmes d’espacement ;
  • thèmes ;
  • utilities ;
  • responsive helpers ;
  • surcharges spécifiques produit.

10. Exemple complet recommandé

@use "../Tokens/Colors" as *;
@use "../Tokens/Spacing" as *;

$CardRadius: 0.75rem;

@mixin CardSurface($BackgroundColor, $TextColor) {
    background-color: $BackgroundColor;
    color: $TextColor;
    border-radius: $CardRadius;
    padding: $SpacingMd;
}

.GsProfileCard {
    @include CardSurface($SurfaceColor, $TextPrimaryColor);
    box-shadow: 0 0.5rem 1rem rgba(0, 0, 0, 0.12);

    &__Header {
        margin-bottom: $SpacingSm;
    }
}

11. Décision officielle recommandée

Standard officiel recommandé pour Galactic-Shrine SCSS :

  • utiliser $PascalCase pour variables et paramètres ;
  • utiliser PascalCase pour mixins et fonctions ;
  • centraliser les tokens ;
  • limiter le nesting ;
  • garder des composants lisibles et peu spécifiques.

12. Résumé exécutable

À appliquer dans tous les projets SCSS Galactic-Shrine :

  • $PascalCase pour variables et paramètres ;
  • PascalCase pour mixins et fonctions ;
  • tokens centralisés ;
  • nesting limité ;
  • pas d’abstraction SCSS inutile ;
  • structure modulaire claire.