screen-flow (Bildschirmfluss)

Was macht screen-flow (Bildschirmfluss)?

Erstelle einen eigenständigen HTML-Bildschirmfluss aus echten Screenshots der laufenden App. Es gibt drei Teile:

1. Kartiere die Bildschirme und die Links zwischen ihnen, hauptsächlich aus dem Code, und schreibe sie in flow.json.
2. Erfasse jeden Bildschirm in der laufenden App mit den dir zur Verfügung stehenden Agent-Tools. Zeichne für jeden Link auch seinen Hotspot auf: die Stelle des Buttons, Tabs oder der Zeile, die ihn auslöst, auf dem Screenshot. Der Viewer startet dann jeden Pfeil an dieser Stelle.
3. Baue die Seite mit scripts/build_flow.py. Das Skript übernimmt das Layout, die Pfeile, Schwenken und Zoomen, und bettet die Bilder ein. Schreibe niemals das Viewer-HTML selbst. Verwende deine Mühe auf eine korrekte Karte und gute Screenshots.

Die Pfade unten sind relativ zu diesem Skill-Ordner (dem Ordner, in dem diese Datei liegt).

0. Umfang und Ausgabe

• Umfang: feature (ein Feature oder Flow, z. B. "Checkout" oder "Kindersicherung") oder app (alle Screens). Wenn die Anfrage nichts sagt, verwende das genannte Feature. Ohne Nennung eines Features verwende die gesamte App.
• Feature-Umfang: Füge die Einstiegsbildschirme hinzu, die in das Feature führen, wie den Tab- oder Startbildschirm mit dem Button, der es öffnet. Platziere sie in einer kleinen nav-Gruppe, damit Leser sehen, wo das Feature beginnt. Erfasse nicht den Rest der App.
• Ausgabe-Ordner: Verwende, wonach der Benutzer gefragt hat. Andernfalls verwende screen-flows/<slug>/ im Projekt: flow.json, screens/<screen-id>.png und screen-flow.html. Prüfe vor dem Schreiben in das Repository, ob screen-flows/ zu .gitignore hinzugefügt werden sollte. Die PNGs können groß sein.

1. Navigation kartieren (vor allen Screenshots)

Lies den Code, um ein Inventar zu erstellen. Klicke nicht wahllos herum. Wo suchen:

Stack	Wo Navigation lebt
React Router / TanStack Router	Routenkonfiguration, createBrowserRouter, <Route>, routes/ Ordner
Next.js / Remix / Nuxt / SvelteKit	Dateibasierte Routen: app/, pages/, routes/, src/routes/
Angular / Vue	*-routing.module.ts, router/index.ts
SwiftUI / UIKit	NavigationStack, TabView, .sheet, .fullScreenCover, Koordinatoren, Storyboards/Sequences
Android	NavHost / composable(...) Routen, nav_graph.xml, Activities im Manifest, untere Navigationsmenüs
Flutter	GoRouter / routes: / Navigator.push, BottomNavigationBar
React Native	createNativeStackNavigator, createBottomTabNavigator, Expo Router app/ Ordner
TV / 10-Fuß-Apps	Fokus-basierte Menüs, Rails, die Zurück-Taste der Fernbedienung, Deep-Link-Handler

Finde dann die Auslöser, die Bildschirme verlinken: Buttons, Links, Tab-Leisten, Menüs, navigate(...), router.push, .sheet(isPresented:), Weiterleitungen nach Login, Guards. Jeder Auslöser wird zu einer Kante.

Schreibe ein erstes flow.json ohne Bilder. Das vollständige Format ist in references/flow-schema.md. Kurz:

• Gruppen
  • Erstelle genau eine kind: "nav"-Gruppe für die primäre Navigationshülle: die Tab-Leisten- oder Seitenleisten-Ziele, den Startbildschirm und globale Menüs. Diese Screens sitzen gemeinsam in einer Reihe oben auf der Leinwand.
  • Erstelle eine kind: "feature"-Gruppe pro Feature, mit seinen Screens in Aufgabenreihenfolge (z. B.: Liste → Detail → Bearbeiten → Bestätigen).
  • Setze Onboarding, Login und Registrierung in eine eigene Feature-Gruppe.
