screen-flow (parcours d'écrans)

Screen flow

Créez un screen flow HTML autonome à partir de captures d'écran réelles de l'application en cours d'exécution. Il y a trois parties :

1. Cartographiez les écrans et les liens entre eux, principalement à partir du code, et écrivez-les dans flow.json.
2. Capturez chaque écran dans l'application en cours d'exécution avec les outils d'agent dont vous disposez. Pour chaque lien, enregistrez également son point d'accès (hotspot) : l'endroit où se trouve le bouton, l'onglet ou la ligne qui le déclenche sur la capture d'écran. La visionneuse démarre alors chaque flèche à partir de cet endroit.
3. Construisez la page avec scripts/build_flow.py. Le script se charge de la mise en page, des flèches, du panoramique et du zoom, et intègre les images. N'écrivez jamais le code HTML de la visionneuse vous-même. Consacrez vos efforts à une carte correcte et à de bonnes captures d'écran.

Les chemins ci-dessous sont relatifs au dossier de cette compétence (le dossier dans lequel se trouve ce fichier).

0. Périmètre et résultat

• Périmètre : feature (une fonctionnalité ou un flux, par exemple "checkout" ou "contrôle parental") ou app (tous les écrans). Si la demande ne le précise pas, utilisez la fonctionnalité qu'ils ont nommée. Sans fonctionnalité nommée, utilisez toute l'application.
• Périmètre de la fonctionnalité : incluez les écrans d'entrée qui mènent à la fonctionnalité, comme l'onglet ou l'écran d'accueil avec le bouton qui l'ouvre. Placez-les dans un petit groupe nav afin que les lecteurs puissent voir où la fonctionnalité commence. Ne capturez pas le reste de l'application.
• Dossier de sortie : utilisez ce que l'utilisateur a demandé. Sinon, utilisez screen-flows/<slug>/ dans le projet : flow.json, screens/<screen-id>.png, et screen-flow.html. Avant d'écrire dans le dépôt, vérifiez si screen-flows/ doit être ajouté à .gitignore. Les PNG peuvent être volumineux.

1. Cartographie de la navigation (avant toute capture d'écran)

Lisez le code pour établir un inventaire. Ne naviguez pas au hasard. Où chercher :

Stack	Où se trouve la navigation
React Router / TanStack Router	config de route, createBrowserRouter, <Route>, dossier routes/
Next.js / Remix / Nuxt / SvelteKit	routes basées sur les fichiers : app/, pages/, routes/, src/routes/
Angular / Vue	*-routing.module.ts, router/index.ts
SwiftUI / UIKit	NavigationStack, TabView, .sheet, .fullScreenCover, coordinateurs, storyboards/segues
Android	NavHost / composable(...) routes, nav_graph.xml, Activités dans le manifeste, menus de navigation inférieurs
Flutter	GoRouter / routes: / Navigator.push, BottomNavigationBar
React Native	createNativeStackNavigator, createBottomTabNavigator, dossier app/ Expo Router
TV / applications 10 pieds	menus basés sur le focus, rails, touche retour de la télécommande, gestionnaires de liens profonds

Ensuite, trouvez les déclencheurs qui lient les écrans : boutons, liens, barres d'onglets, menus, navigate(...), router.push, .sheet(isPresented:), redirections après connexion, gardes. Chaque déclencheur devient une arête.

Écrivez un premier flow.json sans images. Le format complet se trouve dans references/flow-schema.md. En résumé :

• Groupes
  • Créez exactement un groupe kind: "nav" pour le shell de navigation principal : les destinations de la barre d'onglets ou de la barre latérale, l'écran d'accueil et les menus globaux. Ces écrans sont regroupés sur une seule rangée en haut du canevas.
  • Créez un groupe kind: "feature" par fonctionnalité, avec ses écrans dans l'ordre des tâches (par exemple : liste → détail → modifier → confirmer).
  • Placez l'intégration, la connexion et l'inscription dans leur propre groupe de fonctionnalités.
• Écrans : un par vue distincte. Les modales, les feuilles, les dialogues et les états importants (vide, erreur, paywall) comptent comme des écrans lorsqu'ils sont importants pour le flux. Marquez-les avec state. Définissez entry: true sur l'écran où un groupe commence.
• Arêtes : écrivez l'action de l'utilisateur comme étiquette, par exemple "Appuyer sur 'Commander'" ou "Glisser vers la gauche". Utilisez kind pour back (chemins de retour), modal et redirect (navigation automatique). Omettez les liens de retour évidents sauf s'ils sont importants. Ne créez pas de lien entre chaque onglet et chaque autre onglet. Créez un lien depuis l'onglet par défaut vers chacun des autres, de sorte qu'une application à 5 onglets ait 4 arêtes, et non 20.

Vérifiez la carte avec python3 scripts/build_flow.py flow.json --check. Pour une application entière avec plus d'environ 25 écrans, montrez à l'utilisateur la liste des groupes et des écrans et demandez-lui de la confirmer avant de capturer quoi que ce soit.

2. Capturer de vraies captures d'écran

Lisez references/capture.md pour l'outil et les commandes à utiliser sur chaque plateforme. Règles pour toutes les plateformes :

• Utilisez d'abord les outils fournis par votre environnement. Ceux-ci incluent les outils de navigateur ou d'aperçu, les outils de périphérique ou de simulateur, et les serveurs MCP Playwright/Chrome DevTools. Si vous n'en avez aucun, utilisez les solutions de repli dans capture.md : scripts/capture_web.mjs (Playwright), xcrun simctl io, ou adb exec-out screencap.
• Exécutez l'application vous-même. Utilisez les instructions d'exécution du projet (README, AGENTS.md/CLAUDE.md, scripts package.json, configurations d'exécution). Utilisez une version locale ou de développement avec des données de test.
• Connectez-vous avec un compte de test. Si vous avez besoin d'identifiants, demandez à l'utilisateur. Ne devinez jamais, n'utilisez jamais le compte d'un vrai client et ne collez jamais de secrets dans flow.json.
• Utilisez un seul appareil et une seule fenêtre d'affichage pour tout le flux. Pour le Web mobile, utilisez 390×844 à 2×. Pour le Web de bureau, utilisez 1440×900. Pour les applications natives, utilisez un seul modèle de simulateur ou d'émulateur. Utilisez le même thème et la même langue partout.
• Accédez à chaque écran comme le ferait un utilisateur lorsque cela est pratique. Cela vérifie également vos arêtes. Si une étape est lente ou instable, ouvrez l'écran directement avec un lien profond ou une URL. Si le chemin réel diffère de votre carte, corrigez la carte.
• Attendez que l'écran se soit stabilisé. Pas de spinners, pas de squelettes, images chargées, pas de toasts sauf s'ils sont le sujet. Fermez les superpositions de développement et les bannières de débogage.
• Ne faites jamais rien de destructeur ou d'irréversible, comme des paiements, des suppressions ou l'envoi d'e-mails ou de messages, en dehors d'un bac à sable. Capturez l'écran de confirmation et arrêtez-vous là.
• Enregistrez chaque capture d'écran sous screens/<screen-id>.png, et définissez image dans flow.json.
• Enregistrez un point d'accès (hotspot) pour chaque lien pendant que vous êtes sur l'écran source : la boîte englobante de l'élément sur lequel l'utilisateur appuie. Écrivez-le dans le même système de coordonnées que la capture d'écran (pixels de l'image, ou fractions de 0 à 1). Sur le Web, scripts/capture_web.mjs le fait pour vous à partir d'un sélecteur et écrit hotspots.json. Sur les plateformes natives, prenez les limites de l'élément à partir de l'arborescence UI (voir capture.md). Ignorez-le pour les liens qui ne sont pas un élément visible, comme un glissement, une redirection automatique ou le bouton de retour système.
• Examinez chaque capture d'écran après l'avoir enregistrée, à l'aide de votre visionneuse d'images ou de votre outil de lecture. Recapturez toute image qui est vide, recadrée, le mauvais écran, un écran de connexion ou une page d'erreur.
• Si un écran ne peut pas être atteint, conservez-le dans la carte sans image et écrivez la raison dans notes. La visionneuse affiche une carte "Aucune capture d'écran capturée" pour celui-ci.

3. Construire et vérifier

python3 scripts/build_flow.py <out>/flow.json            # écrit <out>/screen-flow.html
python3 scripts/build_flow.py <out>/flow.json -o docs/flow.html --max-width 900

Le script n'a besoin que de la bibliothèque standard Python. Il lit hotspots.json à côté de flow.json lorsque ce fichier existe, ou un fichier que vous passez avec --hotspots. Pour garder le fichier petit, il réduit les captures d'écran plus larges que --max-width (1000 px par défaut) lorsque Pillow ou sips macOS est disponible.

Ouvrez le HTML et regardez-le. Utilisez un outil de navigateur pour le capturer, ou ouvrez-le pour l'utilisateur. Ensuite, corrigez la mise en page via flow.json et reconstruisez :

Problème	Correctif
Écrans dans le mauvais ordre au sein d'un groupe	Réorganisez screens, définissez entry: true, ou épinglez un écran avec "column": n
Un groupe est un ensemble lâche d'écrans, pas une séquence	"layout": "grid" sur le groupe
Une longue séquence doit s'afficher sur une seule rangée	"layout": "row"
Une fonctionnalité est loin de son point de départ	Ajoutez l'arête qui y mène, ou définissez "parent": "<group-id>"
Trop de flèches	Supprimez les liens de retour dont vous n'avez pas besoin, ou liez les onglets uniquement à partir de l'onglet par défaut
Une flèche commence au mauvais endroit sur une capture d'écran	Corrigez le hotspot de cette arête (vérifiez-le dans le panneau de détails)

Exportations PNG et PDF

Si l'utilisateur demande une image ou un PDF, ou si le flux doit être intégré dans une pull request, un ticket, Confluence ou des diapositives, exportez-le sans tête. Cela utilise le même moteur de rendu que le bouton d'exportation de la page :

node scripts/export.mjs <out>/screen-flow.html <out>/screen-flow.png                 # flux entier
node scripts/export.mjs <out>/screen-flow.html <out>/checkout.png --scope checkout   # un groupe
node scripts/export.mjs <out>/screen-flow.html <out>/screen-flow.pdf                 # vue d'ensemble + une page par groupe

Options : --theme light|dark (light par défaut), --no-hotspots, --no-group-pages (PDF). Le script a besoin de Playwright, configuré de la même manière que pour capture_web.mjs. Examinez le PNG avant de le remettre.

4. Rapport

Donnez à l'utilisateur le chemin d'accès à screen-flow.html et le nombre d'écrans et de groupes. Listez tous les écrans sans capture d'écran et la raison. Mentionnez ces contrôles de la visionneuse :

• Faites glisser pour vous déplacer ; faites défiler ou pincez pour zoomer.
• Cliquez sur un écran pour le voir en grand, avec ses liens entrants et sortants.
• Faites glisser les écrans, ou un groupe par son en-tête, pour les réorganiser ; cela est sauvegardé dans ce navigateur.
• Points d'accès (Hotspots) (bouton de la barre d'outils, ou H) démarre chaque flèche au bouton qui la déclenche. Dans le panneau de détails, les points d'accès sont cliquables, de sorte que les lecteurs peuvent cliquer sur le flux comme un prototype.
• / recherche, F ajuste tout à l'écran.
• Exportation (barre d'outils) télécharge un PNG ou un PDF de tout, de la vue actuelle ou d'un groupe, dans le thème clair ou sombre. Le PDF a une page de vue d'ensemble plus une page par groupe. Les exportations suivent les bascules actuelles (étiquettes, liens entre groupes, liens de retour, points d'accès).
• #<screen-id> à la fin de l'URL ouvre cet écran.