Ir al contenido
Senzu

react-spring-physics

  • Grupo: Animación
  • Cuándo se activa: Animación basada en físicas en React (react-spring)
  • Se instala: Opcional: llega con un paquete de skills.

Documentación completa upstream (inglés): SKILL.upstream.md (464 líneas). No la leas entera: usa el mapa y lee solo la sección que necesites (Read con offset/limit o Grep).

Cuándo usar / cuándo NO

Sección titulada «Cuándo usar / cuándo NO»
  • Usar: movimiento natural e interrumpible en React (mass/tension/friction), drag/swipe con conservación de velocidad, inercia y snap a grid.
  • Usar: transiciones de listas (useTransition), cascadas (useTrail), reveal por viewport (useInView) o scroll (useScroll), animar props de react-three-fiber con @react-spring/three.
  • NO usar: proyecto vanilla, Vue o Astro sin React → animejs (easing spring(...)) o gsap-scrolltrigger; coreografía por timeline/scrub → gsap-scrolltrigger; variantes declarativas con gestos → motion-framer.

Lectura mínima por tarea

Sección titulada «Lectura mínima por tarea»
Tarea Lee solo
Empezar un proyecto/starter SKILL.upstream.md L26-97 (§Core Concepts) + assets/README.md (Vite react + npm i @react-spring/web)
Click / hover / trail / listas L100-176 (§1-3) o scripts/spring_generator.py --type transition
Scroll / viewport / cadenas async L177-236 (§4-6)
Drag con momentum / inercia Popmotion L237-259 (§7) + L290-312 + references/popmotion_api.md
Ajustar la sensación del muelle L75-97 (presets) + scripts/physics_calculator.py --feel bouncy + references/physics_guide.md
Integrar con react-three-fiber / formularios L262-330 (§Integration Patterns)
Depurar / rendimiento L331-367 (§Performance) + L368-441 (§Common Pitfalls)

Mapa de SKILL.upstream.md

Sección titulada «Mapa de SKILL.upstream.md»
Líneas Sección Para qué
10-25 Overview Cuándo usar; paquetes @react-spring/web, /three, popmotion
26-97 Core Concepts Física del muelle (28), patrones de useSpring objeto vs función+api (50), presets config.* (75)
98-259 Common Patterns Click (100), trail (131), transiciones de lista (155), scroll (177), inView (198), cadenas async (216), velocidad preservada (237)
260-330 Integration Patterns react-three-fiber (262), Popmotion inertia (290), shake en validación de formulario (313)
331-367 Performance Optimization precision, useSprings en lote, Globals.skipAnimation
368-441 Common Pitfalls Deps de useSpring, mutar valores, precisión, velocidad, mezclar patrones, strings no numéricos
442-464 Resources / Related Skills Scripts, referencias, física vs timeline

Recursos

Sección titulada «Recursos»
  • references/react_spring_api.md — hooks, animated, interpolación .to(), api.start/stop, eventos.
  • references/popmotion_api.md — spring, inertia, decay, keyframes y streams de Popmotion.
  • references/physics_guide.md — mass/tension/friction, amortiguación crítica, tabla de tuning.
  • scripts/spring_generator.py — boilerplate click/scroll/trail/transition/inview/chain/gesture: py -3 scripts/spring_generator.py --type gesture (Linux/mac: python3 …).
  • scripts/physics_calculator.py — calcula parámetros por sensación o amortiguación crítica: py -3 scripts/physics_calculator.py --feel bouncy / --critical-damping --tension 170.
  • assets/README.md — solo instrucciones de starter con Vite y enlaces oficiales (no existe carpeta starter_spring/ real pese al upstream).

Reglas duras

Sección titulada «Reglas duras»
  • useSpring(() => ({...}), []) con array de deps y usa api.start(); nunca springs.x.set() ni recrear el spring por render.
  • Anima valores numéricos individuales (x, rotation) y compón el transform con .to(); no pases strings compuestos.
  • Al interrumpir una animación pasa velocity: springs.x.getVelocity() para no cortar el momentum.
  • Fija config.precision (p. ej. 0.01) y agrupa con useSprings/useTrail para evitar renders innecesarios.
  • Respeta prefers-reduced-motion con Globals.assign({ skipAnimation: true }) (L356-367).

Integración con el stack del proyecto

Sección titulada «Integración con el stack del proyecto»
  • Detecta el stack como indica la skill front-activation/skill-router (senzu/senzu.json → package.json). Librería solo React (también Next/Remix/Astro con islas React); los hooks se ejecutan en cliente y useScroll/useInView requieren window, así que en SSR envuélvelos en componentes client-only.
  • Si el proyecto es Vue, Svelte o vanilla, no la instales: usa animejs (easing spring) o gsap-scrolltrigger; para 3D en React combina con react-three-fiber vía @react-spring/three.