app_durations library

Sistema de duraciones para animaciones, transiciones y delays

Este módulo proporciona duraciones estandarizadas siguiendo las mejores prácticas de UX y Material Design Motion para garantizar animaciones fluidas, naturales y consistentes en toda la aplicación.

🆕 API Recomendada (Nueva)

// Duraciones base - para animaciones generales
AnimatedContainer(
  duration: Consts.durations.base.md,  // 300ms - Estándar
  curve: Curves.easeInOut,
  child: MyWidget(),
)

// Duraciones por feature - casos de uso específicos
Timer(Consts.durations.feat.searchDebounce, () => search());
Tooltip(waitDuration: Consts.durations.feat.tooltipDelay);

🔄 API Legacy (Compatible)

// Sigue funcionando para mantener compatibilidad
AnimatedContainer(duration: AppDurations.md);
Timer(AppDurations.searchDebounce, callback);

⏱️ Filosofía de Timing

Las duraciones están diseñadas según principios de motion design:

Ultra rápidas (50-150ms): Feedback inmediato, no bloquean la UI
Rápidas (200-400ms): Balance ideal velocidad/claridad ⭐
Moderadas (500-800ms): Transiciones importantes, estados destacados
Extendidas (1000-3000ms): Loading, notificaciones, efectos especiales

📏 Escala de Duraciones Base

Nombre	Duración	Uso Principal
`xxs`	50ms	Hover sutiles, ripples instantáneos
`xs`	100ms	Cambios de estado, toggles
`sm`	150ms	Navegación, transiciones de página
`smd`	200ms	Fade, ripples, micro-interacciones ⭐
`mds`	250ms	Expansión cards, slides suaves
`md`	300ms	Animaciones estándar ⭐⭐⭐
`mdl`	350ms	Transformaciones complejas
`lg`	400ms	Hero animations, layouts importantes
`xl`	500ms	Onboarding, efectos especiales
`xxl`	600ms	Animaciones de celebración
`xxxl`	800ms	Secuencias complejas
`huge`	1000ms	Progress indicators, loading cycles
`massive`	1500ms	Shimmer effects, skeleton screens
`giant`	2000ms	Snackbars, toasts, notificaciones
`mega`	3000ms	Mensajes importantes con acciones

🎯 Duraciones por Feature

Nombre	Duración	Descripción
`searchDebounce`	300ms	Debounce de búsqueda
`filterDebounce`	400ms	Debounce de filtros
`quickDebounce`	200ms	Validación en tiempo real
`tooltipDelay`	500ms	Delay antes de mostrar tooltip
`snackbarDuration`	2000ms	Tiempo visible del snackbar
`pageTransition`	150ms	Transición entre páginas
`hoverEffect`	100ms	Hover en botones/cards
`rippleEffect`	200ms	Material ripple
`shimmerAnimation`	1500ms	Skeleton loading
`apiSimulatedDelay`	1500ms	Mock API delay

💡 Guía de Selección Rápida

Por tipo de animación:

// Micro-interacciones → xxs a smd (50-200ms)
MouseRegion(onEnter: ..., duration: Consts.durations.base.xs);

// UI transitions → smd a md (200-300ms) ⭐
AnimatedContainer(duration: Consts.durations.base.md);

// Transiciones importantes → lg a xl (400-500ms)
Hero(transitionDuration: Consts.durations.base.lg);

// Estados de carga → huge a massive (1000-1500ms)
shimmer.repeat(period: Consts.durations.base.massive);

Por complejidad:

1 propiedad → smd (200ms)
2-3 propiedades → md (300ms) ⭐
4+ propiedades → lg (400ms)

Por distancia visual:

Pequeña (< 20px) → smd a md (200-300ms)
Mediana (20-100px) → md a lg (300-400ms)
Grande (> 100px) → lg a xl (400-500ms)

🎬 Combinación con Curves

// Entrada (aparece)
AnimatedContainer(
  duration: Consts.durations.base.md,
  curve: Curves.easeOut,  // Desacelera al final
)

// Salida (desaparece)
AnimatedContainer(
  duration: Consts.durations.base.smd,  // Más rápido
  curve: Curves.easeIn,  // Acelera al final
)

// Bidireccional
AnimatedContainer(
  duration: Consts.durations.base.md,
  curve: Curves.easeInOut,  // Suave en ambos extremos
)

// Con bounce
AnimatedContainer(
  duration: Consts.durations.base.lg,  // Más largo
  curve: Curves.elasticOut,
)

♿ Accesibilidad

Duration getAnimationDuration(BuildContext context) {
  final reduceMotion = MediaQuery.of(context).disableAnimations;
  return reduceMotion ? Duration.zero : Consts.durations.base.md;
}

❌ Anti-patrones

// ❌ Duraciones arbitrarias
AnimatedContainer(duration: Duration(milliseconds: 273));

// ✅ Usa duraciones predefinidas
AnimatedContainer(duration: Consts.durations.base.md);

// ❌ Animaciones muy lentas en UI frecuente
AnimatedOpacity(duration: Duration(seconds: 2));

// ✅ Duraciones apropiadas al contexto
AnimatedOpacity(duration: Consts.durations.base.smd);

constants/app_durations library