Communitygithub.com

flutter-motion-ui

Crea interfaces de Flutter pulidas y animadas donde el movimiento y el estado se diseñan juntos: transiciones de página, animaciones Hero/elemento compartido, barras de navegación flotantes de vidrio líquido, entradas escalonadas, confirmaciones con hoja inferior, deslizar para confirmar, flujos de autenticación OTP y de varios pasos, botones que se transforman de carga a éxito, números rodantes, inserción/eliminación animada de listas, pantallas de seguimiento en vivo, cambio de tema, más la gestión de estado (estados de flujo sellados, fuente única de verdad, actualizaciones optimistas) que mantiene las pantallas coherentes. Usa esta habilidad cada vez que el usuario pida construir, diseñar, rediseñar, animar o hacer más suave/más premium cualquier pantalla, widget, flujo o aplicación de Flutter (splash, onboarding, autenticación, inicio, detalle, pago, perfil, entrega, viajes compartidos, billetera, fitness), o mencione transiciones de Flutter, hero, glassmorphism/vidrio líquido, microinteracciones, coherencia de UI, tokens de diseño, animación entrecortada o gestión de estado para UI (Riverpod, Bloc, Provider, setState desordenado), incluso si nunca dicen la palabra animación.

¿Qué es flutter-motion-ui?

Este skill especializado permite a agentes de IA (como Claude Code, Cursor o Codex) generar pantallas de Flutter que se sienten como un producto coherente y terminado a mano, donde cada elemento llega con intención, cada toque responde, cada cambio de estado es visible y los datos se mantienen consistentes entre pantallas. Se basa en el análisis detallado de 22 aplicaciones de referencia (billetera, entrega, viajes compartidos, fitness, autenticación OTP, alarma, pago, reserva, emparejamiento de dispositivos) y su idea central es que el estado impulsa el movimiento: la mayoría de los momentos "suaves" ocurren porque un estado cambia y la UI anima del valor anterior al nuevo, utilizando animaciones implícitas como AnimatedSwitcher, AnimatedContainer o TweenAnimationBuilder en lugar de AnimationController explícitos (que solo se reservan para gestos táctiles, ambiente de bucle y secuencias coreografiadas de múltiples partes). El skill incluye un kit de movimiento completo (con widgets para entradas escalonadas, transiciones de página, barras de navegación de vidrio, botones mutantes, deslizadores de confirmación, números rodantes, listas animadas y más) y establece reglas estrictas para la gestión de estado (clases selladas, fuente única de datos, efectos secundarios en oyentes, estado de animación separado del estado de negocio), coherencia de UI (tokens en el tema, escala de espaciado de 4 puntos, radios consistentes) y calidad de código (widgets pequeños con constructores const, disposición adecuada de recursos, manejo de errores y pruebas). También proporciona guías de referencia detalladas para sistemas de movimiento, transiciones de navegación, barras de vidrio, componentes específicos y mejores prácticas de Flutter, asegurando que el código generado sea profesional, mantenible y esté listo para producción.

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

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

Flutter Motion UI

Este skill produce pantallas de Flutter que se sienten como un producto coherente y terminado a mano: cada elemento llega con intención, cada toque responde, cada cambio de estado es visible y los datos se mantienen consistentes entre pantallas.

Se destiló del análisis fotograma a fotograma de 22 grabaciones de aplicaciones de referencia (billetera, entrega, viajes compartidos, fitness, autenticación/OTP, alarma, pago, reserva, emparejamiento de dispositivos). references/video-analysis.md enumera lo que hace cada una y qué receta la reproduce.

La idea central: el estado impulsa el movimiento

Casi todos los momentos "suaves" en las referencias son el mismo mecanismo: un estado cambió, y la UI animó del valor anterior al nuevo. Nadie llamó a controller.forward() desde un manejador de botón. Por lo tanto, el trabajo siempre es:

  1. Modelar los estados de la pantalla explícitamente (una clase sellada, no cinco booleanos).
  2. Renderizar con un switch sobre ese estado.
  3. Envolver lo que cambia en una animación implícita (AnimatedSwitcher, AnimatedContainer, TweenAnimationBuilder o un widget del kit) para que la diferencia entre dos estados se anime a sí misma.

Cuando esto se hace, la animación y la gestión de estado dejan de ser dos problemas. Las animaciones interrumpidas, los dobles toques y los errores de "spinner de carga junto al tick de éxito" desaparecen porque los estados imposibles no se pueden representar.

Los AnimationControllers explícitos se reservan para tres cosas: gestos controlados por el dedo, ambiente en bucle (pulsos, escáneres) y secuencias coreografiadas de múltiples partes.

Flujo de trabajo

