Claude Code para iteração de UI em Flutter: um loop prático para transformar user stories em árvores de widgets, estado e navegação mantendo as mudanças modulares e fáceis de revisar.
Trabalho rápido de UI em Flutter costuma começar bem. Você ajusta um layout, adiciona um botão, move um campo, e a tela melhora rápido. O problema aparece depois de algumas rodadas, quando velocidade vira um monte de mudanças que ninguém quer revisar.
Times geralmente enfrentam as mesmas falhas:
Uma grande causa é a abordagem de “um grande prompt”: descrever a feature inteira, pedir o conjunto completo de telas e aceitar uma saída grande. A assistente tenta ajudar, mas toca em muitas partes do código de uma vez. Isso torna as mudanças confusas, difíceis de revisar e arriscadas de mesclar.
Um loop repetível conserta isso forçando clareza e limitando a área impactada. Em vez de “construa a feature”, faça isto repetidamente: escolha uma user story, gere a menor fatia de UI que resolve ela, adicione apenas o estado necessário para essa fatia e então ligue a navegação para um caminho. Cada passo fica pequeno o suficiente para revisar, e erros são fáceis de reverter.
O objetivo aqui é um fluxo prático para transformar user stories em telas concretas, manejo de estado e fluxos de navegação sem perder o controle. Bem feito, você acaba com peças de UI modulares, diffs menores e menos surpresas quando os requisitos mudam.
User stories são escritas para humanos, não para árvores de widgets. Antes de gerar qualquer coisa, converta a story em uma pequena especificação de UI que descreva o comportamento visível. “Pronto” deve ser testável: o que o usuário pode ver, tocar e confirmar, não se o design “parece moderno”.
Uma forma simples de manter o escopo concreto é dividir a story em quatro blocos:
Se a story ainda parecer vaga, responda a estas perguntas em linguagem simples:
Adicione restrições cedo porque elas guiam cada escolha de layout: noções básicas do tema (cores, espaçamento, tipografia), responsividade (primeiro celular em portrait, depois larguras de tablet) e mínimos de acessibilidade como tamanho alvo para toques, escala de texto legível e rótulos significativos para ícones.
Finalmente, decida o que é estável versus flexível para não agitar a base de código. Itens estáveis são coisas de que outras features dependem, como nomes de rotas, modelos de dados e APIs existentes. Itens flexíveis são mais seguros para iterar, como estrutura de layout, microcopy e a composição exata de widgets.
Exemplo: “Como usuário, posso salvar um item em Favoritos a partir da tela de detalhe.” Uma especificação de UI construível poderia ser:
Isso é suficiente para construir, revisar e iterar sem chutar no escuro.
Diffs pequenos não significam trabalhar mais devagar. Eles tornam cada mudança de UI fácil de revisar, fácil de desfazer e difícil de quebrar. A regra mais simples: uma tela ou uma interação por iteração.
Escolha um slice bem delimitado antes de começar. “Adicionar um estado vazio à tela Orders” é um bom slice. “Refazer todo o fluxo Orders” não é. Mire num diff que um colega consiga entender em um minuto.
Uma estrutura de pastas estável também ajuda a manter mudanças contidas. Uma organização simples orientada por feature evita que você espalhe widgets e rotas pelo app:
lib/
features/
orders/
screens/
widgets/
state/
routes.dart
Mantenha widgets pequenos e compostos. Quando um widget tem entradas e saídas claras, você pode mudar layout sem tocar na lógica de estado, e mudar estado sem reescrever a UI. Prefira widgets que recebam valores simples e callbacks, não estado global.
Um loop que permanece revisável:
Defina uma regra rígida: cada mudança deve ser fácil de reverter ou isolar. Evite refactors “drive-by” enquanto itera numa tela. Se notar problemas não relacionados, anote e corrija em um commit separado.
Se sua ferramenta suporta snapshots e rollback, use cada slice como um ponto de snapshot. Algumas plataformas de vibe-coding como Koder.ai incluem snapshots e rollback, o que pode tornar experimentos mais seguros quando você tenta uma mudança ousada de UI.
Um hábito adicional que mantém iterações iniciais calmas: prefira adicionar novos widgets em vez de editar componentes compartilhados. Componentes compartilhados são onde pequenas mudanças viram grandes diffs.
Trabalho rápido de UI fica seguro quando você separa pensar de digitar. Comece obtendo um plano claro da árvore de widgets antes de gerar código.
Peça apenas um esboço da árvore de widgets. Você quer nomes de widgets, hierarquia e o que cada parte mostra. Nada de código ainda. É aqui que você captura estados faltantes, telas vazias e escolhas estranhas de layout enquanto tudo ainda é barato de mudar.
Peça um breakdown de componentes com responsabilidades. Mantenha cada widget focado: um widget renderiza o cabeçalho, outro renderiza a lista, outro lida com empty/error UI. Se algo precisar de estado depois, anote agora, mas não implemente ainda.
Gere o scaffold da tela e widgets stateless. Comece com um único arquivo de tela com conteúdo placeholder e TODOs claros. Mantenha entradas explícitas (parâmetros de construtor) para que você possa conectar estado real depois sem reescrever a árvore.
Faça uma passada separada para estilo e detalhes de layout: espaçamentos, tipografia, theming e comportamento responsivo. Trate o styling como um diff próprio para que as revisões permaneçam simples.
Coloque restrições no início para que a assistente não invente UI que você não possa entregar:
Exemplo concreto: a user story é “Como usuário, posso revisar meus itens salvos e remover um.” Peça uma árvore de widgets que inclua um app bar, uma lista com linhas de item e um estado vazio. Então solicite um breakdown como SavedItemsScreen, SavedItemTile, EmptySavedItems. Só depois gere o scaffold com widgets stateless e dados falsos, e finalmente adicione estilo (divider, padding e um botão claro de remover) em uma passada separada.
A iteração de UI desanda quando todo widget começa a tomar decisões. Mantenha a árvore de widgets “burra”: ela deve ler estado e renderizar, não conter regras de negócio.
Comece nomeando os estados em palavras simples. A maioria das features precisa de mais do que “loading” e “done”:
Depois liste os eventos que podem mudar o estado: toques, submit de formulário, pull-to-refresh, voltar, retry e “usuário editou um campo”. Fazer isso antes evita chutes depois.
Escolha uma abordagem de estado para a feature e mantenha-a. O objetivo não é “o melhor padrão”, e sim diffs consistentes.
Para uma tela pequena, um controller simples (como ChangeNotifier ou ValueNotifier) frequentemente basta. Coloque a lógica em um lugar só:
Antes de adicionar código, escreva as transições de estado em inglês simples. Exemplo para uma tela de login:
"Quando o usuário tocar em Sign in: setar Loading. Se o email for inválido: permanecer em Partial input e mostrar mensagem inline. Se a senha estiver errada: setar Error com uma mensagem e habilitar Retry. Se sucesso: setar Success e navegar para Home."
Então gere o código Dart mínimo que corresponda a essas sentenças. Revisões permanecem simples porque você pode comparar o diff com as regras.
Torne validação explícita. Decida o que acontece quando inputs são inválidos:
Com essas respostas escritas, sua UI fica limpa e o código de estado permanece pequeno.
Boa navegação começa como um mapa pequeno, não uma pilha de rotas. Para cada user story, escreva quatro momentos: onde o usuário entra, o próximo passo mais provável, como cancelar e o que “voltar” significa (voltar para a tela anterior ou para um estado inicial seguro).
Um mapa de rotas simples deve responder às perguntas que normalmente causam retrabalho:
Depois defina os parâmetros passados entre telas. Seja explícito: IDs (productId, orderId), filtros (intervalo de datas, status) e dados de rascunho (um formulário parcialmente preenchido). Se pular isso, você vai acabar escondendo estado em singletons globais ou reconstuindo telas para “encontrar” contexto.
Deep links importam mesmo que você não lance eles no dia 1. Decida o que acontece quando um usuário chega no meio do fluxo: você consegue carregar dados faltantes ou deve redirecionar para uma tela de entrada segura?
Também decida quais telas devem retornar resultados. Exemplo: uma tela “Select Address” retorna um addressId, e a tela de checkout atualiza sem refresh completo. Mantenha o formato de retorno pequeno e tipado para que mudanças continuem fáceis de revisar.
Antes de codificar, aponte casos de borda: mudanças não salvas (mostrar diálogo de confirmação), autenticação necessária (pausar e retomar depois do login) e dados faltantes ou deletados (mostrar erro e um caminho claro de saída).
Quando você itera rápido, o risco real não é a UI “estar errada”. É a UI ser irrevisável. Se um colega não consegue dizer o que mudou, por que mudou e o que ficou estável, cada próxima iteração fica mais lenta.
Uma regra que ajuda: trave as interfaces primeiro e então permita que os internos se mexam. Estabilize props públicas de widgets (inputs), pequenos modelos de UI e argumentos de rota. Uma vez nomeados e tipados, você pode remodelar a árvore de widgets sem quebrar o resto do app.
Peça um plano favorável a diffs antes de gerar código. Você quer um plano que diga quais arquivos vão mudar e quais devem permanecer intocados. Isso mantém revisões focadas e evita refactors acidentais que alteram comportamento.
Padrões que mantêm diffs pequenos:
Diga que a user story é “Como comprador, posso editar meu endereço de envio no checkout.” Trave os args de rota primeiro: CheckoutArgs(cartId, shippingAddressId) permanece estável. Então itere dentro da tela. Quando o layout estiver estável, divida em AddressForm, AddressSummary e SaveBar.
Se o manejo de estado mudar (por exemplo, validação sai do widget para um CheckoutController), a revisão continua legível: arquivos de UI mudam principalmente na renderização, enquanto o controller concentra a mudança de lógica em um lugar só.
A forma mais rápida de desacelerar é pedir à assistente para mudar tudo de uma vez. Se um commit tocar layout, estado e navegação, revisores não sabem o que quebrou, e reverter vira bagunça.
Um hábito mais seguro é uma intenção por iteração: molde a árvore, depois ligue o estado, depois conecte a navegação.
Um problema comum é deixar o código gerado inventar um novo padrão a cada tela. Se uma página usa Provider, outra usa setState e a terceira introduz uma controller customizada, o app vira inconsistente rápido. Escolha um pequeno conjunto de padrões e os aplique.
Outro erro é colocar trabalho assíncrono diretamente dentro de build(). Pode até funcionar numa demo rápida, mas dispara chamadas repetidas em rebuilds, flicker e bugs difíceis de rastrear. Mova a chamada para initState(), um view model ou um controller dedicado, e mantenha build() focado em renderizar.
Nomear mal é uma armadilha silenciosa. Código que compila mas lê como Widget1, data2 ou temp torna refactors futuros dolorosos. Nomes claros também ajudam a assistente a produzir mudanças de follow-up melhores porque a intenção fica óbvia.
Guardiões que previnem os piores resultados:
build()Um conserto visual clássico é adicionar mais Container, Padding, Align e SizedBox até ficar certo. Depois de algumas passadas, a árvore vira ilegível.
Se um botão está desalinhado, tente primeiro remover wrappers, usar um único widget de layout pai ou extrair um pequeno widget com suas próprias restrições.
Exemplo: uma tela de checkout onde o preço total pula ao carregar. Uma assistente pode envolver a linha do preço em mais widgets para “estabilizar” ela. Uma correção mais limpa é reservar espaço com um placeholder de loading simples mantendo a estrutura da linha inalterada.
Antes de commitar, faça uma passada de dois minutos que verifica valor ao usuário e te protege de regressões surpresas. O objetivo não é perfeição. É garantir que essa iteração seja fácil de revisar, testar e desfazer.
Leia a user story uma vez, depois verifique estes itens contra o app em execução (ou ao menos contra um widget test simples):
Um cheque rápido de realidade: se você adicionou uma nova tela de Order details, você deveria conseguir (1) abri-la a partir da lista, (2) ver um spinner de loading, (3) simular um erro, (4) ver um pedido vazio e (5) apertar voltar para retornar à lista sem pulos estranhos.
Se seu fluxo suporta snapshots e rollback, tire um snapshot antes de mudanças maiores de layout. Plataformas como Koder.ai suportam isso e podem ajudar a iterar mais rápido sem arriscar a branch principal.
User story: "Como comprador, posso navegar por itens, abrir uma página de detalhes, salvar um item em favoritos e depois ver meus favoritos." O objetivo é ir das palavras para telas em três passos pequenos e revisáveis.
Iteração 1: foque apenas na tela de lista de navegação. Crie uma árvore de widgets suficiente para renderizar mas não ligada a dados reais: um Scaffold com AppBar, um ListView de linhas placeholder e UI clara para loading e empty. Mantenha estado simples: loading (mostra CircularProgressIndicator), empty (mostra uma mensagem curta e talvez um botão Tentar novamente) e ready (mostra a lista).
Iteração 2: adicione a tela de detalhes e navegação. Seja explícito: onTap faz push de uma rota e passa um pequeno objeto de parâmetro (por exemplo: item id, title). Comece a página de detalhes como read-only com título, descrição placeholder e um botão de Ação Favorite. O objetivo é casar com a story: lista -> detalhes -> voltar, sem fluxos extras.
Iteração 3: introduza updates de estado de favoritos e feedback visual. Adicione uma única fonte de verdade para favoritos (mesmo que ainda esteja em memória) e conecte-a às duas telas. Tocar em Favorite atualiza o ícone imediatamente e mostra uma confirmação pequena (como um SnackBar). Depois adicione uma tela Favorites que lê o mesmo estado e lida com o estado vazio.
Um diff revisável geralmente parece com isto:
browse_list_screen.dart: árvore de widgets mais UI de loading/empty/readyitem_details_screen.dart: layout de UI e aceita params de navegaçãofavorites_store.dart: holder mínimo de estado e métodos de atualizaçãoapp_routes.dart: rotas e helpers de navegação tipadosfavorites_screen.dart: lê estado e mostra empty/list UISe qualquer arquivo virar “o lugar onde tudo acontece”, quebre-o antes de seguir adiante. Arquivos pequenos com nomes claros aceleram a próxima iteração.
Se o fluxo só funciona quando você está “no modo”, ele vai quebrar quando você trocar de tela ou um colega tocar na feature. Torne o loop um hábito escrevendo-o e colocando guardrails sobre o tamanho da mudança.
Use um template de time para que cada iteração comece com as mesmas entradas e produza o mesmo tipo de saída. Mantenha curto mas específico:
Isso reduz a chance de a assistente inventar novos padrões no meio da feature.
Escolha uma definição de pequeno que seja fácil de aplicar em revisão de código. Por exemplo, limite cada iteração a um número reduzido de arquivos e separe refactors de UI de mudanças de comportamento.
Um conjunto simples de regras:
Adicione checkpoints para poder desfazer um passo ruim rapidamente. Pelo menos, tagueie commits ou mantenha checkpoints locais antes de refactors maiores. Se seu fluxo suporta snapshots/rollback, use-os agressivamente.
Se quiser um fluxo baseado em chat que possa gerar e refinar apps Flutter de ponta a ponta, Koder.ai inclui um modo de planejamento que te ajuda a revisar um plano e os arquivos esperados antes de aplicá-los.
Use uma especificação de UI pequena e testável primeiro. Escreva 3–6 linhas que cubram:
Depois, construa apenas esse slice (geralmente uma tela + 1–2 widgets).
Converta a story em quatro blocos:
Se você não consegue descrever o critério de aceitação rapidamente, a story ainda está vaga demais para um diff limpo.
Comece gerando apenas um esboço da árvore de widgets (nomes + hierarquia + o que cada parte mostra). Sem código.
Depois, peça um quebra-down de responsabilidades dos componentes (o que cada widget deve fazer).
Só então gere o scaffold stateless com entradas explícitas (valores + callbacks), e trate o styling em uma passada separada.
Trate isso como uma regra rígida: uma intenção por iteração.
Se um único commit altera layout, estado e rotas, os revisores não saberão o que causou um bug e reverter vira complicado.
Mantenha os widgets “burros”: eles devem renderizar o estado, não decidir regras de negócio.
Um padrão prático:
Evite chamadas assíncronas dentro de — isso causa chamadas repetidas em rebuilds.
Defina estados e transições em linguagem simples antes de codificar.
Padrão exemplo:
Depois liste os eventos que movem entre eles (refresh, retry, submit, edit). O código fica mais fácil de comparar com as regras escritas.
Escreva um pequeno “mapa de fluxo” para a story:
Padronize pastas por feature para manter mudanças contidas. Por exemplo:
lib/features/<feature>/screens/lib/features/<feature>/widgets/lib/features/<feature>/state/lib/features/<feature>/routes.dartMantenha cada iteração focada numa pasta de feature e evite refactors ocasionais em outras áreas.
Uma regra simples: estabilize interfaces, não internals.
Revisores se importam mais que inputs/outputs estejam estáveis mesmo se o layout mudar internamente.
Faça uma verificação rápida de dois minutos:
Se o seu fluxo suporta snapshots/rollback, tire um snapshot antes de um refactor maior para poder reverter com segurança.
build()Também trave o que viaja entre telas (IDs, filtros, dados de rascunho) para evitar esconder contexto em singletons globais.