252 lines
10 KiB
Markdown
252 lines
10 KiB
Markdown
# ADR 006 — Stack frontend : versions 2026 (React 19, Vite 8, TypeScript 6, Tailwind 4, RR7)
|
|
|
|
**Statut :** Accepté — mis à jour Sprint 0.5
|
|
**Date :** 2026-04-17
|
|
**Décideur :** Hermann
|
|
**Contexte :** Révélé par l'état des lieux Claude Code au démarrage du Sprint 0 frontend
|
|
|
|
---
|
|
|
|
## Contexte
|
|
|
|
La première version d'`ARCHITECTURE.md` §2 listait une stack basée sur les versions "connues stables" :
|
|
|
|
- React 18
|
|
- Vite 5
|
|
- TypeScript 5
|
|
- Tailwind 3
|
|
- React Router v6
|
|
|
|
L'état des lieux effectué par Claude Code au démarrage du Sprint 0 (2026-04-17) a révélé que le scaffold installé plusieurs semaines auparavant utilisait des versions plus récentes :
|
|
|
|
- React 19.2.4
|
|
- Vite 8.0.4
|
|
- TypeScript 6.0.2
|
|
- Tailwind 4.2.2
|
|
- React Router v7.14.1
|
|
|
|
Cette divergence doit être résolue : soit downgrader le scaffold, soit mettre à jour la documentation.
|
|
|
|
## Options envisagées
|
|
|
|
### Option A — Downgrader vers les versions de la doc originale
|
|
|
|
Aligner le scaffold sur React 18, Vite 5, TypeScript 5, Tailwind 3, React Router v6.
|
|
|
|
- **Avantages :** documentation historique respectée, versions "éprouvées" en production.
|
|
- **Inconvénients :**
|
|
- Casse un `node_modules` qui fonctionne
|
|
- Perd l'optimisation du compilateur React 19 (Actions, useOptimistic)
|
|
- Perd le moteur Oxide de Tailwind 4 (builds 3,5x plus rapides)
|
|
- Perd le typage strict amélioré de TypeScript 6
|
|
- Downgrade effectué pour des raisons qui n'existent plus (les versions récentes sont matures en avril 2026)
|
|
|
|
### Option B — Mettre à jour la documentation
|
|
|
|
Accepter les versions installées et mettre à jour `ARCHITECTURE.md §2` pour refléter la réalité.
|
|
|
|
- **Avantages :**
|
|
- Préserve le travail de scaffold déjà fait
|
|
- Bénéficie des améliorations de performance des versions récentes
|
|
- Écosystème mature : shadcn/ui supporte complètement Tailwind 4 et React 19 depuis début 2025
|
|
- Alignement avec l'écosystème 2026 (les nouveaux tutoriels, docs, et ressources communautaires supposent ces versions)
|
|
- **Inconvénients :**
|
|
- Versions légèrement plus récentes = moins de StackOverflow disponible pour les cas exotiques
|
|
- Mitigation : Claude Opus 4.7 connaît bien ces versions (cf. knowledge cutoff janvier 2026)
|
|
|
|
### Option C — Hybride
|
|
|
|
Garder React 19, Vite 8, TypeScript 6 mais downgrader Tailwind 4 → 3 pour "compatibilité shadcn/ui classique".
|
|
|
|
- **Avantages :** apparemment plus prudent.
|
|
- **Inconvénients :** injustifié depuis que shadcn/ui supporte complètement Tailwind 4 avec configuration CSS-first via `@theme`. Ajoute de la complexité sans bénéfice.
|
|
|
|
## Décision
|
|
|
|
**Option B** — accepter les versions installées et mettre à jour la documentation.
|
|
|
|
### Stack frontend officielle au 2026-04-17
|
|
|
|
| Couche | Version | Notes |
|
|
|---|---|---|
|
|
| React | 19.2.x | Server Components N/A (SPA pur), Actions et useOptimistic disponibles |
|
|
| React DOM | 19.2.x | |
|
|
| Vite | 8.0.x | Moteur Rolldown stable, config simplifiée |
|
|
| TypeScript | 6.0.x | Typage strict activé (voir tsconfig.app.json) |
|
|
| Tailwind CSS | 4.2.x | Configuration CSS-first via `@theme`, pas de `tailwind.config.ts` |
|
|
| `@tailwindcss/vite` | 4.2.x | Plugin Vite officiel (préféré au plugin PostCSS) |
|
|
| React Router | v7.14.x | Compatible API v6, data loaders disponibles |
|
|
| Supabase JS | 2.103.x | |
|
|
|
|
### Dépendances à ajouter lors du scaffold
|
|
|
|
| Package | Rôle | Cf. ADR |
|
|
|---|---|---|
|
|
| `@tanstack/react-query` | Cache serveur, refetch, mutations | ARCHITECTURE.md §2 |
|
|
| `zod` | Validation des inputs formulaires | SECURITY.md SEC-04 |
|
|
| `react-markdown` | Rendu sécurisé des rapports IA | SECURITY.md SEC-05 |
|
|
| `class-variance-authority`, `clsx`, `tailwind-merge` | Utilitaires shadcn/ui | — |
|
|
| `lucide-react` | Icônes (standard shadcn/ui) | — |
|
|
| Packages `@radix-ui/react-*` | Primitives shadcn/ui (installés à la demande) | — |
|
|
| `@sentry/react` | Monitoring | TECH_DEBT.md FTD-07 (après MVP) |
|
|
|
|
### Dépendances de développement
|
|
|
|
| Package | Rôle |
|
|
|---|---|
|
|
| `vitest` | Tests unitaires |
|
|
| `@vitest/coverage-v8` | Couverture |
|
|
| `@testing-library/react` | Tests React |
|
|
| `@testing-library/jest-dom` | Matchers DOM |
|
|
| `@testing-library/user-event` | Simulation user |
|
|
| `jsdom` | Environnement DOM pour Vitest |
|
|
| `prettier` | Formatage |
|
|
| `eslint-config-prettier` | Intégration ESLint ↔ Prettier |
|
|
|
|
### Configuration Tailwind 4
|
|
|
|
Pas de `tailwind.config.ts`. La configuration se fait exclusivement dans `src/index.css`.
|
|
|
|
#### Dark mode
|
|
|
|
Dark mode class-based (`.dark` sur `<html>`) — toggle manuel via ThemeProvider React (Sprint 0.5 étape 2). Configuré via :
|
|
|
|
```css
|
|
@variant dark (&:where(.dark, .dark *));
|
|
```
|
|
|
|
Si cette syntaxe est rejetée par une future version de Tailwind 4, le fallback est `@custom-variant dark (...)`.
|
|
|
|
#### Tokens @theme (palette Direction H — validée Sprint 0.5)
|
|
|
|
```css
|
|
@import 'tailwindcss';
|
|
|
|
@variant dark (&:where(.dark, .dark *));
|
|
|
|
@theme {
|
|
/* Typographie */
|
|
--font-sans: "Plus Jakarta Sans", -apple-system, BlinkMacSystemFont, "Segoe UI",
|
|
system-ui, sans-serif;
|
|
|
|
/* Fonds — bg-canvas = page, bg-surface = cards */
|
|
--color-canvas: #EEF2F8;
|
|
--color-canvas-2: #E6EBF4;
|
|
--color-surface: #FFFFFF;
|
|
--color-surface-hover: #F8FAFD;
|
|
|
|
/* Hairlines */
|
|
--color-line: #DDE3ED;
|
|
--color-line-strong: #C7D0E0;
|
|
|
|
/* Encres */
|
|
--color-ink-1: #0F172A; /* titres */
|
|
--color-ink-2: #1E293B; /* corps */
|
|
--color-ink-3: #475569;
|
|
--color-ink-4: #64748B;
|
|
--color-ink-5: #94A3B8; /* désactivé, hints */
|
|
|
|
/* Brand */
|
|
--color-expria: #1B4FD8;
|
|
--color-expria-hover: #1741B8;
|
|
--color-expria-50: #EEF3FF;
|
|
--color-expria-100: #DCE6FF;
|
|
--color-expria-200: #B8CDFF;
|
|
--color-deep: #0B1F5C;
|
|
--color-deep-2: #142B6E;
|
|
|
|
/* Sémantiques */
|
|
--color-success: #0E9F6E; --color-success-bg: #E6F6F0;
|
|
--color-warning: #C77A00; --color-warning-bg: #FEF3E2;
|
|
--color-danger: #C53030; --color-danger-bg: #FDECEC;
|
|
|
|
/* Rayons */
|
|
--radius-sm: 6px; --radius-md: 10px;
|
|
--radius-lg: 14px; --radius-xl: 18px; --radius-full: 999px;
|
|
|
|
/* Ombres */
|
|
--shadow-sm: 0 1px 2px rgba(15, 23, 42, 0.04);
|
|
--shadow-md: 0 4px 12px rgba(15, 23, 42, 0.06), 0 1px 3px rgba(15, 23, 42, 0.04);
|
|
--shadow-lg: 0 12px 28px rgba(15, 23, 42, 0.08), 0 2px 6px rgba(15, 23, 42, 0.04);
|
|
}
|
|
|
|
/* Dark mode overrides */
|
|
.dark {
|
|
--color-canvas: #0D1220; --color-canvas-2: #121A2D;
|
|
--color-surface: #182238; --color-surface-hover: #1E2A42;
|
|
--color-line: #27324B; --color-line-strong: #364363;
|
|
--color-ink-1: #F1F4FA; --color-ink-2: #DDE3EF;
|
|
--color-ink-3: #A8B2C7; --color-ink-4: #7A8499; --color-ink-5: #525C73;
|
|
--color-expria: #5B7FFF; --color-expria-hover: #6F8EFF;
|
|
--color-expria-50: rgba(91, 127, 255, 0.12);
|
|
--color-deep: #060B1A;
|
|
--color-success: #3DD68C; --color-success-bg: rgba(61, 214, 140, 0.12);
|
|
--color-warning: #F5B849; --color-warning-bg: rgba(245, 184, 73, 0.12);
|
|
--color-danger: #F06B6B; --color-danger-bg: rgba(240, 107, 107, 0.12);
|
|
--shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.3);
|
|
--shadow-md: 0 4px 16px rgba(0, 0, 0, 0.4);
|
|
--shadow-lg: 0 12px 32px rgba(0, 0, 0, 0.5);
|
|
}
|
|
```
|
|
|
|
#### Classes Tailwind générées
|
|
|
|
Les tokens `@theme` créent des classes utilitaires directement utilisables :
|
|
|
|
| Token | Classes Tailwind |
|
|
|---|---|
|
|
| `--color-canvas` | `bg-canvas`, `text-canvas`, `border-canvas` |
|
|
| `--color-surface` | `bg-surface`, `text-surface`, `border-surface` |
|
|
| `--color-ink-1` | `text-ink-1`, `bg-ink-1` |
|
|
| `--color-expria` | `bg-expria`, `text-expria`, `border-expria` |
|
|
| `--color-success` | `text-success`, `bg-success` |
|
|
| `--radius-md` | `rounded-md` (override : 10px au lieu de 6px Tailwind) |
|
|
| `--shadow-sm` | `shadow-sm` (override valeurs Tailwind) |
|
|
|
|
**Convention critique** : `bg-surface` = cards / modals / panels. `bg-canvas` = fond de page. Ne jamais inverser.
|
|
|
|
#### Typographie
|
|
|
|
Plus Jakarta Sans chargée via Google Fonts dans `index.html` (preconnect + stylesheet, weights 400/500/600/700). Migration vers auto-hébergement (`@fontsource/plus-jakarta-sans`) après MVP si les performances réseau deviennent un enjeu.
|
|
|
|
### shadcn/ui avec Tailwind 4
|
|
|
|
La CLI shadcn/ui supporte Tailwind 4 depuis début 2025 :
|
|
|
|
```bash
|
|
npx shadcn@latest init
|
|
npx shadcn@latest add button dialog form
|
|
```
|
|
|
|
Les composants générés utilisent les conventions Tailwind 4 (pas de `forwardRef`, attributs `data-slot`). Le fichier de configuration reste `components.json` à la racine.
|
|
|
|
## Conséquences
|
|
|
|
**Positives :**
|
|
- Pas de perte de travail sur le scaffold existant
|
|
- Performances optimales (build Tailwind 4 : microsecondes sur builds incrémentaux)
|
|
- Stack aligné sur l'écosystème 2026 — facile pour un dev externe qui arrivera
|
|
- Compilateur React 19 apporte des optimisations gratuites
|
|
|
|
**Négatives :**
|
|
- Les versions récentes peuvent avoir quelques bugs non encore découverts. Mitigation : mise à jour ponctuelle vers la dernière version patch en cas de bug signalé (ex : 19.2.4 → 19.2.5).
|
|
- Si un dev arrive avec une expertise sur React 17/18 uniquement, courbe d'apprentissage légère. Mitigation : `ONBOARDING.md` liste les ressources officielles pour React 19 et Tailwind 4.
|
|
|
|
**À revisiter si :**
|
|
- Une faille de sécurité critique apparaît dans une version spécifique
|
|
- Une incompatibilité bloquante est découverte entre deux packages (peu probable en avril 2026)
|
|
|
|
## Actions de mise en cohérence
|
|
|
|
1. Mettre à jour `ARCHITECTURE.md §2` avec les versions ci-dessus (réalisé en session actuelle)
|
|
2. Mettre à jour `ONBOARDING.md` pour référencer React 19 et Tailwind 4 dans les ressources (à faire)
|
|
3. Aucune action sur `TESTS_AUTOMATISES.md` — Vitest fonctionne identiquement
|
|
4. Aucune action sur les ADRs 001-005 — ils ne référencent pas de versions précises
|
|
|
|
## Références
|
|
|
|
- État des lieux Claude Code du 2026-04-17
|
|
- [shadcn/ui Tailwind v4](https://ui.shadcn.com/docs/tailwind-v4) — support officiel confirmé
|
|
- [React 19 Upgrade Guide](https://react.dev/blog/2024/04/25/react-19)
|
|
- [Tailwind CSS v4.0](https://tailwindcss.com/blog/tailwindcss-v4)
|
|
- `ARCHITECTURE.md` §2 (mis à jour en parallèle)
|