Communitygithub.com

flutter-motion-ui

Crie interfaces Flutter animadas e refinadas, onde movimento e estado são projetados em conjunto — transições de página, animações Hero/elemento compartilhado, barras de navegação flutuantes em vidro líquido, entradas escalonadas, confirmações em bottom sheet, deslizar para confirmar, fluxos de autenticação OTP e multi-etapas, botões que se transformam de carregamento para sucesso, números rolantes, inserção/remoção animada de listas, telas de rastreamento ao vivo, alternância de temas, além do gerenciamento de estado (estados de fluxo lacrados, fonte única da verdade, atualizações otimistas) que mantém as telas consistentes.

O que é flutter-motion-ui?

O skill `flutter-motion-ui` é projetado para desenvolvedores Flutter que desejam construir interfaces de usuário polidas e animadas, onde cada elemento parece intencional e cada interação é respondida com movimento. A ideia central é que o estado direciona a animação: modela-se o estado da tela explicitamente (como uma classe lacrada), e a UI anima automaticamente as transições entre os estados usando widgets como `AnimatedSwitcher`, `AnimatedContainer` e `TweenAnimationBuilder`, eliminando bugs de animação interrompida e estados impossíveis. O skill suporta plataformas como Claude Code e Cursor, e fornece um kit de movimento Flutter puro que inclui componentes como `Entrance` para entradas escalonadas, `GlassNavBar` para barras de navegação em vidro líquido, `MorphButton` para botões que se transformam de carregamento para sucesso, `SlideToConfirm` para ações de deslizar, `RollingText` para números rolantes e `AnimatedItems` para listas com inserção/remoção animada. Além disso, ele enfatiza práticas de gerenciamento de estado (Riverpod, Bloc, Provider) com estados de fluxo lacrados, fonte única da verdade e atualizações otimistas, consistência de design (tokens no tema, espaçamento de 4 pt, raios padronizados) e qualidade de código (widgets pequenos e const, descarte de controladores, testes de fluxo e gestos infelizes). O fluxo de trabalho envolve ler o projeto existente, instalar apenas os componentes do kit necessários, projetar a tela em termos de estados e momentos, construir na ordem (tokens → layout estático → camada de estado → animações → entrada → transição → hápticos → verificação), e validar com `flutter analyze`, testes de widget e checklist de consistência.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Ismail554/flutter-motion-ui-skill/tree/HEAD/flutter-motion-ui

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

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:

  1. Modelar os estados da tela explicitamente (uma classe lacrada, não cinco booleanos).
  2. Renderizar com um switch sobre esse estado.
  3. Envolver o que muda em uma animação implícita (AnimatedSwitcher, AnimatedContainer, TweenAnimationBuilder ou 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.

ArquivoFornece
motion.dartMotion.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.dartEntrance (fade/slide/blur-in escalonado), StateSwitcher (switch animado sobre estado)
page_routes.dartAppRoute, AppPageTransitions.theme(), showAppSheet, heroFadeShuttle
glass_nav_bar.dartGlassNavBar barra flutuante de vidro líquido em formato de pílula com indicador de lente deslizante
morph_button.dartPressable, MorphButton (ocioso→spinner→sucesso), AsyncMorphButton
slide_to_confirm.dartSlideToConfirm arrastar para confirmar com hápticos e status
rolling_number.dartCountUpText, RollingText (dígitos de odômetro)
otp_boxes.dartOtpBoxes, Shake
animated_items.dartAnimatedItems<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

MomentoUseTempo
Tela aparece pela primeira vezEntrance(index: n) em 3–7 blocos de alto nível, de cima para baixoslow, 55 ms de intervalo
Navegar para uma tela não relacionada (splash→home, auth→app)AppTransition.fadeThroughpage
Próximo passo no mesmo fluxo (telefone→OTP→senha)AppTransition.sharedAxisX + indicador de etapa animadopage
Item de lista → seu detalheHero na imagem/cartão + resto do detalhe fade-in apóshero
Confirmar / escolher / avaliar / selecionarshowAppSheet, conteúdo escalonado dentropage
Requisição em andamentoMorphButton ou SlideToConfirm com statusbase por fase
Valor muda (preço, ETA, saldo)RollingText (discreto) / CountUpText (magnitude)base / long
Item adicionado / removidoAnimatedItemsbase
Estado da tela muda (loading→content→error)StateSwitcherbase
Seleção (chip, cartão, aba, estrela)AnimatedContainer cor/borda + pequeno AnimatedScalefast
Qualquer toquePressable escala + háptico leveinstant
Falha de validaçãoShake + borda vermelha + mensagem; mantenha a entradaslow
Sucessocheck 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 switch exaustivo. 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.pop e 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 sobre AnimationControllers.
  • 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 um await.

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 + uma ThemeExtension para extras de marca (sucesso, tonalidade de vidro, gradientes). Widgets leem Theme.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 construtores const — 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 (await ou unawaited).
  • Chaves estáveis: ValueKey(item.id) em listas dinâmicas e em filhos de AnimatedSwitcher; nunca chaves de índice, nunca chaves criadas em build.
  • 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 Row contendo 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 em Expanded/Flexible com maxLines e overflow. Inclua um teste que execute a primeira tela do aplicativo (e cada aba) a 320×568 com tester.platformDispatcher.textScaleFactorTestValue = 1.6 e 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, select para valores de tick, subárvores estáticas passadas como child.
  • 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 — passe onTap para o Semantics també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.

Habilidades Relacionadas