Flutter Motion UI
Este skill produz telas Flutter que parecem um produto único e coeso: cada elemento chega com intenção, cada toque responde, cada mudança de estado é visível e os dados permanecem consistentes entre as telas.
Foi destilado a partir da análise quadro a quadro de 22 gravações de aplicativos de referência (carteira, entrega, compartilhamento de viagens, fitness, autenticação/OTP, alarme, checkout, reserva, pareamento de dispositivos). O arquivo references/video-analysis.md lista o que cada um faz e qual receita o reproduz.
A ideia central: o estado impulsiona o movimento
Quase todo momento "suave" nas referências é o mesmo mecanismo: um pedaço de estado mudou, e a UI animou do valor antigo para o novo. Ninguém chamou controller.forward() a partir de um manipulador de botão. Portanto, o trabalho é sempre:
- Modelar os estados da tela explicitamente (uma classe lacrada, não cinco booleanos).
- Renderizar com um
switchsobre esse estado. - Envolver o que muda em uma animação implícita (
AnimatedSwitcher,AnimatedContainer,TweenAnimationBuilderou um widget do kit) para que a diferença entre dois estados se anime por si só.
Quando isso é feito, animação e gerenciamento de estado deixam de ser dois problemas. Animações interrompidas, toques duplos e bugs de "spinner de carregamento ao lado do ícone de sucesso" desaparecem porque os estados impossíveis não podem ser representados.
AnimationControllers explícitos são reservados para três coisas: gestos guiados pelos dedos, ambiente em loop (pulsos, scanners) e sequências coreografadas de várias partes.
Fluxo de trabalho
1. Leia o projeto antes de escrever qualquer coisa
pubspec.yaml: Flutter/Dart SDK, biblioteca de estado já em uso (riverpod / bloc / provider / getx / nenhum), roteador (go_router / auto_route / Navigator), pacotes de animação existentes.- Tema, cores, espaçamento e widgets compartilhados existentes. Estenda o que já existe; não introduza um segundo sistema de design ou uma segunda biblioteca de estado. Corresponda à estrutura de pastas e nomenclatura do projeto. Em um aplicativo existente, mantenha as alterações em arquivos que não foram solicitados tão pequenas quanto o recurso precisa (um wrapper
Hero, um pequeno padding), deixe limpezas de lint ou estilo não relacionadas em paz, a menos que solicitado, e liste cada arquivo existente que você reescreveu em seu resumo para que o diff não tenha surpresas. - Se for um novo projeto ou não tiver convenções, use os padrões deste skill (Riverpod
Notifier, tema Material 3 com extensões,lib/core/+lib/features/<nome>/).
2. Instale o kit de movimento uma vez
Copie os arquivos do kit que a tarefa precisa para a pasta de UI compartilhada do projeto (padrão lib/core/motion/): sempre motion.dart, mais apenas os widgets que você realmente usará, e ajuste o arquivo barrel para corresponder. Copiar todos os dez arquivos para uma tela que usa três deixa o usuário com código que ninguém chama. O kit é Flutter puro, sem dependências, limpo pelo analyzer e testado com widgets. Se o projeto já tem um equivalente (seu próprio arquivo de durações, sua própria barra de navegação), adapte-se ao deles em vez de duplicar.
| Arquivo | Fornece |
|---|---|
motion.dart | Motion.fast/base/slow/page/hero, curvas, molas, auxiliar de movimento reduzido — o único lugar onde as durações vivem; Haptics.tap/selection/success/error — o único lugar onde os hápticos são disparados |
entrance.dart | Entrance (fade/slide/blur-in escalonado), StateSwitcher (switch animado sobre estado) |
page_routes.dart | AppRoute, AppPageTransitions.theme(), showAppSheet, heroFadeShuttle |
glass_nav_bar.dart | GlassNavBar barra flutuante de vidro líquido em formato de pílula com indicador de lente deslizante |
morph_button.dart | Pressable, MorphButton (ocioso→spinner→sucesso), AsyncMorphButton |
slide_to_confirm.dart | SlideToConfirm arrastar para confirmar com hápticos e status |
rolling_number.dart | CountUpText, RollingText (dígitos de odômetro) |
otp_boxes.dart | OtpBoxes, Shake |
animated_items.dart | AnimatedItems<T> — lista que anima inserções/remoções a partir de uma lista imutável simples |
assets/examples/send_money_flow.dart é um fluxo de trabalho completo (lista → teclado → deslizar → enviando → sucesso → voltar, nova linha animada). Leia-o ao construir qualquer fluxo de vários estados; é o padrão a ser imitado. send_money_flow_test.dart ao lado mostra como testar tal fluxo (caminho completo, estouro de tela pequena, movimento reduzido).
assets/project_setup/analysis_options.yaml é o conjunto estrito de lint que o kit passa. Ofereça-se para mesclá-lo na configuração do analyzer do projeto; não sobrescreva regras que uma equipe já escolheu.
3. Projete a tela como estados e momentos, depois construa
Antes de codificar uma tela, anote (em sua mente ou em um comentário curto):
- Estados: quais são as coisas distintas que esta tela pode ser? (ex.
Editing → Submitting → Done | Failed) - Dados compartilhados: o que esta tela mostra que outra tela também mostra? Esses dados têm um único proprietário.
- Momentos: entrada, a ação principal, cada mudança de estado e saída. Cada um recebe um movimento deliberado da tabela abaixo. Todo o resto permanece parado.
Em seguida, construa nesta ordem: tokens/tema → layout estático → camada de estado → animações de mudança de estado → escalonamento de entrada → transição de navegação → hápticos → verificação de movimento reduzido e tela pequena.
4. Verifique
Execute dart format nos arquivos que você tocou e flutter analyze até ficar limpo. Onde um dispositivo/emulador estiver disponível, execute o aplicativo e veja o fluxo; caso contrário, escreva um pequeno teste de widget que percorra os estados (veja a forma do exemplo de teste) e execute-o. Em seguida, vá para references/consistency-checklist.md.
Qual movimento para qual momento
| Momento | Use | Tempo |
|---|---|---|
| Tela aparece pela primeira vez | Entrance(index: n) em 3–7 blocos de alto nível, de cima para baixo | slow, 55 ms de intervalo |
| Navegar para uma tela não relacionada (splash→home, auth→app) | AppTransition.fadeThrough | page |
| Próximo passo no mesmo fluxo (telefone→OTP→senha) | AppTransition.sharedAxisX + indicador de etapa animado | page |
| Item de lista → seu detalhe | Hero na imagem/cartão + resto do detalhe fade-in após | hero |
| Confirmar / escolher / avaliar / selecionar | showAppSheet, conteúdo escalonado dentro | page |
| Requisição em andamento | MorphButton ou SlideToConfirm com status | base por fase |
| Valor muda (preço, ETA, saldo) | RollingText (discreto) / CountUpText (magnitude) | base / long |
| Item adicionado / removido | AnimatedItems | base |
| Estado da tela muda (loading→content→error) | StateSwitcher | base |
| Seleção (chip, cartão, aba, estrela) | AnimatedContainer cor/borda + pequeno AnimatedScale | fast |
| Qualquer toque | Pressable escala + háptico leve | instant |
| Falha de validação | Shake + borda vermelha + mensagem; mantenha a entrada | slow |
| Sucesso | check aparece com Motion.overshoot, segure successHold, depois prossiga | — |
Regras práticas para manter o bom gosto:
- Entradas tocam uma vez. Em listas lentas, uma linha que rola de volta para a vista é reconstruída e animaria novamente; passe
Entrance(enabled: …)para que apenas a primeira aparição anime. - Uma peça central por navegação. Um Hero ou um blur-through ou um grande escalonamento — não todos os três.
- Entre devagar, saia rápido. Saídas executam ~60–80% da duração de entrada com
Motion.exit. - Coisas relacionadas se movem juntas; coisas não relacionadas são escalonadas.
- Anime transform e opacidade; evite animar layout em listas longas. Blur é caro — use-o em alguns elementos hero, nunca por linha de lista.
- Nunca bloqueie entrada para decoração. Entradas não devem atrasar a tocabilidade; apenas trabalho real (rede) desabilita controles.
- Respeite movimento reduzido: o kit já reduz durações via
Motion.of(context, …); faça o mesmo em qualquer controller que você escrever.
Fundamentos de gerenciamento de estado
Guia completo com equivalentes Riverpod / Bloc / ChangeNotifier: references/state.md. Os pontos inegociáveis:
- Estado de fluxo é uma classe lacrada; a UI é um
switchexaustivo. Carregue os dados que cada estado precisa dentro dele. - Um proprietário por dado compartilhado. Uma tela de lista e uma tela de detalhe/fluxo leem o mesmo provider; o fluxo escreve nele. Não passe resultados de volta através de
Navigator.pope corrija uma cópia local — é assim que as telas saem de sincronia. - Mantenha a entrada do usuário em caso de falha. Um envio com falha retorna ao estado de edição com campos intactos mais um erro.
- Efeitos colaterais em listeners, não em
build. Navegação, snackbars, hápticos reagem a transições de estado (ref.listen,BlocListener). - Estado de animação fica nos widgets; estado de negócio nunca. Um controller sabe
Submitting; ele não sabe sobreAnimationControllers. - Dados ao vivo são um stream mapeado em estado (ETA, posição do motorista, status do pedido), com o widget interpolando entre ticks para que o movimento seja contínuo mesmo quando as atualizações chegam uma vez por segundo.
- Proteja lacunas assíncronas (
ref.mounted/isClosed/mounted) antes de tocar no estado após umawait.
Consistência de UI
Consistência é o que separa um aplicativo projetado de uma pilha de telas bonitas. Coloque tokens no tema e nunca os codifique em widgets:
- Cor:
ColorScheme+ umaThemeExtensionpara extras de marca (sucesso, tonalidade de vidro, gradientes). Widgets leemTheme.of(context); isso também é o que torna a troca animada de claro/escuro gratuita. - Espaçamento: uma escala de 4 pt (4, 8, 12, 16, 20, 24, 32). Um padding de página horizontal para todo o aplicativo.
- Raio: três valores (ex. 12 pequeno / 20 cartão / 28 sheet) mais pílula. Mesmo cartão = mesmo raio em todos os lugares.
- Tipografia: apenas papéis
TextTheme; figuras tabulares para qualquer número que mude. - Movimento: apenas
Motion.*. - Componentes: um botão primário, um estilo de sheet, um estilo de entrada, uma barra de navegação. Se uma segunda variante aparecer, promova-a a um widget compartilhado com um parâmetro.
Detalhes e lista de auditoria: references/consistency-checklist.md.
Padrão de qualidade de código
UI animada multiplica o custo de código descuidado: um método build que executa 120 vezes por segundo, um controller que sobrevive à sua tela, um layout que só cabe em um telefone. Segure cada arquivo no mesmo padrão que o kit atende. references/flutter-best-practices.md tem a orientação completa; os pontos que mais frequentemente dão errado:
- Classes de widget pequenas, não métodos auxiliares
_buildX(), com construtoresconst— para que uma reconstrução toque apenas o que mudou. - Tudo que é criado é descartado: controllers de animação/texto/rolagem/página,
CurvedAnimations, nós de foco, timers, assinaturas. - Proteja cada lacuna assíncrona (
context.mounted/ref.mounted/isClosed) e nunca descarte um Future silenciosamente (awaitouunawaited). - Chaves estáveis:
ValueKey(item.id)em listas dinâmicas e em filhos deAnimatedSwitcher; nunca chaves de índice, nunca chaves criadas embuild. - Layouts que rolam em vez de estourar: qualquer tela com teclado, formulário ou seletor deve sobreviver a uma viewport de 320×480, um teclado aberto e texto 1.3×.
- Cada tela sobrevive a largura estreita + texto grande, não apenas o fluxo que foi solicitado: a 320 de largura com texto 1.6×, uma
Rowcontendo um título e um valor, um cartão com um número e um rótulo, ou um tile de lista vai estourar lateralmente a menos que o texto esteja emExpanded/FlexiblecommaxLineseoverflow. Inclua um teste que execute a primeira tela do aplicativo (e cada aba) a 320×568 comtester.platformDispatcher.textScaleFactorTestValue = 1.6e espere nenhuma exceção. - Teste o gesto infeliz: um arrasto solto cedo, um segundo toque durante o carregamento, voltar pressionado no meio de uma requisição. Esses caminhos seguram as falhas que um teste de início ao fim nunca toca.
- Sem literais no código de recurso: cores, raios, espaçamento, durações, hápticos vêm todos do tema/tokens/
Motion/Haptics; strings voltadas ao usuário seguem a configuração de localização do projeto. - Listas lentas e reconstruções com escopo: builders para qualquer coisa rolável,
selectpara valores de tick, subárvores estáticas passadas comochild. - Acessível por construção: semântica em controles personalizados, uma alternativa para ações apenas por gesto, movimento reduzido respeitado. Um wrapper
Semantics(label: …, excludeSemantics: true)também remove a ação de toque do filho — passeonTappara oSemanticstambém. - Testado onde importa: transições de estado do controller como testes unitários; um teste de widget por fluxo afirmando resultados, não detalhes internos de animação.
Arquivos de referência — leia o que corresponde à tarefa
references/motion-system.md— tokens explicados, coreografia e receitas para efeitos não no kit (sequências de splash, blur focus-in, anéis de progresso, linhas de scanner, lerps de cor/tema, cabeçalhos vinculados à rolagem).references/navigation-transitions.md— transições de página, Hero feito corretamente, container-transform, bottom sheets, fluxos de várias etapas, integração com go_router.references/glass-nav-bar.md— como a barra de vidro líquido é construída, ajuste, desempenho, estado de shell/aba, armadilhas conhecidas.references/state.md— estados de fluxo, estado compartilhado, padrões assíncronos/otimistas, streams ao vivo, em Riverpod, Bloc e ChangeNotifier.references/components.md— receitas: progresso de etapa, cartões/chips selecionáveis, classificação por estrelas com rótulo reativo, carrossel de cartões que retinge a página, seletores de roda, skeletons, planilha de rastreamento ao vivo + marcador de rota, barra de status mini persistente.references/video-analysis.md— as 22 gravações analisadas: o que acontece na tela e como reconstruir.references/flutter-best-practices.md— estrutura de projeto, composição de widget, ciclo de vida, segurança assíncrona, hábitos Dart 3, layout robusto, desempenho, theming, l10n/acessibilidade, estados de erro, teste, ferramentas. Leia antes de criar uma nova estrutura de projeto ou ao revisar/refatorar código existente.references/consistency-checklist.md— tokens, QA pré-entrega, verificações de desempenho e acessibilidade.
Expectativas de saída
- Entregue arquivos completos e executáveis na estrutura do projeto — não fragmentos com "…restante do seu código".
- Use os pacotes existentes do projeto. Sugira um novo pacote apenas quando ele claramente ganhar seu lugar e explique por quê.
- As APIs do Flutter mudam rapidamente. Se o SDK instalado for mais novo do que você tem certeza, verifique a assinatura (
flutter analyzeé o oráculo mais rápido) em vez de adivinhar. - Ao terminar, informe ao usuário brevemente quais momentos foram animados e qual forma de estado foi usada.
Traduzido e adaptado para português.