1. Leer el proyecto antes de escribir nada

  • pubspec.yaml: Flutter/Dart SDK, biblioteca de estado ya en uso (riverpod / bloc / provider / getx / ninguno), enrutador (go_router / auto_route / Navigator), paquetes de animación existentes.
  • Tema, colores, espaciado, widgets compartidos existentes. Extiende lo que ya hay; no introduzcas un segundo sistema de diseño o una segunda biblioteca de estado. Coincide con la estructura de carpetas y la nomenclatura del proyecto. En una aplicación existente, mantén los cambios en archivos que no te pidieron tan pequeños como la función lo requiera (un envoltorio Hero, un relleno), deja las limpiezas de estilo o lint no relacionadas a menos que se te pida, y enumera cada archivo existente que reescribiste en tu resumen para que el diff no tenga sorpresas.
  • Si es un proyecto nuevo o no tiene convenciones, usa los valores predeterminados de este skill (Riverpod Notifier, tema Material 3 con extensiones, lib/core/ + lib/features/<nombre>/).

2. Instalar el kit de movimiento una vez

Copia los archivos del kit que la tarea necesita en la carpeta de UI compartida del proyecto (por defecto lib/core/motion/): siempre motion.dart, más solo los widgets que realmente usarás, y recorta el archivo barrel para que coincida. Copiar los diez archivos para una pantalla que usa tres deja al usuario con código que nadie llama. El kit es Flutter puro sin dependencias, libre de análisis y probado con widgets. Si el proyecto ya tiene un equivalente (su propio archivo de duraciones, su propia barra de navegación), adáptate al suyo en lugar de duplicar.

ArchivoTe proporciona
motion.dartMotion.fast/base/slow/page/hero, curvas, resortes, ayuda para movimiento reducido: el único lugar donde viven las duraciones; Haptics.tap/selection/success/error: el único lugar donde se activan las hápticas
entrance.dartEntrance (desvanecimiento/deslizamiento/desenfoque escalonado), StateSwitcher (switch animado sobre el estado)
page_routes.dartAppRoute, AppPageTransitions.theme(), showAppSheet, heroFadeShuttle
glass_nav_bar.dartGlassNavBar barra de navegación flotante de vidrio líquido con indicador deslizante tipo lente
morph_button.dartPressable, MorphButton (inactivo→spinner→éxito), AsyncMorphButton
slide_to_confirm.dartSlideToConfirm arrastrar para confirmar con hápticas y estado
rolling_number.dartCountUpText, RollingText (dígitos de odómetro)
otp_boxes.dartOtpBoxes, Shake
animated_items.dartAnimatedItems<T>: lista que anima inserciones/eliminaciones desde una lista inmutable simple

assets/examples/send_money_flow.dart es un flujo de trabajo completo (lista → teclado → deslizar → enviando → éxito → volver, nueva fila aparece animada). Léelo al construir cualquier flujo de múltiples estados; es el patrón a imitar. send_money_flow_test.dart junto a él muestra cómo probar dicho flujo (ruta completa, desbordamiento en pantalla pequeña, movimiento reducido).

assets/project_setup/analysis_options.yaml es el conjunto estricto de lint que el kit pasa. Ofrece fusionarlo en la configuración del analizador del proyecto; no sobrescribas reglas que un equipo ya eligió.

3. Diseñar la pantalla como estados y momentos, luego construir

Antes de codificar una pantalla, escribe (en tu cabeza o en un comentario breve):

  • Estados: ¿cuáles son las cosas distintas que esta pantalla puede ser? (p. ej., Editing → Submitting → Done | Failed)
  • Datos compartidos: ¿qué muestra esta pantalla que otra pantalla también muestra? Esos datos tienen un único propietario.
  • Momentos: entrada, la acción principal, cada cambio de estado y salida. Cada uno recibe un movimiento deliberado de la tabla a continuación. Todo lo demás permanece quieto.

Luego construye en este orden: tokens/tema → diseño estático → capa de estado → animaciones de cambio de estado → escalonamiento de entrada → transición de navegación → hápticas → verificación de movimiento reducido y pantalla pequeña.

4. Verificar

Ejecuta dart format en los archivos que tocaste y flutter analyze hasta que esté limpio. Cuando haya un dispositivo/emulador disponible, ejecuta la aplicación y mira realmente el flujo; de lo contrario, escribe una breve prueba de widget que recorra los estados (consulta la forma de la prueba de ejemplo) y ejecútala. Luego revisa references/consistency-checklist.md.

Qué movimiento para qué momento

