Portail ⋞Galactic-Shrine⋟
Documentation · 1.2.0

Galactic-Shrine SCSS Documentation Standard

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

Markdown source Retour à la section
SCSSDocumentationProjets SCSSCSS FrameworksUI KitsDesign Systems

Galactic-Shrine SCSS Documentation Standard

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

1. Objectif

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

Il a pour objectifs :

  • d’uniformiser la documentation du code SCSS ;
  • de conserver un style bilingue [FR] / [EN] ;
  • de rester cohérent avec la convention documentaire Galactic-Shrine ;
  • de conserver un format visuel homogène ;
  • de documenter proprement les variables, mixins, fonctions, placeholders, composants et sections structurantes.

2. Principes généraux

La documentation SCSS Galactic-Shrine doit être :

  • claire ;
  • concise ;
  • bilingue ;
  • naturelle pour SCSS ;
  • utile techniquement.

La documentation doit privilégier :

  • les commentaires de bloc natifs ;
  • des descriptions courtes ;
  • des tags simples et lisibles ;
  • un usage pertinent, sans surdocumentation.

3. Format obligatoire des blocs

Toujours utiliser le format suivant :

/**
 * [FR] Applique le style principal du bouton.
 * [EN] Applies the main button style.
 */

Ce format constitue le standard officiel recommandé pour Galactic-Shrine SCSS.

4. Convention bilingue

Chaque bloc descriptif doit suivre l’ordre suivant :

  1. ligne française [FR]
  2. ligne anglaise [EN]

Exemple :

/**
 * [FR] Définit la couleur principale de la marque.
 * [EN] Defines the primary brand color.
 */

5. Éléments autorisés

Éléments autorisés dans les commentaires SCSS Galactic-Shrine :

  • texte libre avec [FR] et [EN]
  • @param
  • @return
  • @example
  • @deprecated
  • @requires
  • @see
  • @note

Éléments déconseillés :

  • les balises XML de type <summary>, <param>, <returns> ;
  • les commentaires trop verbeux ;
  • les descriptions purement décoratives sans valeur technique.

6. Structure recommandée d’un commentaire

Ordre recommandé :

  1. description courte [FR]
  2. description courte [EN]
  3. détail complémentaire [FR] si nécessaire
  4. détail complémentaire [EN] si nécessaire
  5. tags techniques utiles

Exemple :

/**
 * [FR] Génère un style de bouton réutilisable.
 * [EN] Generates a reusable button style.
 *
 * [FR] Ce mixin centralise les couleurs et les états visuels principaux.
 * [EN] This mixin centralizes colors and main visual states.
 *
 * @param {Color} $background-color [FR] Couleur de fond.
 *                                  [EN] Background color.
 * @param {Color} $text-color [FR] Couleur du texte.
 *                            [EN] Text color.
 */

7. Standard par type d’élément

7.1 Fichier ou module SCSS

/**
 * [FR] Définit les styles du composant bouton.
 * [EN] Defines the button component styles.
 *
 * [FR] Ce fichier contient les variantes, tailles et états interactifs.
 * [EN] This file contains variants, sizes, and interactive states.
 */

7.2 Variable globale ou token

/**
 * [FR] Couleur principale de la marque.
 * [EN] Primary brand color.
 */
$gs-color-primary: #00d5ff !default;

7.3 Mixin

/**
 * [FR] Applique une variante visuelle de bouton.
 * [EN] Applies a visual button variant.
 *
 * @param {Color} $background-color [FR] Couleur de fond du bouton.
 *                                  [EN] Button background color.
 * @param {Color} $text-color [FR] Couleur du texte.
 *                            [EN] Text color.
 * @param {Color|null} $border-color [FR] Couleur de bordure optionnelle.
 *                                   [EN] Optional border color.
 */
@mixin button-variant($background-color, $text-color, $border-color: null) {
    background-color: $background-color;
    color: $text-color;
}

7.4 Fonction SCSS

/**
 * [FR] Convertit une valeur en rem selon la base configurée.
 * [EN] Converts a value to rem based on the configured root size.
 *
 * @param {Number} $pixels [FR] Valeur en pixels.
 *                         [EN] Value in pixels.
 * @return {Number} [FR] Valeur convertie en rem.
 *                  [EN] Value converted to rem.
 */
@function to-rem($pixels) {
    @return calc($pixels / 16) * 1rem;
}

7.5 Placeholder

/**
 * [FR] Définit le style de base partagé par les cartes interactives.
 * [EN] Defines the shared base style for interactive cards.
 */
%card-base {
    border-radius: 1rem;
}

7.6 Bloc composant

/**
 * [FR] Composant principal de carte utilisateur.
 * [EN] Main user card component.
 */
.gs-user-card {
    display: flex;
}

7.7 Utilitaire ou helper

/**
 * [FR] Utilitaire de troncature sur une ligne.
 * [EN] Single-line truncation utility.
 */
.u-text-truncate {
    overflow: hidden;
    text-overflow: ellipsis;
    white-space: nowrap;
}

8. Règles de style

8.1 Descriptions courtes

Toujours préférer une phrase simple et directe.

8.2 Ordre fixe

Toujours écrire [FR] avant [EN].

8.3 @param et @return

Utiliser les tags techniques seulement lorsqu’ils apportent une vraie valeur, notamment pour les mixins, fonctions et helpers réutilisables.

8.4 Commentaires //

Les commentaires // peuvent être utilisés pour des notes locales temporaires, mais ne constituent pas la documentation officielle.

8.5 Pas de surdocumentation

Ne pas commenter chaque règle CSS évidente.

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

Documenter en priorité :

  • modules SCSS ;
  • tokens globaux ;
  • variables sémantiques ;
  • mixins ;
  • fonctions ;
  • placeholders ;
  • composants réutilisables ;
  • utilitaires structurants ;
  • blocs complexes ;
  • styles exposés comme API front-end.

10. Exemple complet recommandé

/**
 * [FR] Définit les styles du composant bouton.
 * [EN] Defines the button component styles.
 *
 * [FR] Ce fichier centralise les styles communs, variantes et tailles.
 * [EN] This file centralizes shared styles, variants, and sizes.
 */

$gs-button-radius: 0.75rem !default;

/**
 * [FR] Applique une variante visuelle de bouton.
 * [EN] Applies a visual button variant.
 *
 * @param {Color} $background-color [FR] Couleur de fond du bouton.
 *                                  [EN] Button background color.
 * @param {Color} $text-color [FR] Couleur du texte.
 *                            [EN] Text color.
 *
 * @example [FR] @include button-variant(#111, #fff);
 *          [EN] @include button-variant(#111, #fff);
 */
@mixin button-variant($background-color, $text-color) {
    background-color: $background-color;
    color: $text-color;
    border-radius: $gs-button-radius;
}

11. Décision officielle recommandée

Standard officiel recommandé pour Galactic-Shrine SCSS :

  • utiliser /** ... */ ;
  • écrire d’abord [FR], puis [EN] ;
  • utiliser @param, @return, @example, @deprecated, @note selon le besoin ;
  • documenter les éléments structurants, pas chaque propriété triviale ;
  • garder un style court, propre et uniforme.

12. Résumé exécutable

À appliquer dans tous les projets SCSS Galactic-Shrine :

  • utiliser des commentaires de bloc officiels ;
  • écrire [FR] puis [EN] ;
  • documenter variables exposées, mixins, fonctions, placeholders et composants ;
  • réserver // aux notes internes non officielles ;
  • documenter ce qui compte, pas l’évidence.