screen-flow

Screen flow (Fluxo de telas)

Crie um fluxo de telas HTML independente a partir de capturas de tela reais do aplicativo em execução. Há três partes:

1. Mapeie as telas e os links entre elas, principalmente a partir do código, e escreva-os em flow.json.
2. Capture cada tela no aplicativo em execução com as ferramentas de agente que você possui. Para cada link, registre também seu hotspot: onde o botão, aba ou linha que o aciona está na captura de tela. O visualizador então inicia cada seta nesse ponto.
3. Construa a página com scripts/build_flow.py. O script faz o layout, as setas, pan e zoom, e incorpora as imagens. Nunca escreva o HTML do visualizador você mesmo. Gaste seu esforço em um mapa correto e boas capturas de tela.

Os caminhos abaixo são relativos à pasta desta skill (a pasta onde este arquivo está).

0. Escopo e saída

• Escopo: feature (uma funcionalidade ou fluxo, como "checkout" ou "controle parental") ou app (todas as telas). Se a solicitação não disser, use a funcionalidade que eles nomearam. Se nenhuma funcionalidade for nomeada, use o aplicativo inteiro.
• Escopo de funcionalidade: inclua as telas de entrada que levam à funcionalidade, como a aba ou tela inicial com o botão que a abre. Coloque-as em um pequeno grupo nav para que os leitores possam ver onde a funcionalidade começa. Não capture o resto do aplicativo.
• Pasta de saída: use o que o usuário pediu. Caso contrário, use screen-flows/<slug>/ no projeto: flow.json, screens/<screen-id>.png e screen-flow.html. Antes de escrever no repositório, verifique se screen-flows/ deve ser adicionado ao .gitignore. Os PNGs podem ser grandes.

1. Mapear a navegação (antes de qualquer captura de tela)

Leia o código para construir um inventário. Não clique aleatoriamente. Onde procurar:

Stack	Onde a navegação vive
React Router / TanStack Router	configuração de rotas, createBrowserRouter, <Route>, pasta routes/
Next.js / Remix / Nuxt / SvelteKit	rotas baseadas em arquivos: app/, pages/, routes/, src/routes/
Angular / Vue	*-routing.module.ts, router/index.ts
SwiftUI / UIKit	NavigationStack, TabView, .sheet, .fullScreenCover, coordenadores, storyboards/segues
Android	NavHost / rota composable(...), nav_graph.xml, Activities no manifesto, menus de navegação inferior
Flutter	GoRouter / routes: / Navigator.push, BottomNavigationBar
React Native	createNativeStackNavigator, createBottomTabNavigator, Expo Router pasta app/
TV / aplicativos 10-pés	menus baseados em foco, rails, a tecla de voltar do controle remoto, manipuladores de deep-link

Em seguida, encontre os gatilhos que vinculam as telas: botões, links, barras de abas, menus, navigate(...), router.push, .sheet(isPresented:), redirecionamentos após login, guardas. Cada gatilho se torna uma aresta.

Escreva um primeiro flow.json sem imagens. O formato completo está em references/flow-schema.md. Resumindo:

• Grupos
  • Crie exatamente um grupo kind: "nav" para o shell de navegação principal: os destinos da barra de abas ou barra lateral, a tela inicial e menus globais. Essas telas ficam juntas em uma linha no topo da tela.
  • Crie um grupo kind: "feature" por funcionalidade, com suas telas em ordem de tarefa (por exemplo: lista → detalhe → editar → confirmar).
  • Coloque onboarding, login e cadastro em seu próprio grupo de funcionalidade.
• Telas: uma por visualização distinta. Modais, sheets, diálogos e estados importantes (vazio, erro, paywall) contam como telas quando são relevantes para o fluxo. Marque-os com state. Defina entry: true na tela onde um grupo começa.
• Arestas: escreva a ação do usuário como o rótulo, como "Toque em 'Checkout'" ou "Deslize para a esquerda". Use kind para back (caminhos de retorno), modal e redirect (navegação automática). Deixe de fora links de volta óbvios, a menos que sejam importantes. Não vincule cada aba a todas as outras abas. Vincule a aba padrão a cada uma das outras, de modo que um aplicativo de 5 abas tenha 4 arestas, não 20.

Verifique o mapa com python3 scripts/build_flow.py flow.json --check. Para um aplicativo inteiro com mais de cerca de 25 telas, mostre ao usuário a lista de grupos e telas e peça que ele confirme antes de capturar qualquer coisa.

2. Capturar capturas de tela reais

Leia references/capture.md para a ferramenta e comandos a serem usados em cada plataforma. Regras para todas as plataformas:

• Use primeiro as ferramentas que seu harness fornece. Elas incluem ferramentas de navegador ou pré-visualização, ferramentas de dispositivo ou simulador, e servidores MCP Playwright/Chrome DevTools. Se você não tiver nenhuma, use as alternativas em capture.md: scripts/capture_web.mjs (Playwright), xcrun simctl io ou adb exec-out screencap.
• Execute o aplicativo você mesmo. Use as próprias instruções de execução do projeto (README, AGENTS.md/CLAUDE.md, scripts package.json, configurações de execução). Use uma compilação local ou de desenvolvimento com dados de teste.
• Faça login com uma conta de teste. Se você precisar de credenciais, pergunte ao usuário. Nunca adivinhe, nunca use a conta de um cliente real e nunca cole segredos em flow.json.
• Use um dispositivo e viewport para todo o fluxo. Para web móvel, use 390×844 a 2×. Para web desktop, use 1440×900. Para aplicativos nativos, use um modelo de simulador ou emulador. Use o mesmo tema e idioma em todos os lugares.
• Acesse cada tela da forma como um usuário faria quando isso for prático. Isso também verifica suas arestas. Se uma etapa for lenta ou instável, abra a tela diretamente com um deep link ou URL. Se o caminho real diferir do seu mapa, corrija o mapa.
• Aguarde até que a tela esteja estabilizada. Sem spinners, sem skeletons, imagens carregadas, sem toasts a menos que sejam o ponto. Feche overlays de desenvolvimento e banners de depuração.
• Nunca faça nada destrutivo ou irreversível, como pagamentos, exclusões ou envio de e-mail ou mensagens, fora de uma sandbox. Capture a tela de confirmação e pare.
• Salve cada captura de tela como screens/<screen-id>.png e defina image em flow.json.
• Registre um hotspot para cada link enquanto estiver na tela de origem: a caixa delimitadora do elemento que o usuário toca. Escreva-o no mesmo sistema de coordenadas da captura de tela (pixels da imagem ou frações de 0 a 1). Na web, scripts/capture_web.mjs faz isso para você a partir de um seletor e escreve hotspots.json. Em plataformas nativas, obtenha os limites do elemento na árvore de UI (veja capture.md). Pule para links que não são um elemento visível, como um deslize, um redirecionamento automático ou o botão de voltar do sistema.
• Olhe para cada captura de tela depois de salvá-la, usando seu visualizador de imagens ou ferramenta Read. Recapture qualquer imagem que esteja em branco, cortada, na tela errada, uma tela de login ou uma página de erro.
• Se uma tela não puder ser alcançada, mantenha-a no mapa sem image e escreva o motivo em notes. O visualizador mostra um cartão "Nenhuma captura de tela capturada" para ela.

3. Construir e verificar

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

O script precisa apenas da biblioteca padrão do Python. Ele lê hotspots.json ao lado de flow.json quando esse arquivo existe, ou um arquivo passado com --hotspots. Para manter o arquivo pequeno, ele reduz a escala de capturas de tela mais largas que --max-width (padrão 1000 px) quando Pillow ou sips do macOS estiver disponível.

Abra o HTML e observe-o. Use uma ferramenta de navegador para capturar a tela ou abra-o para o usuário. Em seguida, corrija o layout através de flow.json e reconstrua:

Problema	Correção
Telas na ordem errada dentro de um grupo	Reordene screens, defina entry: true ou fixe uma tela com "column": n
Um grupo é um conjunto solto de telas, não uma sequência	"layout": "grid" no grupo
Uma sequência longa deve ficar em uma linha	"layout": "row"
Uma funcionalidade fica longe de onde começa	Adicione a aresta que leva a ela ou defina "parent": "<group-id>"
Muitas setas	Remova links de volta que você não precisa, ou vincule abas apenas a partir da aba padrão
Uma seta começa no lugar errado em uma captura de tela	Corrija o hotspot dessa aresta (verifique no painel de detalhes)

Exportações PNG e PDF

Se o usuário pedir uma imagem ou um PDF, ou o fluxo precisar ser colocado em um pull request, ticket, Confluence ou slides, exporte-o sem cabeçalho. Isso usa o mesmo renderizador do botão Exportar da página:

node scripts/export.mjs <saida>/screen-flow.html <saida>/screen-flow.png                 # fluxo inteiro
node scripts/export.mjs <saida>/screen-flow.html <saida>/checkout.png --scope checkout   # um grupo
node scripts/export.mjs <saida>/screen-flow.html <saida>/screen-flow.pdf                 # visão geral + uma página por grupo

Opções: --theme light|dark (padrão light), --no-hotspots, --no-group-pages (PDF). O script precisa do Playwright, configurado da mesma forma que para capture_web.mjs. Olhe o PNG antes de entregá-lo.

4. Relatório

Dê ao usuário o caminho para screen-flow.html e o número de telas e grupos. Liste quaisquer telas sem captura de tela e o motivo. Mencione estes controles do visualizador:

• Arraste para mover; role ou aperte para ampliar/reduzir.
• Clique em uma tela para vê-la em tamanho grande, com seus links de entrada e saída.
• Arraste telas, ou um grupo pelo seu cabeçalho, para reorganizá-las; isso é salvo nesse navegador.
• Hotspots (botão da barra de ferramentas, ou H) inicia cada seta no botão que a aciona. No painel de detalhes, os hotspots são clicáveis, para que os leitores possam percorrer o fluxo como um protótipo.
• / pesquisa, F ajusta tudo na tela.
• Exportar (barra de ferramentas) baixa um PNG ou um PDF de tudo, da visualização atual ou de um grupo, no tema claro ou escuro. O PDF tem uma página de visão geral mais uma página por grupo. As exportações seguem as alternâncias atuais (rótulos, links entre grupos, links de volta, hotspots).
• #<screen-id> no final da URL abre essa tela.