MomentoUsarTiempo
La pantalla aparece por primera vezEntrance(index: n) en 3–7 bloques de nivel superior, de arriba a abajoslow, separados 55 ms
Navegar a una pantalla no relacionada (splash→inicio, autenticación→app)AppTransition.fadeThroughpage
Siguiente paso en el mismo flujo (teléfono→OTP→contraseña)AppTransition.sharedAxisX + indicador de paso animadopage
Elemento de lista → su detalleHero en la imagen/tarjeta + el resto del detalle se desvanece despuéshero
Confirmar / elegir / calificar / seleccionarshowAppSheet, contenido escalonado dentropage
Solicitud en cursoMorphButton o SlideToConfirm con statusbase por fase
El valor cambia (precio, ETA, saldo)RollingText (discreto) / CountUpText (magnitud)base / long
Elemento agregado / eliminadoAnimatedItemsbase
Cambios de estado de pantalla (cargando→contenido→error)StateSwitcherbase
Selección (chip, tarjeta, pestaña, estrella)AnimatedContainer color/borde + pequeño AnimatedScalefast
Cualquier toquePressable escala + háptica ligerainstant
Error de validaciónShake + borde rojo + mensaje; mantén la entradaslow
Éxitoel check aparece con Motion.overshoot, mantén successHold, luego continúa—

Reglas generales que lo mantienen con buen gusto:

  • Las entradas se reproducen una vez. En listas perezosas, una fila que se desplaza de nuevo a la vista se reconstruye y se animaría de nuevo; pasa Entrance(enabled: …) para que solo la primera aparición se anime.
  • Una pieza central por navegación. Un Hero o un desenfoque o un gran escalonamiento, no los tres.
  • Entrar lento, salir rápido. Las salidas se ejecutan ~60–80% de la duración de entrada con Motion.exit.
  • Las cosas que están relacionadas se mueven juntas; las no relacionadas se escalonan.
  • Animar transformación y opacidad; evita animar el diseño en listas largas. El desenfoque es costoso: úsalo en unos pocos elementos hero, nunca por fila de lista.
  • Nunca bloquees la entrada por decoración. Las entradas no deben retrasar la capacidad de tocar; solo el trabajo real (red) deshabilita los controles.
  • Respeta el movimiento reducido: el kit ya colapsa las duraciones mediante Motion.of(context, …); haz lo mismo en cualquier controlador que escribas.

Fundamentos de gestión de estado

Guía completa con equivalentes de Riverpod / Bloc / ChangeNotifier: references/state.md. Los no negociables:

  • El estado del flujo es una clase sellada; la UI es un switch exhaustivo. Lleva los datos que cada estado necesita dentro de él.
  • Un propietario por pieza de datos compartidos. Una pantalla de lista y una pantalla de detalle/flujo leen el mismo proveedor; el flujo escribe en él. No pases resultados de vuelta a través de Navigator.pop y parchees una copia local: así es como las pantallas se desincronizan.
  • Conserva la entrada del usuario en caso de error. Un envío fallido regresa al estado de edición con los campos intactos más un error.
  • Efectos secundarios en oyentes, no en build. La navegación, los snackbars y las hápticas reaccionan a las transiciones de estado (ref.listen, BlocListener).
  • El estado de animación permanece en los widgets; el estado de negocio nunca. Un controlador conoce Submitting; no sabe nada sobre AnimationControllers.
  • Los datos en vivo son un flujo mapeado a estado (ETA, posición del conductor, estado del pedido), y el widget interpola entre ticks para que el movimiento sea continuo incluso cuando las actualizaciones llegan una vez por segundo.
  • Protege los vacíos asíncronos (ref.mounted / isClosed / mounted) antes de tocar el estado después de un await.

Coherencia de UI

La coherencia es lo que separa una aplicación diseñada de un montón de pantallas bonitas. Pon los tokens en el tema y nunca los codifiques en los widgets:

  • Color: ColorScheme + un ThemeExtension para extras de marca (éxito, tinte de vidrio, degradados). Los widgets leen Theme.of(context); esto también es lo que hace que el cambio animado entre claro y oscuro sea gratuito.
  • Espaciado: una escala de 4 puntos (4, 8, 12, 16, 20, 24, 32). Un relleno de página horizontal para toda la aplicación.
  • Radio: tres valores (p. ej., 12 pequeño / 20 tarjeta / 28 hoja) más píldora. La misma tarjeta = el mismo radio en todas partes.
  • Tipografía: solo roles de TextTheme; cifras tabulares para cualquier número que cambie.
  • Movimiento: solo Motion.*.
  • Componentes: un botón principal, un estilo de hoja, un estilo de entrada, una barra de navegación. Si aparece una segunda variante, promuévela a un widget compartido con un parámetro.

Detalles y la lista de auditoría: references/consistency-checklist.md.

Estándar de calidad del código