• Screens: einer pro eigenständiger Ansicht. Modals, Sheets, Dialoge und wichtige Zustände (leer, Fehler, Paywall) zählen als Screens, wenn sie für den Flow relevant sind. Markiere sie mit state. Setze entry: true auf dem Screen, wo eine Gruppe beginnt.
• Kanten: Schreibe die Benutzeraktion als Label, z. B. "Tippe auf 'Checkout'" oder "Wische nach links". Verwende kind für back (Rückwege), modal und redirect (automatische Navigation). Lasse offensichtliche Zurück-Links weg, es sei denn, sie sind wichtig. Verlinke nicht jeden Tab mit jedem anderen Tab. Verlinke den Standard-Tab mit jedem der anderen, so dass eine App mit 5 Tabs 4 Kanten hat, nicht 20.

Überprüfe die Karte mit python3 scripts/build_flow.py flow.json --check. Für eine gesamte App mit mehr als etwa 25 Screens, zeige dem Benutzer die Liste der Gruppen und Screens und bitte ihn, sie zu bestätigen, bevor du etwas erfasst.

2. Echte Screenshots erfassen

Lies references/capture.md für das Tool und die Befehle, die auf jeder Plattform zu verwenden sind. Regeln für jede Plattform:

• Verwende zuerst die Tools, die dir dein Harness gibt. Dazu gehören Browser- oder Vorschau-Tools, Geräte- oder Simulator-Tools und Playwright/Chrome DevTools MCP Server. Wenn du keine hast, verwende die Fallbacks in capture.md: scripts/capture_web.mjs (Playwright), xcrun simctl io oder adb exec-out screencap.
• Starte die App selbst. Verwende die eigenen Startanweisungen des Projekts (README, AGENTS.md/CLAUDE.md, package.json Skripte, Run-Konfigurationen). Verwende einen lokalen oder Dev-Build mit Testdaten.
• Melde dich an mit einem Testkonto. Wenn du Anmeldedaten benötigst, frage den Benutzer. Rate niemals, verwende niemals ein echtes Kundenkonto und füge niemals Geheimnisse in flow.json ein.
• Verwende ein Gerät und einen Viewport für den gesamten Flow. Für mobiles Web verwende 390×844 bei 2×. Für Desktop-Web verwende 1440×900. Für native Apps verwende ein Simulator- oder Emulator-Modell. Verwende überall das gleiche Design und die gleiche Sprache.
• Gelange zu jedem Bildschirm so, wie es ein Benutzer tun würde, wenn das praktikabel ist. Dies überprüft auch deine Kanten. Wenn ein Schritt langsam oder instabil ist, öffne den Bildschirm direkt mit einem Deep Link oder einer URL. Wenn der tatsächliche Pfad von deiner Karte abweicht, korrigiere die Karte.
• Warte, bis sich der Bildschirm beruhigt hat. Keine Spinner, keine Skelette, Bilder geladen, keine Toasts, es sei denn, sie sind der Punkt. Schließe Dev-Overlays und Debug-Banner.
• Führe niemals destruktive oder irreversible Aktionen durch, wie Zahlungen, Löschungen oder das Senden von E-Mails oder Nachrichten, außerhalb einer Sandbox. Erfasse den Bestätigungsbildschirm und höre dort auf.
• Speichere jeden Screenshot als screens/<screen-id>.png und setze image in flow.json.
• Zeichne einen Hotspot für jeden Link auf, während du auf dem Quellbildschirm bist: das Begrenzungsrechteck des Elements, auf das der Benutzer tippt. Schreibe es im gleichen Koordinatensystem wie den Screenshot (Pixel des Bildes oder Brüche von 0 bis 1). Im Web erledigt scripts/capture_web.mjs dies für dich anhand eines Selektors und schreibt hotspots.json. Auf nativen Plattformen nimm die Elementgrenzen aus dem UI-Baum (siehe capture.md). Überspringe es für Links, die kein sichtbares Element sind, wie z. B. einen Wisch, eine automatische Weiterleitung oder die System-Zurück-Taste.
• Betrachte jeden Screenshot, nachdem du ihn gespeichert hast, mit deinem Bildbetrachter oder Read-Tool. Erfasse jeden Schuss erneut, der leer, abgeschnitten, der falsche Bildschirm, eine Login-Wand oder eine Fehlerseite ist.
• Wenn ein Bildschirm nicht erreicht werden kann, behalte ihn in der Karte ohne image und schreibe den Grund in notes. Der Viewer zeigt dafür eine Karte "Kein Screenshot erfasst" an.

