Guide de style frontend et conventions de codage
Ce document définit les normes de codage, les modèles architecturaux et le système de conception pour l'interface Angular Guessimate.
1. Pile technologique
- Framework : Angular 20+
- Styling : Tailwind CSS 4
- Gestion d'état : Angular Signals et RxJS
- Système de build : Angular CLI (Esbuild)
2. Structure du projet
Nous suivons une structure de répertoires basée sur les fonctionnalités. Le code est organisé par domaine fonctionnel plutôt que par type technique.
src/app/
├── core/ # Singletons globaux (Guards, Intercepteurs, Services globaux)
├── layout/ # Composants de mise en page (Navigation, Pied de page, Shell)
├── features/ # Modules fonctionnels (Logique métier)
│ ├── home/
│ ├── session/
│ │ ├── components/ # Composants muets/présentation
│ │ ├── pages/ # Composants intelligents/conteneurs (routés)
│ │ ├── services/ # État/logique propre à la fonctionnalité
│ │ └── models/ # Types propres à la fonctionnalité
│ └── ...
├── websocket/ # Infrastructure WebSocket
└── shared/ # Utilitaires partagés (Pipes, Directives, UI générique)
Conventions de nommage
- Fichiers : kebab-case (ex.
session-page.component.ts,auth.service.ts). - Classes : PascalCase (ex.
SessionPageComponent,AuthService). - Sélecteurs : préfixe
app-, kebab-case (ex.app-user-profile). - Signals : pas de suffixe, nom descriptif nom/verbe (ex.
user(),isLoading()). - Observables : suffixe
$(ex.user$).
3. Normes des composants
Définition
- Utiliser des composants autonomes (
standalone: trueest la valeur par défaut dans v19+). - Préférer les modèles en ligne pour la plupart des composants afin de garder la logique et la vue colocalisées.
- Éviter les fichiers CSS externes ; utiliser les classes utilitaires Tailwind CSS directement dans le modèle.
@Component({
selector: 'app-exemple',
imports: [CommonModule, RouterLink], // Importations explicites
template: `
<div class="p-4 bg-surface-100 rounded-lg">
<h1 class="text-2xl font-bold text-gray-900">{{ titre() }}</h1>
</div>
`
})
export class ExempleComponent {
titre = signal('Bonjour le monde');
}
Flux de contrôle
Utiliser la nouvelle syntaxe de flux de contrôle intégrée d'Angular.
<!-- Bien -->
@if (chargementEnCours()) {
<app-spinner/>
} @else {
@for (item of items(); track item.id) {
<app-item [data]="item"/>
}
}
Injection de dépendances
Préférer la fonction inject() à l'injection par constructeur pour une meilleure inférence de type et un code plus propre.
// Bien
private readonly
route = inject(ActivatedRoute);
private readonly
store = inject(SessionStore);
// À éviter si possible
constructor(private
route: ActivatedRoute
)
{
}
4. Gestion d'état
- État local : Utiliser
signal()pour l'état primitif. - État partagé : Utiliser les Signal Stores (Services utilisant Signals) fournis au niveau approprié (Racine ou Composant).
- Données réactives : Utiliser
computed()pour l'état dérivé eteffect()avec parcimonie pour les effets de bord.
@Injectable()
export class SessionStore {
// État
private readonly _state = signal<SessionState>(initialState);
// Sélecteurs
readonly lobby = computed(() => this._state().lobby);
readonly connexion = computed(() => this._state().connection);
// Actions
setLobby(lobby: Lobby) {
this._state.update(s => ({...s, lobby}));
}
}
5. Styling et système de conception
Nous utilisons Tailwind CSS 4 avec une palette de couleurs sémantiques définie dans styles.css.
Règles d'utilisation
- Utility-First : Écrire les classes directement dans le HTML.
- Pas de nombres magiques : Utiliser les valeurs du thème (ex.
p-4pasp-[16px]). - Mode sombre : Utiliser le modificateur
dark:pour toutes les classes liées aux couleurs.
Palette de couleurs
L'application utilise une convention de nommage sémantique mappée aux couleurs Tailwind.
Couleurs principales
| Catégorie | Nom sémantique | Mode clair | Mode sombre | Utilisation |
|---|---|---|---|---|
| Arrière-plan | background | gray-50 | gray-950 | Arrière-plan principal de l'application |
| Surface | surface | white | gray-900 | Cartes, modales, sections |
| Surface Alt | surface-alt | gray-100 | gray-800 | Arrière-plans secondaires, champs de saisie |
| Primaire | brand | blue-600 | blue-600 | Actions principales, boutons, mises en avant |
| Primaire Atténué | brand-muted | blue-50 | blue-900/30 | États sélectionnés, surbrillances légères |
| Succès | success | emerald-500 | emerald-600 | États de succès, confirmation |
| Succès Atténué | success-muted | emerald-50 | emerald-900/30 | Arrière-plans de succès |
| Danger | danger | red-600 | red-600 | Erreurs, actions destructrices |
| Danger Atténué | danger-muted | red-50 | red-900/30 | Arrière-plans d'erreur |
| Avertissement | warning | amber-500 | amber-600 | Avertissements, états en attente |
| Avertiss. Atténué | warning-muted | amber-50 | amber-900/30 | Arrière-plans d'avertissement |
Typographie et bordures
| Catégorie | Mode clair | Mode sombre | Utilisation |
|---|---|---|---|
| Primaire | gray-900 | white | Titres principaux et texte du corps |
| Secondaire | gray-500 | gray-400 | Sous-titres, étiquettes, info secondaire |
| Atténué | gray-400 | gray-500 | Texte désactivé, espaces réservés |
| Bordure | gray-200 | gray-800 | Séparateurs standard et bordures de cartes |
Implémentation dans styles.css
Les couleurs sont définies à l'aide de variables CSS dans le bloc @theme :
@theme {
--color-brand-600: var(--color-blue-600);
--color-surface-100: var(--color-stone-100);
/* ... */
}
6. Modèles de composants courants
Cartes et conteneurs
Style standard pour les conteneurs de contenu (comme les cartes d'estimation, listes) :
<div class="flex flex-col bg-surface-100/60 border border-surface-200 dark:bg-gray-900/40 dark:border-gray-800/60 rounded-md shadow-sm">
<!-- Contenu -->
</div>
- Arrière-plan :
bg-surface-100/60(Clair) /dark:bg-gray-900/40(Sombre) - Bordure :
border border-surface-200(Clair) /dark:border-gray-800/60(Sombre) - Arrondi :
rounded-md(Standard) - Séparateurs :
divide-y divide-surface-300 dark:divide-gray-800
En-têtes typographiques
<div class="flex flex-col gap-1">
<h2 class="text-2xl font-semibold leading-none text-gray-900 dark:text-white">Titre</h2>
<span class="text-sm font-normal text-gray-600 dark:text-gray-400">Description du sous-titre</span>
</div>