Galactic-Shrine HTML Documentation Standard

Version: 1.2.0
Auteur / Author: ⋞Galactic-Shrine⋟
Portée / Scope: Projets HTML / Twig / Templates Symfony / Pages Web / Composants UI / Fragments de vues / Emails HTML / Interfaces d’administration

1. Objectif

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

Il a pour objectifs :

• d’uniformiser la documentation des templates et structures HTML ;
• de conserver un style bilingue [FR] / [EN] ;
• de rester naturel pour le HTML ;
• de rendre les structures de page plus lisibles ;
• de documenter proprement les sections, composants, zones dynamiques et contraintes d’accessibilité.

2. Principes généraux

La documentation HTML Galactic-Shrine doit être :

• claire ;
• concise ;
• bilingue ;
• structurée ;
• utile pour la maintenance.

La documentation doit privilégier :

• les commentaires HTML natifs ;
• les descriptions courtes ;
• les indications structurelles ;
• les remarques d’accessibilité lorsque nécessaire ;
• la documentation des blocs importants, pas de chaque balise.

3. Format obligatoire des blocs

Toujours utiliser le format suivant :

<!--
[FR] Représente la navigation principale du site.
[EN] Represents the main site navigation.
-->

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

4. Convention bilingue

Chaque bloc descriptif doit suivre l’ordre suivant :

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

Exemple :

<!--
[FR] Conteneur principal de la page profil.
[EN] Main container of the profile page.
-->

5. Éléments autorisés

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

• texte libre avec [FR] et [EN]
• @role
• @accessibility
• @dependency
• @note
• @todo
• @see

Éléments déconseillés :

• les balises XML de type <summary> ou <param> ;
• les commentaires trop longs ;
• les commentaires purement décoratifs ;
• les duplications d’informations déjà évidentes dans le balisage.

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 utiles

Exemple :

<!--
[FR] Section de navigation principale du tableau de bord.
[EN] Main navigation section of the dashboard.

@accessibility [FR] Utilise un libellé explicite pour les lecteurs d’écran.
@accessibility [EN] Uses an explicit label for screen readers.
-->

7. Standard par type d’élément

7.1 Fichier ou template

<!--
[FR] Template principal de la page d’accueil.
[EN] Main template for the homepage.

[FR] Ce fichier structure le héros, les sections marketing et l’appel à l’action.
[EN] This file structures the hero, marketing sections, and call to action.
-->

7.2 Section principale

<!--
[FR] Section présentant les dernières actualités du studio.
[EN] Section displaying the latest studio news.
-->
<section class="gs-news-section">

7.3 Composant réutilisable

<!--
[FR] Carte de profil utilisateur réutilisable.
[EN] Reusable user profile card.

@role [FR] Affichage synthétique du compte.
@role [EN] Compact account display.
-->
<article class="gs-user-card">

7.4 Zone dynamique ou hook JavaScript

<!--
[FR] Point d’injection pour la liste chargée dynamiquement.
[EN] Injection point for the dynamically loaded list.

@dependency [FR] Rempli par JavaScript après chargement des données.
@dependency [EN] Filled by JavaScript after data loading.
-->
<div id="news-feed" data-controller="news-feed"></div>

7.5 Bloc avec contrainte d’accessibilité

<!--
[FR] Boîte de dialogue de confirmation de suppression.
[EN] Delete confirmation dialog.

@accessibility [FR] Doit conserver aria-modal, aria-labelledby et le focus initial.
@accessibility [EN] Must preserve aria-modal, aria-labelledby, and initial focus.
-->
<div class="gs-modal" role="dialog" aria-modal="true" aria-labelledby="delete-title">

7.6 Formulaire

<!--
[FR] Formulaire de connexion utilisateur.
[EN] User login form.

@note [FR] Les messages d’erreur sont injectés côté serveur.
@note [EN] Error messages are injected server-side.
-->
<form method="post" action="/login">

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 Commenter les blocs, pas chaque balise

Documenter layouts, sections majeures, composants réutilisables, zones dynamiques, hooks JavaScript, formulaires métier et éléments sensibles pour l’accessibilité.

8.4 Règle HTML importante

Éviter la séquence -- dans le contenu des commentaires, car elle peut rendre le commentaire invalide.

8.5 Pas de surdocumentation

Ne pas commenter l’évidence.

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

Documenter en priorité :

• templates principaux ;
• layouts ;
• partials ;
• composants réutilisables ;
• sections de page importantes ;
• zones pilotées par JavaScript ;
• blocs dépendants d’un contrôleur Symfony ou Twig ;
• éléments critiques pour l’accessibilité ;
• structures de formulaires métier ;
• fragments complexes conditionnels.

10. Exemple complet recommandé

<!--
[FR] Template principal de la page profil utilisateur.
[EN] Main template for the user profile page.

[FR] Ce template structure l’en-tête, les statistiques et l’activité récente.
[EN] This template structures the header, statistics, and recent activity.
-->

<main class="gs-profile-page">
    <!--
    [FR] En-tête de profil avec avatar et informations principales.
    [EN] Profile header with avatar and primary information.
    -->
    <section class="gs-profile-header">
        <h1>{{ user.displayName }}</h1>
    </section>

    <!--
    [FR] Zone dynamique des activités récentes.
    [EN] Dynamic recent activity area.

    @dependency [FR] Alimentée via Turbo ou JavaScript.
    @dependency [EN] Populated via Turbo or JavaScript.
    -->
    <section id="recent-activity" data-controller="recent-activity">
    </section>
</main>

11. Décision officielle recommandée

Standard officiel recommandé pour Galactic-Shrine HTML :

• utiliser <!-- ... --> ;
• écrire d’abord [FR], puis [EN] ;
• utiliser @role, @accessibility, @dependency, @note selon le besoin ;
• documenter les blocs structurants, pas chaque élément trivial ;
• garder un style court, propre et uniforme.

12. Résumé exécutable

À appliquer dans tous les projets HTML Galactic-Shrine :

• utiliser des commentaires HTML natifs ;
• écrire [FR] puis [EN] ;
• documenter templates, sections majeures, composants, hooks JS et zones sensibles ;
• éviter -- dans le contenu des commentaires ;
• documenter ce qui compte, pas l’évidence.