Preámbulo (ejecutar primero)
_TEL_TIER=$(cat ~/.superstack/config.json 2>/dev/null | grep -o '"telemetryTier": *"[^"]*"' | head -1 | sed 's/.*"telemetryTier": *"//;s/"$//' || echo "anonymous")
_TEL_TIER="${_TEL_TIER:-anonymous}"
_TEL_PROMPTED=$([ -f ~/.superstack/.telemetry-prompted ] && echo "yes" || echo "no")
_TEL_START=$(date +%s)
_SESSION_ID="$$-$(date +%s)"
mkdir -p ~/.superstack
echo "TELEMETRÍA: $_TEL_TIER"
echo "TEL_PROMPTED: $_TEL_PROMPTED"
if [ "$_TEL_TIER" != "off" ]; then
_TEL_EVENT='{"skill":"page-load-animations","phase":"build","event":"started","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"}'
echo "$_TEL_EVENT" >> ~/.superstack/telemetry.jsonl 2>/dev/null || true
_CONVEX_URL=$(cat ~/.superstack/config.json 2>/dev/null | grep -o '"convexUrl":"[^"]*"' | head -1 | cut -d'"' -f4 || echo "")
[ -n "$_CONVEX_URL" ] && curl -s -X POST "$_CONVEX_URL/api/mutation" -H "Content-Type: application/json" -d '{"path":"telemetry:track","args":{"skill":"page-load-animations","phase":"build","status":"success","version":"0.2.0","platform":"'$(uname -s)-$(uname -m)'","timestamp":'$(date +%s)000'}}' >/dev/null 2>&1 &
true
fi
Si TEL_PROMPTED es no: Antes de comenzar el flujo de trabajo de la habilidad, pregúntale al usuario sobre la telemetría.
Usa AskUserQuestion:
¡Ayuda a superstack a mejorar! Rastreamos qué habilidades se usan y cuánto tiempo tardan — sin código, rutas de archivos ni PII. Cámbialo en cualquier momento en
~/.superstack/config.json.
Opciones:
- A) Claro, ayuda a superstack a mejorar (anónimo)
- B) No, gracias
Si A: ejecuta este bash:
echo '{"telemetryTier":"anonymous"}' > ~/.superstack/config.json
_TEL_TIER="anonymous"
touch ~/.superstack/.telemetry-prompted
Si B: ejecuta este bash:
echo '{"telemetryTier":"off"}' > ~/.superstack/config.json
_TEL_TIER="off"
touch ~/.superstack/.telemetry-prompted
Esto solo ocurre una vez. Si TEL_PROMPTED es yes, omite esto por completo y continúa con el flujo de trabajo de la habilidad.
¿Habilidad incorrecta? Consulta SKILL_ROUTER.md para todas las habilidades disponibles.
Animaciones de Carga de Página
Patrones adaptados de recetas probadas en batalla de framer-motion. Inspiración original: suzi-ux-motions.
Recetas de producción para framer-motion que hacen que las cargas de página se sientan intencionadas en lugar de caóticas. Esta habilidad existe porque el problema de animación más común en las interfaces de usuario de cripto no es la falta de animación, sino que todo aparece a la vez sin coreografía, escalonamiento ni física de muelle. El resultado se siente roto incluso cuando el código es correcto.
Esta habilidad proporciona las recetas de implementación. Para teoría de animación (cuándo animar, niveles de duración, curvas de suavizado, movimiento reducido), consulta frontend-design-guidelines/references/animation.md. Esta habilidad hereda todas esas restricciones base.
Modelo de Autoridad
animation.md= restricciones base (niveles de duración, suavizado, movimiento reducido, propiedades GPU)- Esta habilidad = recetas de producción que implementan dentro de esas restricciones
frontend-design-guidelinesDELEGA en esta habilidad para los patrones de framer-motion, no al revés
Configuración
npm install framer-motion
Las transiciones CSS son el valor predeterminado para cambios de estado simples (según animation.md). Recurre a framer-motion cuando necesites: física de muelle, secuencias orquestadas, animaciones de salida con AnimatePresence, gestos/arrastre, o transiciones de diseño compartidas.
Cuándo Activar Esta Habilidad
Aplica estas recetas cada vez que estés:
- Construyendo una página que carga múltiples secciones (panel de control, pantalla de detalle, página de aterrizaje)
- Escalonando una lista, cuadrícula de tarjetas o tabla al montarse
- Animando un modal, menú desplegable o ventana emergente
- Cambiando pestañas o filtros donde el contenido cambia y la altura se ajusta
- Mostrando números, gráficos o gráficos de dona que se actualizan en vivo
- Añadiendo retroalimentación al pasar el ratón, rotación de cheurón o entrada de tooltip
- Revisando código existente de framer-motion en busca de anti-patrones
- Un usuario dice "la página se siente entrecortada" o "todo aparece a la vez"
Si estás construyendo un componente a nivel de página y esta habilidad no se ha activado, actívala tú mismo.
Flujo de Trabajo
Antes de escribir código de animación, identifica qué archivo de referencia es relevante y léelo:
- Orquestando una entrada de página → references/page-choreography.md
- Escalonando una lista o cuadrícula de tarjetas → references/list-stagger.md
- Animando un modal, menú desplegable o ventana emergente → references/popups-modals.md
- Cambiando pestañas/filtros con cambios de altura → references/filter-transitions.md
- Números rodantes, transformaciones de gráficos, revelaciones de dona → references/live-data.md
- Retroalimentación de botón, rotación de cheurón, tooltips → references/hover-micro.md
- Consultando un preset de muelle o curva de suavizado → references/spring-presets.md
Carga solo lo que necesites. No leas todas las referencias de antemano.
Modo 1: Construir nuevas animaciones
- Lee el(los) archivo(s) de referencia relevantes para el patrón que necesitas.
- Comienza con el comentario de guion gráfico ASCII: planifica la secuencia completa antes de escribir cualquier código.
- Define un objeto TIMING con constantes con nombre para cada retardo.
- Implementa usando los patrones de la referencia. Usa física de muelle por defecto.
- Verifica contra los puntos no negociables a continuación antes de reportar como completado.
Modo 2: Revisar código de animación existente
- Escanea en busca de anti-patrones comunes:
# prop layout en padre E hijos (fuente de vibración) grep -rn "layout" --include="*.tsx" --include="*.jsx" | head -20 # staggerChildren con AnimatePresence (poco fiable) grep -rn "staggerChildren" --include="*.tsx" --include="*.jsx" | head -10 # transition-all (anima propiedades no deseadas) grep -rn "transition-all\|transition: all" --include="*.tsx" --include="*.css" | head -10 # Manejo de reduced-motion faltante grep -rn "motion\.\|animate=" --include="*.tsx" -l | while read f; do grep -L "reduced-motion\|useReducedMotion\|motion-safe" "$f"; done | head -10 - Para cada problema encontrado, referencia la regla de anti-patrón específica del archivo de referencia relevante.
- Proporciona parches de código exactos.
Modo 3: Consulta rápida
Si el usuario pregunta "¿qué configuración de muelle para X?" o "¿cómo animo Y?", responde directamente desde los archivos de referencia y los presets de muelle sin ejecutar un flujo de trabajo completo.
Puntos No Negociables
- Comentario de guion gráfico ASCII. Cada página animada comienza con un comentario de línea de tiempo que muestra la secuencia completa de un vistazo. Los tiempos son absolutos desde el montaje, alineados a la derecha.
- Constantes de temporización con nombre. Cada retardo va en un objeto TIMING al principio del archivo. Sin números mágicos en props
setTimeoutodelay. - Muelle primero. Prefiere la física de muelle sobre el suavizado basado en duración para un movimiento natural e interrumpible. Usa duración solo para fundidos y tooltips.
- Secuenciación por etapas. Un único estado entero orquesta secuencias de múltiples secciones. Sin banderas booleanas dispersas.
- Patrón
stage >= N. Las secciones permanecen visibles una vez que aparecen. Nuncastage === N. - Nunca
layouten padre E hijos. Esta es la causa #1 de animaciones de filtro temblorosas. UsaAnimatedHeightconResizeObserveren su lugar. - Nunca
staggerChildrenconAnimatePresence. No funciona de forma fiable. Usadelay: i * staggermanual. - Respeta
prefers-reduced-motion. Heredado deanimation.md. Cada animación debe degradarse con elegancia. - Distinción entre montaje y actualización. Las animaciones de montaje son dramáticas (600 ms, suavizado expresivo). Las animaciones de actualización son sutiles (150 ms, suavizado suave). Fases diferentes, configuraciones diferentes.
Principios de Diseño
- Primero el guion gráfico — planifica la secuencia antes de escribir código
- Muelle primero — física de muelle sobre suavizado basado en duración
- Constantes con nombre — cada valor de temporización se declara, no está en línea
- Impulsado por etapas — un único estado entero orquesta secuencias complejas
- Impulsado por datos — los elementos repetidos usan
.map()con retardos basados en índice, no bloques copiados y pegados - Mide, no adivines —
ResizeObserverpara alturas dinámicas, nunca alturas en píxeles codificadas
Integración con Otras Habilidades
frontend-design-guidelines— la habilidad general de UI. Delega el trabajo de framer-motion a esta habilidad. Cuando ambas se activan, las reglas base deanimation.mdson autoritativas para las restricciones; esta habilidad es autoritativa para las recetas de implementación.number-formatting— para visualizaciones de números en vivo, usanumber-formattingpara la especificación de formato y esta habilidad para el patrón de animación de dígitos rodantes.brand-design— los colores de la marca pueden afectar las opciones de color de animación (indicadores positivos/negativos, resaltados de acento).
Recursos
references/
- references/page-choreography.md — Entrada de página por etapas con guiones gráficos ASCII, objetos TIMING, configuraciones de sección, presets de muelle y el patrón
stage >= N - references/list-stagger.md — Retardos de escalonamiento por índice, envoltorio StaggerItem, pautas de temporización/desplazamiento y anti-patrones
- references/popups-modals.md — Animación de modal en tres capas (fondo de escenario, panel, escalonamiento de contenido), patrón de menú desplegable, comportamientos de cierre
- references/filter-transitions.md — AnimatedHeight con ResizeObserver, fundido cruzado con envoltorio con clave, anti-patrón crítico de
layout - references/live-data.md — Dígitos de números rodantes (máquina tragaperras), revelaciones SVG de dona, transformación de gráficos, gestión de fase de montaje vs actualización
- references/hover-micro.md — Matriz de decisión CSS vs framer-motion, retroalimentación de botón, rotación de cheurón, entrada de tooltip, retroalimentación de copia
- references/spring-presets.md — Todos los presets como tablas + JSON: configuraciones de muelle, curvas de suavizado, valores de escalonamiento, presets de duración
Referencias entre habilidades
frontend-design-guidelines/references/animation.md— restricciones base que esta habilidad hereda (niveles de duración, suavizado, movimiento reducido, propiedades GPU)number-formatting— para reglas de visualización de números (formato, no animación)
Inicio Rápido
# Disparadores:
# "Arregla la carga de mi página — todo aparece a la vez"
# "Añade animaciones de entrada a este panel de control"
# "La animación del modal se siente entrecortada"
# "¿Cómo escalono estas tarjetas?"
# "¿Qué configuración de muelle debo usar para un menú desplegable?"
# "Añade animación de números rodantes a la visualización del saldo"
# Se activa automáticamente al construir componentes a nivel de página
Telemetría (ejecutar al final)
Después de que el flujo de trabajo de la habilidad se complete (éxito, error o cancelación), registra el evento de telemetría.
Determina el resultado del flujo de trabajo: success si se completó normalmente, error
si falló, abort si el usuario lo interrumpió.
Ejecuta este bash:
_TEL_END=$(date +%s)
_TEL_DUR=$(( _TEL_END - ${_TEL_START:-$_TEL_END} ))
_TEL_TIER=$(cat ~/.superstack/config.json 2>/dev/null | grep -o '"telemetryTier": *"[^"]*"' | head -1 | sed 's/.*"telemetryTier": *"//;s/"$//' || echo "anonymous")
if [ "$_TEL_TIER" != "off" ]; then
echo '{"skill":"page-load-animations","phase":"build","event":"completed","outcome":"RESULTADO","duration_s":"'"$_TEL_DUR"'","session":"'"$_SESSION_ID"'","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","platform":"'$(uname -s)-$(uname -m)'"}' >> ~/.superstack/telemetry.jsonl 2>/dev/null || true
true
fi
Reemplaza RESULTADO con success/error/abort según el resultado del flujo de trabajo.