Introduction
Les user flows avancés vont au-delà des simples wireframes linéaires. Ils intègrent des branches conditionnelles, des états persistants et des interactions multi-appareils. En 2026, les équipes exigent des flux modélisés qui se synchronisent directement avec le code. Cette approche réduit les écarts entre design et développement tout en améliorant la traçabilité des décisions UX. Nous allons construire un système complet combinant diagrammes exécutables et logique applicative.
Prérequis
- Node.js 20+
- Connaissances solides de TypeScript et React
- Notions de machines à états (XState)
- Mermaid CLI ou éditeur compatible
- Figma ou outil de prototypage avancé
Initialisation du projet
npm create vite@latest user-flows-2026 -- --template react-ts
cd user-flows-2026
npm install @xstate/react xstate mermaidNous initialisons un projet React TypeScript et installons XState pour gérer les états du flow ainsi que Mermaid pour la visualisation exécutable des diagrammes.
Définition du flow avec Mermaid
flowchart TD
A[Landing] -->|non authentifié| B[Login]
B --> C{Email vérifié ?}
C -->|oui| D[Dashboard]
C -->|non| E[Vérification OTP]
E --> D
D --> F[Onboarding complet]Ce diagramme Mermaid représente le flux d'onboarding avec branche conditionnelle. Il peut être rendu directement dans l'application ou exporté pour documentation.
Configuration XState du flow
import { createMachine } from 'xstate';
export const onboardingMachine = createMachine({
id: 'onboarding',
initial: 'landing',
states: {
landing: { on: { LOGIN: 'login' } },
login: { on: { VERIFY: 'verification', SUCCESS: 'dashboard' } },
verification: { on: { SUCCESS: 'dashboard' } },
dashboard: { type: 'final' }
}
});La machine à états formalise exactement le diagramme Mermaid. Chaque transition correspond à une action utilisateur réelle et peut être testée automatiquement.
Intégration React du flow
import { useMachine } from '@xstate/react';
import { onboardingMachine } from '../flows/onboardingMachine';
export const OnboardingFlow = () => {
const [state, send] = useMachine(onboardingMachine);
return (
<div>
{state.value === 'landing' && <button onClick={() => send({ type: 'LOGIN' })}>Commencer</button>}
{state.value === 'dashboard' && <p>Accès autorisé</p>}
</div>
);
};Le hook useMachine connecte le flow à l'interface. Les transitions sont déclenchées par les interactions utilisateur et restent synchronisées avec le diagramme.
Export et synchronisation automatisée
import { writeFileSync } from 'fs';
import { onboardingMachine } from '../flows/onboardingMachine';
const mermaid = `flowchart TD
...`; // généré depuis la machine
writeFileSync('docs/onboarding.mmd', mermaid);Un script simple convertit la définition XState en Mermaid pour maintenir la documentation à jour automatiquement lors des déploiements.
Bonnes pratiques
- Toujours synchroniser le diagramme visuel avec la machine à états source
- Nommer les états et événements de manière explicite et métier
- Ajouter des tests de couverture sur chaque transition critique
- Versionner les flows comme du code source
- Utiliser des guards et actions pour éviter la logique dans les composants UI
Erreurs courantes à éviter
- Créer des diagrammes qui ne correspondent plus au code après la première itération
- Oublier les états d'erreur et de récupération dans le flow
- Utiliser des transitions implicites sans événement explicite
- Négliger la performance des machines à états sur les parcours longs
Pour aller plus loin
Approfondissez la modélisation de flux complexes avec nos formations Learni dédiées à l'architecture UX et aux state machines.