PD-228 — Retour d'expérience¶

1. Résumé exécutif¶

La User Story PD-228 visait à établir un design system CSS basé sur des tokens pour garantir la cohérence des couleurs et espacements. L'implémentation a produit un fichier design-system.css complet avec une palette de tokens bien définie (couleurs, espacements, typographie, ombres, rayons). Cependant, plusieurs écarts majeurs ont été identifiés : des couleurs hardcodées dans les composants (gradients), des espacements en valeurs brutes au lieu des tokens, et l'absence de la structure modulaire et du linting prévu. Verdict : ACCEPTÉ AVEC RÉSERVES.

2. Points fluides¶

• Définition complète des tokens de couleurs dans :root (palette principale, secondaire, états, sémantiques)
• Tokens d'espacement cohérents avec une échelle claire (xs à 3xl)
• Intégration des polices @fontsource (Inter, Space Grotesk) sans dépendance externe
• Tokens de typographie bien structurés (tailles de texte, poids)
• Tokens d'ombres et de rayons de bordure complets
• Styles de base (reset, body, headings) utilisant les tokens
• Classes utilitaires (text-center, mb-, mt-) basées sur les tokens
• Responsive design avec adaptation des tokens sur mobile

3. Points difficiles¶

• Discipline d'utilisation des tokens : Malgré la définition des tokens, les composants (Hero.astro, CallToAction.astro) utilisent des couleurs hex hardcodées (#0d3461) dans les gradients CSS au lieu des tokens.

• Mixité tokens/valeurs brutes : Les boutons utilisent padding: 1rem 1.5rem au lieu de var(--spacing-sm) var(--spacing-md), créant une incohérence avec l'approche tokens.

• Structure modulaire abandonnée : Le plan prévoyait une séparation en fichiers (tokens/, base/, components/). L'implémentation a fusionné tout dans un seul fichier design-system.css.

• Absence de garde-fou : Pas de stylelint ni de règle pour détecter les couleurs/espacements hors tokens. Rien n'empêche un développeur d'ajouter des valeurs arbitraires.

4. Hypothèses révélées tardivement¶

• Complexité des gradients CSS : Les gradients CSS utilisent des valeurs RGBA avec opacité. Les tokens CSS natifs ne supportent pas facilement la manipulation de l'opacité, ce qui a conduit à hardcoder certaines valeurs.

• Fichier legacy public/styles.css : Ce fichier existait avant le design system et définit une palette différente (--primary, --text). Son existence n'avait pas été anticipée.

• Effort de migration : Aligner tous les composants existants sur les tokens demande un effort significatif après coup, ce qui a été sous-estimé.

5. Invariants complexes¶

6. Dette technique¶

7. Risques résiduels¶

8. Améliorations processus¶

• Implémenter le linting dès le départ : Configurer stylelint avec color-no-hex et règles d'espacement avant d'écrire le premier composant
• Définir des tokens pour les gradients : Créer des variables CSS pour les gradients complets, pas seulement les couleurs de base
• Créer un guide de contribution CSS : Documenter les règles d'utilisation des tokens pour les nouveaux développeurs
• Nettoyer les fichiers legacy : Supprimer ou migrer public/styles.css avant de livrer le design system

9. Enseignements clés¶

1. Définir des tokens ne suffit pas — Sans garde-fou (linting), les développeurs contourneront les tokens par commodité ou ignorance.

2. Les gradients CSS nécessitent une approche spécifique — Les tokens de couleurs seuls ne couvrent pas les cas avec opacité ou transitions de couleurs.

3. Un fichier unique peut devenir un monolithe — La structure modulaire prévue (tokens/, base/, components/) aurait facilité la maintenance.

4. La migration vers un design system est coûteuse — Il est plus efficace d'appliquer les tokens dès la création des composants que de les migrer après coup.

5. Les fichiers legacy sont des pièges — Un ancien fichier CSS non aligné crée de la confusion et un risque d'incohérence.

10. Addendum — Résolution des écarts¶

[2025-12-21] — Mise à jour suite à acceptation finale¶

Les écarts E-01 à E-04 identifiés lors de la revue initiale ont été corrigés :

Verdict final : ✅ ACCEPTÉ (2025-12-20)