3. Bauen und überprüfen

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

Das Skript benötigt nur die Python-Standardbibliothek. Es liest hotspots.json neben flow.json, wenn diese Datei existiert, oder eine Datei, die du mit --hotspots übergibst. Um die Datei klein zu halten, skaliert es Screenshots, die breiter als --max-width (Standard 1000 px) sind, herunter, wenn Pillow oder macOS sips verfügbar ist.

Öffne das HTML und schau es dir an. Verwende ein Browser-Tool, um einen Screenshot davon zu machen, oder öffne es für den Benutzer. Korrigiere dann das Layout über flow.json und baue neu:

Problem	Lösung
Screens in der falschen Reihenfolge innerhalb einer Gruppe	screens neu anordnen, entry: true setzen oder einen Screen mit "column": n fixieren
Eine Gruppe ist eine lose Sammlung von Screens, keine Sequenz	"layout": "grid" auf der Gruppe
Eine lange Sequenz soll in einer Reihe laufen	"layout": "row"
Ein Feature sitzt weit von seinem Startpunkt entfernt	Füge die Kante hinzu, die hineinführt, oder setze "parent": "<group-id>"
Zu viele Pfeile	Entferne nicht benötigte Zurück-Links oder verlinke Tabs nur vom Standard-Tab aus
Ein Pfeil beginnt an der falschen Stelle auf einem Screenshot	Korrigiere den hotspot dieser Kante (überprüfe ihn im Detail-Panel)

PNG- und PDF-Exporte

Wenn der Benutzer nach einem Bild oder einem PDF fragt, oder der Flow in einen Pull Request, ein Ticket, Confluence oder Folien muss, exportiere ihn kopflos. Dies verwendet den gleichen Renderer wie die Export-Schaltfläche der Seite:

node scripts/export.mjs <out>/screen-flow.html <out>/screen-flow.png                 # gesamter Flow
node scripts/export.mjs <out>/screen-flow.html <out>/checkout.png --scope checkout   # eine Gruppe
node scripts/export.mjs <out>/screen-flow.html <out>/screen-flow.pdf                 # Übersicht + eine Seite pro Gruppe

Optionen: --theme light|dark (Standard light), --no-hotspots, --no-group-pages (PDF). Das Skript benötigt Playwright, eingerichtet wie für capture_web.mjs. Betrachte das PNG, bevor du es übergibst.

4. Bericht

Gib dem Benutzer den Pfad zu screen-flow.html und die Anzahl der Screens und Gruppen. Liste alle Screens ohne Screenshot und den Grund auf. Erwähne diese Viewer-Steuerungen:

• Ziehen zum Schwenken; Scrollen oder Pinch-to-Zoom.
• Klicke auf einen Screen, um ihn groß zu sehen, mit seinen eingehenden und ausgehenden Links.
• Ziehe Screens oder eine Gruppe an ihrer Überschrift, um sie neu anzuordnen; dies wird in diesem Browser gespeichert.
• Hotspots (Toolbar-Button oder H) starten jeden Pfeil an dem Button, der ihn auslöst. Im Detail-Panel sind die Hotspots anklickbar, so dass Leser wie durch einen Prototypen durch den Flow klicken können.
• / sucht, F passt alles auf den Bildschirm.
• Export (Toolbar) lädt ein PNG oder ein PDF von allem, der aktuellen Ansicht oder einer Gruppe, im hellen oder dunklen Design herunter. Das PDF hat eine Übersichtsseite plus eine Seite pro Gruppe. Exporte folgen den aktuellen Umschaltern (Labels, Gruppenübergreifende Links, Zurück-Links, Hotspots).
• #<screen-id> am Ende der URL öffnet diesen Screen.