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:
- Modelar los estados de la pantalla explícitamente (una clase sellada, no cinco booleanos).
- Renderizar con un
switchsobre ese estado. - Envolver lo que cambia en una animación implícita (
AnimatedSwitcher,AnimatedContainer,TweenAnimationBuildero 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.
| Archivo | Te proporciona |
|---|---|
motion.dart | Motion.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.dart | Entrance (desvanecimiento/deslizamiento/desenfoque escalonado), StateSwitcher (switch animado sobre el estado) |
page_routes.dart | AppRoute, AppPageTransitions.theme(), showAppSheet, heroFadeShuttle |
glass_nav_bar.dart | GlassNavBar barra de navegación flotante de vidrio líquido con indicador deslizante tipo lente |
morph_button.dart | Pressable, MorphButton (inactivo→spinner→éxito), AsyncMorphButton |
slide_to_confirm.dart | SlideToConfirm arrastrar para confirmar con hápticas y estado |
rolling_number.dart | CountUpText, RollingText (dígitos de odómetro) |
otp_boxes.dart | OtpBoxes, Shake |
animated_items.dart | AnimatedItems<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
| Momento | Usar | Tiempo |
|---|---|---|
| La pantalla aparece por primera vez | Entrance(index: n) en 3–7 bloques de nivel superior, de arriba a abajo | slow, separados 55 ms |
| Navegar a una pantalla no relacionada (splash→inicio, autenticación→app) | AppTransition.fadeThrough | page |
| Siguiente paso en el mismo flujo (teléfono→OTP→contraseña) | AppTransition.sharedAxisX + indicador de paso animado | page |
| Elemento de lista → su detalle | Hero en la imagen/tarjeta + el resto del detalle se desvanece después | hero |
| Confirmar / elegir / calificar / seleccionar | showAppSheet, contenido escalonado dentro | page |
| Solicitud en curso | MorphButton o SlideToConfirm con status | base por fase |
| El valor cambia (precio, ETA, saldo) | RollingText (discreto) / CountUpText (magnitud) | base / long |
| Elemento agregado / eliminado | AnimatedItems | base |
| Cambios de estado de pantalla (cargando→contenido→error) | StateSwitcher | base |
| Selección (chip, tarjeta, pestaña, estrella) | AnimatedContainer color/borde + pequeño AnimatedScale | fast |
| Cualquier toque | Pressable escala + háptica ligera | instant |
| Error de validación | Shake + borde rojo + mensaje; mantén la entrada | slow |
| Éxito | el 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
switchexhaustivo. 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.popy 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 sobreAnimationControllers. - 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 unawait.
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+ unThemeExtensionpara extras de marca (éxito, tinte de vidrio, degradados). Los widgets leenTheme.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 constructoresconst, 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 (awaitounawaited). - Claves estables:
ValueKey(item.id)en listas dinámicas y en hijos deAnimatedSwitcher; nunca claves de índice, nunca claves creadas enbuild. - 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
Rowque 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é enExpanded/FlexibleconmaxLinesyoverflow. Incluye una prueba que ejecute la primera pantalla de la aplicación (y cada pestaña) a 320×568 contester.platformDispatcher.textScaleFactorTestValue = 1.6y 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,
selectpara valores que cambian, subárboles estáticos pasados comochild. - 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: pasaonTapalSemanticstambié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 analyzees 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.