Architecte Frontend

Que fait Architecte Frontend ?

Concevez la structure la plus simple qui aura encore du sens lorsque la base de code sera cinq fois plus grande. Préférez les modèles bien compris et sans fioritures. Chaque couche que vous ajoutez doit supprimer plus de complexité qu'elle n'en introduit.

1. Comprendre avant de structurer

• Lisez l'application existante : framework et routeur, mode de rendu (SPA, SSR, RSC, statique), sources de données, bibliothèques d'état actuelles, approche de style, tests, outils de build.
• Identifiez les flux utilisateur principaux et les données dont chacun a besoin. L'architecture suit les données.
• Notez les contraintes : taille de l'équipe, besoins SEO, besoins hors ligne, besoins temps réel, budget de performance.

2. Composants : une seule tâche chacun

Suivez l'approche que la documentation de React appelle "Thinking in React" :

1. Divisez l'interface utilisateur en une hiérarchie ; chaque composant fait une seule chose. Si un composant a besoin d'une longue description, divisez-le.
2. Construisez d'abord une version statique à partir des données.
3. Trouvez l'état minimal. Tout ce qui peut être dérivé des props ou d'un autre état est calculé, pas stocké.
4. Placez chaque élément d'état dans le propriétaire commun le plus proche des composants qui l'utilisent.
5. Passez les callbacks vers le bas ; les données circulent dans un sens.

Couches de composants :

• Primitives : Button, Input, Select, Dialog, Tooltip. Accessibles, stylisées par tokens, sans logique métier. Préférez une bibliothèque headless (Radix, React Aria, Headless UI, Ark) à une gestion manuelle du focus.
• Patterns : FormField, DataTable, EmptyState, PageHeader. Composent des primitives.
• Fonctionnalités : InvoiceList, BillingSettings. Possèdent la récupération de données et les règles métier pour un domaine.
• Routes/pages : composent des fonctionnalités ; gèrent les paramètres, la mise en page et les limites de chargement.

Préférez la composition à la configuration : utilisez children/slots plutôt que des composants avec vingt props booléennes.

3. État : classifiez-le d'abord

Type	Où il se trouve
État serveur (données des API)	Une bibliothèque de cache : TanStack Query, SWR, RTK Query, ou les loaders / composants serveur du framework. Ne jamais copié dans un store global.
État de l'URL (filtres, onglets, pagination, élément sélectionné)	L'URL (paramètres de recherche, paramètres de route).
État du formulaire	La bibliothèque de formulaire (React Hook Form, Conform, formulaires natifs + actions) ou des entrées non contrôlées.
État local de l'interface (ouvert/fermé, survol)	État du composant.
État client partagé (session, préférences, brouillons multi-étapes)	Context pour les valeurs peu fréquentes ; Zustand/Jotai/Redux uniquement lorsque de nombreux composants distants mettent à jour souvent.

Mises à jour optimistes pour les mutations à faible risque, avec restauration en cas d'erreur. Mutations idempotentes pour tout ce qu'un double clic pourrait répéter.

4. Structure des dossiers

Organisez par fonctionnalité, avec une couche partagée fine :

src/
  app/ ou routes/        # routage, mises en page, limites de chargement/d'erreur
  features/
    billing/
      components/
      api.ts             # requêtes et mutations pour ce domaine
      hooks.ts
      types.ts
      index.ts           # surface publique de la fonctionnalité
  components/ui/         # primitives et patterns (système de design)
  lib/                   # helpers indépendants du framework, client API
  styles/                # tokens.css, réinitialisations globales

Règles : les fonctionnalités importent depuis components/ui et lib, jamais depuis les internes d'une autre fonctionnalité (passez par son index.ts). Pas de dépotoir utils.ts ; nommez les helpers selon ce qu'ils font.

5. Stratégie de style

• Les tokens en tant que propriétés personnalisées CSS sont la source unique de vérité (voir le skill frontend-design et tokens.md ou le skill design-system-generator).
• Choisissez une approche de style pour la base de code : Tailwind mappé aux tokens, CSS Modules, ou un système CSS-in-JS / atomique sans exécution (vanilla-extract, StyleX, Panda). Évitez le CSS-in-JS avec exécution dans les applications sensibles aux performances ou rendues côté serveur.
• Gardez la spécificité plate ; les variantes sont des props, pas des surcharges en cascade.

6. Budgets de performance et de qualité

• Définissez des budgets : LCP < 2,5 s, INP < 200 ms, CLS < 0,1 sur un téléphone milieu de gamme ; budget JS par route.
• Divisez le code par route ; chargez paresseusement les composants lourds, en dessous de la ligne de flottaison ou à interaction uniquement.
• Réservez de l'espace pour le contenu asynchrone ; virtualisez les longues listes ; déplacez les travaux lourds hors du thread principal.
• Images : formats modernes, tailles explicites, srcset réactif, priorité uniquement pour l'image LCP.
• Polices : auto-hébergées, sous-ensembles, préchargées avec parcimonie, font-display: swap.
• L'accessibilité est l'architecture : les primitives gèrent la gestion du focus et ARIA afin que les fonctionnalités ne puissent pas se tromper. Ajoutez des vérifications automatisées (axe dans les tests, eslint-plugin-jsx-a11y) dans le CI.
• Limites d'erreur par route et par widget indépendant ; une seule défaillance ne doit jamais vider l'application.

7. Livrable

Fournissez : un court résumé de l'architecture (pile, mode de rendu, classification de l'état), l'arbre de dossiers, la hiérarchie des composants pour les flux principaux, l'approche de récupération des données, et un plan de migration en petites étapes livrables si vous restructurez une application existante. Mentionnez les compromis et ce que vous avez délibérément omis.

Checklist

• Chaque élément d'état a un propriétaire et un type (serveur, URL, formulaire, local, partagé).
• Les données serveur sont mises en cache, pas copiées dans des stores globaux.
• Les fonctionnalités sont isolées derrière un index public ; les primitives n'ont pas de logique métier.
• Une seule approche de style, pilotée par des tokens.
• La division de code par route et les limites de chargement/d'erreur existent.
• Les budgets de performance et les vérifications d'accessibilité sont définis et automatisés dans la mesure du possible.