La UI animada multiplica el costo del código descuidado: un método build que se ejecuta 120 veces por segundo, un controlador que sobrevive a su pantalla, un diseño que solo cabe en un teléfono. Mantén cada archivo al mismo estándar que cumple el kit. references/flutter-best-practices.md tiene la guía completa; los puntos que más a menudo salen mal:

  • Clases de widget pequeñas, no métodos auxiliares _buildX(), con constructores const, para que una reconstrucción toque solo lo que cambió.
  • Todo lo creado se elimina: controladores de animación/texto/desplazamiento/página, CurvedAnimations, nodos de enfoque, temporizadores, suscripciones.
  • Protege cada vacío asíncrono (context.mounted / ref.mounted / isClosed) y nunca dejes caer un Future en silencio (await o unawaited).
  • Claves estables: ValueKey(item.id) en listas dinámicas y en hijos de AnimatedSwitcher; nunca claves de índice, nunca claves creadas en build.
  • Diseños que se desplazan en lugar de desbordarse: cualquier pantalla con un teclado, formulario o selector debe sobrevivir a una ventana de 320×480, un teclado abierto y texto 1.3×.
  • Cada pantalla sobrevive a texto estrecho + grande, no solo el flujo que te pidieron: a 320 de ancho con texto 1.6×, una Row que contiene un título y una cantidad, una tarjeta con un número y una etiqueta, o un mosaico de lista se desbordará lateralmente a menos que el texto esté en Expanded/Flexible con maxLines y overflow. Incluye una prueba que ejecute la primera pantalla de la aplicación (y cada pestaña) a 320×568 con tester.platformDispatcher.textScaleFactorTestValue = 1.6 y espere que no haya excepción.
  • Prueba el gesto infeliz: un arrastre soltado temprano, un segundo toque mientras se carga, retroceso presionado a mitad de solicitud. Estos caminos contienen los bloqueos que una prueba de principio a fin nunca toca.
  • Sin literales en el código de la función: colores, radios, espaciado, duraciones, hápticas provienen del tema/tokens/Motion/Haptics; las cadenas orientadas al usuario siguen la configuración de localización del proyecto.
  • Listas perezosas y reconstrucciones con ámbito: builders para cualquier cosa desplazable, select para valores que cambian, subárboles estáticos pasados como child.
  • Accesible por construcción: semántica en controles personalizados, una alternativa para acciones solo de gesto, movimiento reducido respetado. Un envoltorio Semantics(label: …, excludeSemantics: true) también elimina la acción de toque del hijo: pasa onTap al Semantics también.
  • Probado donde importa: transiciones de estado del controlador como pruebas unitarias; una prueba de widget por flujo que afirme resultados, no internas de animación.

Archivos de referencia: lee el que coincida con la tarea

  • references/motion-system.md: tokens explicados, coreografía y recetas para efectos no incluidos en el kit (secuencias de splash, desenfoque de enfoque, anillos de progreso, líneas de escáner, interpolaciones de color/tema, encabezados vinculados al desplazamiento).
  • references/navigation-transitions.md: transiciones de página, Hero hecho correctamente, container-transform, hojas inferiores, flujos de múltiples pasos, integración con go_router.
  • references/glass-nav-bar.md: cómo se construye la barra de vidrio líquido, ajuste, rendimiento, estado del shell/pestaña, problemas conocidos.
  • references/state.md: estados de flujo, estado compartido, patrones asíncronos/optimistas, flujos en vivo, en Riverpod, Bloc y ChangeNotifier.
  • references/components.md: recetas: progreso de pasos, tarjetas/chips seleccionables, calificación de estrellas con etiqueta reactiva, carrusel de tarjetas que retiñe la página, selectores de rueda, esqueletos, hoja de seguimiento en vivo + marcador de ruta, barra de estado mini persistente.
  • references/video-analysis.md: las 22 grabaciones analizadas: qué sucede en pantalla y cómo reconstruirlo.
  • references/flutter-best-practices.md: estructura del proyecto, composición de widgets, ciclo de vida, seguridad asíncrona, hábitos de Dart 3, diseño robusto, rendimiento, tematización, l10n/accesibilidad, estados de error, pruebas, herramientas. Léelo antes de crear una nueva estructura de proyecto o al revisar/refactorizar código existente.
  • references/consistency-checklist.md: tokens, QA previo a la entrega, comprobaciones de rendimiento y accesibilidad.

Expectativas de salida

  • Entrega archivos completos y ejecutables en la estructura del proyecto, no fragmentos con "…resto de tu código".
  • Usa los paquetes existentes del proyecto. Sugiere un nuevo paquete solo cuando claramente merezca su lugar, y di por qué.
  • Las APIs de Flutter se mueven rápidamente. Si el SDK instalado es más nuevo de lo que estás seguro, verifica la firma (flutter analyze es el oráculo más rápido) en lugar de adivinar.
  • Al terminar, dile brevemente al usuario qué momentos se animaron y qué forma de estado se usó.

Referencias del kit

Los archivos de origen del kit están en lib/core/motion/ después de la instalación. assets/examples/send_money_flow.dart es el flujo de trabajo completo para estudiar. assets/project_setup/analysis_options.yaml es el lint estricto.

Skills relacionados