Communitygithub.com

subtle-motion

Añade animaciones sutiles y pulidas a cualquier sitio web para que se sienta mejor sin resultar 'animado', manteniendo la capacidad de respuesta y sin tirones a 60fps incluso en móviles de gama baja.

¿Qué es subtle-motion?

Subtle Motion es una habilidad para agentes de IA (como Claude Code, Cursor o Codex) que aplica principios de animación de Disney adaptados a interfaces de usuario y leyes de UX relevantes al movimiento (Fitts, Hick, Miller, Doherty, Postel, Jakob, frecuencia de uso) para generar micro-interacciones, revelaciones al hacer scroll, efectos hover y otras mejoras de movimiento sutiles en cualquier proyecto web. La habilidad prioriza el rendimiento: solo anima `transform` y `opacity` con tiempos rápidos (<300ms), distancias pequeñas y curvas de aceleración/desaceleración. Es compatible con frameworks como React, Next, Vue, Svelte y Astro mediante CSS, sin depender de bibliotecas de animación. Sigue reglas estrictas como no animar propiedades costosas, respetar `prefers-reduced-motion`, efectos hover solo en dispositivos con hover, escalar la duración según el tamaño del elemento y mantener un máximo de ~5 puntos de interacción con movimiento por página. El flujo de trabajo comienza analizando el sitio existente y clasificando los elementos por frecuencia de uso. Luego selecciona hasta 5 puntos táctiles (botones, formularios, tarjetas, secciones, superposiciones) y aplica patrones CSS predefinidos. Finalmente, verifica el resultado y reporta cada cambio. Incluye fichas CSS globales (variables de duración y curvas de easing) que se añaden una sola vez. La habilidad se activa mediante comandos como `/subtle-motion` o solicitudes como 'haz que el sitio se sienta mejor/más suave', 'añade animaciones sutiles', 'añade micro-interacciones' o 'haz que se sienta menos estático'. Es preferible sobre otras habilidades de animación a menos que se requieran patrones específicos de Framer Motion o React.

Compatible con~Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/noni-was-taken/subtle-motion/tree/HEAD/skills/subtle-motion

Preguntar en tu IA favorita

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

Documentación

Movimiento Sutil

El movimiento es como la sal: el usuario debe sentir que el sitio es "suave", pero nunca notar "una animación". Fuentes: The Illusion of Life de Disney, Laws of UX de Jon Yablonski, userinterface.wiki de Raphael Salaja, Emil Kowalski (frecuencia de uso).

Reglas estrictas (nunca romper)

  1. Animar solo transform y opacity (además de filter/clip-path con moderación). Nunca animar width, height, top, left, margin, padding, el tamaño de box-shadow o font-size. ¿Necesitas un cambio de sombra? Desvanece la opacity de un pseudo-elemento.
  2. Tiempos rápidos: animaciones de UI en menos de 300ms. Presión 80–120ms, hover 150ms, entrada 200–300ms, salida ≈ 70% de la entrada. Solo un elemento hero único puede llegar a 500ms.
  3. Distancias pequeñas. Traslación de 2–16px, escala 0.97–1.03, rotación ≤ 6°. Distancias mayores parecen "animadas".
  4. Aceleración y desaceleración. Nunca linear en movimiento. ease-out para entrar, ease-in para salir.
  5. Frecuencia de uso: cuanto más se usa, menos anima. Navegación por teclado, paletas de comandos, pestañas usadas 100 veces al día, selección de listas: instantáneo (0ms) o un desvanecimiento de ≤100ms. Anima los momentos únicos y poco frecuentes, no los repetidos.
  6. Umbral de Doherty: responder en menos de 100ms, terminar en menos de 400ms. La retroalimentación (estado de presión, estado pendiente) comienza en el mismo fotograma que la entrada. Cualquier cosa más lenta que 400ms muestra progreso.
  7. prefers-reduced-motion: reduce elimina el movimiento. Los desvanecimientos de opacidad pueden permanecer.
  8. Efectos hover solo con @media (hover: hover). Si no, el táctil obtiene hovers pegajosos.
  9. CSS primero, sin bibliotecas de animación a menos que el proyecto ya tenga una. Sin bucles JS cuando CSS pueda hacerlo.
  10. Nunca retrasar ni ocultar contenido. Las revelaciones no deben ocultar contenido si JS falla, bloquear clics ni animar el elemento LCP al cargar.
  11. Puesta en escena: un movimiento focal a la vez. Máximo ~5 puntos de interacción con movimiento por página; nunca dos cosas compitiendo por la atención en el mismo momento.
  12. will-change solo durante la animación (o en ≤3 elementos persistentes).
  13. Interrumpible por defecto. El estado que puede cambiar a mitad de vuelo (hover, alternar, abrir/cerrar, indicador de pestaña) usa transition, que redirige desde donde esté. @keyframes solo para momentos únicos (sacudida, timbre, envío) que se reinician limpiamente.
  14. Escalar la duración según el tamaño y el iniciador. Elementos pequeños más rápidos que grandes (icono 100ms, tarjeta 250ms, panel 300ms). Iniciado por el usuario = inmediato; iniciado por el sistema (notificación, actualización en segundo plano) puede usar el extremo lento.
  15. Sin parpadeos de más de 3 veces/segundo; cualquier bucle de >5s necesita un control de pausa (o no hacer bucle).

Los principios, como reglas de UI

Elige los que se ajusten al punto de interacción; nunca todos a la vez. Cada uno se asigna a un patrón a continuación.

#PrincipioEn UI significaPatrón
1Aplastar y estirarLas cosas se aplastan al impactar, se estiran en movimiento: pesoPresión, Alternar
2AnticipaciónPequeño retroceso antes de un gran movimiento (enviar, enviar formulario, desplegar)Botón de envío
3Puesta en escenaDirigir la atención a una cosa: atenuar hermanos, un movimiento a la vezEnfoque de tarjeta
4Pose a poseDefinir estados de inicio/fin; dejar que el navegador interpoletransition, no JS fotograma a fotograma
5Seguimiento y superaciónLas partes se asientan después de que el cuerpo se detiene (pequeño rebasamiento)Notificación, Insignia
6Aceleración y desaceleraciónAcelerar y decelerar, nunca velocidad constanteFichas
7ArcosLos elementos que se mueven lo hacen en curvas, no en líneas rectasVuelo al carrito
8Acción secundariaPequeño adorno que respalda la acción principalAnillo de éxito
9Tiempos rápidosLa duración marca la sensación; UI < 300msFichas
10Retroalimentación exageradaIr más allá de lo real para que el momento impacte (errores, éxito)Sacudida de error
11Dibujo sólido / 3DDar profundidad y volumen a las cosas planasInclinación de tarjeta
12AtractivoLa suma de cada detalle, coherente en todo el sitioPasar verificación
Ley de UXConsecuencia para el movimientoPatrón
Ley de FittsLos objetivos más grandes y cercanos son más rápidos de alcanzarÁreas de impacto
Áreas de impacto más grandesÁrea cliqueable ≥ 44×44px, incluso si lo visual es más pequeñoÁreas de impacto
Ley de HickMás opciones = decisiones más lentas; no animar muchas opciones a la vezLímite de escalonamiento
Ley de MillerAgrupar contenido (~7 elementos); revelar en grupos, no elemento por elementoLímite de escalonamiento
Umbral de DohertyRetroalimentación <100ms, total <400ms, de lo contrario mostrar progresoEstado pendiente
Ley de PostelAceptar entrada desordenada, devolver salida limpia; animar la limpieza suavementeFormato de entrada
Ley de JakobUsar movimiento convencional (menús desplegables desde el disparador, modales desvanecer+escalar desde el centro)Superposición
Frecuencia de usoFrecuente = menos animaciónRegla 5

Flujo de trabajo

  1. Leer el sitio primero. Framework, enfoque CSS (Tailwind, CSS modules, plano), movimiento y fichas existentes. Reutilizarlos.
  2. Clasificar cada elemento interactivo por frecuencia: raro (registro, pago, éxito), ocasional (tarjetas, secciones, modales), frecuente (navegación, pestañas, paletas, filas de lista). Frecuente obtiene ≤100ms o nada.
  3. Elegir ≤5 puntos de interacción, ordenados por sensación-costo:
    1. Botones/enlaces: presión + área de impacto (principio 1, Fitts)
    2. Retroalimentación de formularios: sacudida de error, anillo de éxito, estado pendiente (10, 8, Doherty)
    3. Tarjetas: elevación al hover, inclinación opcional (11)
    4. Secciones: revelación al hacer scroll, escalonamiento agrupado (6, Miller)
    5. Superposiciones/notificaciones: entrada/salida con seguimiento (5, Jakob)
  4. Añadir las fichas una vez, de forma global.
  5. Aplicar patrones solo a los puntos de interacción elegidos.
  6. Verificar (última sección). No está terminado hasta que se verifica.
  7. Informar: cada punto de interacción con archivo:línea, el principio que aplica y cómo verlo.

Fichas (añadir una vez, de forma global)

:root {
  --ease-out: cubic-bezier(.23, 1, .32, 1);       /* entrada, hover */
  --ease-in: cubic-bezier(.55, 0, 1, .45);        /* salida */
  --ease-in-out: cubic-bezier(.65, 0, .35, 1);    /* movimiento en pantalla */
  --ease-settle: cubic-bezier(.34, 1.4, .64, 1);  /* seguimiento: ~4% de rebasamiento */
  /* sensación de muelle, interrumpible; los navegadores sin linear() recurren a `ease` */
  --ease-spring: linear(0, .07 3%, .29 9%, .62 18%, .86 28%, 1.01 40%, 1.03 50%, 1.015 65%, 1);
  --dur-press: 100ms;
  --dur-fast: 150ms;
  --dur-base: 250ms;
  --dur-slow: 300ms;
  --rise: 8px;
}
@media (prefers-reduced-motion: reduce) {
  :root { --rise: 0px; }
  *, *::before, *::after {
    animation-duration: 1ms !important;
    animation-iteration-count: 1 !important;
    transition-duration: 1ms !important;
    scroll-behavior: auto !important;
  }
}

¿Proyecto con Tailwind? Pon estos en @theme / extend de tailwind.config en lugar de un nuevo archivo CSS.

Patrones

Presión: aplastar (1) + área de impacto (Fitts)

.btn {
  position: relative;
  transition: transform var(--dur-fast) var(--ease-out), background-color var(--dur-fast) var(--ease-out);
}
@media (hover: hover) { .btn:hover { transform: translateY(-1px); } }
.btn:active { transform: scale(.97); transition-duration: var(--dur-press); }

/* Botones de icono pequeños: agrandar el área de impacto, no lo visual */
.icon-btn { position: relative; }
.icon-btn::before { content: ""; position: absolute; inset: 50% auto auto 50%; width: 44px; height: 44px; translate: -50% -50%; }

Alternar: aplastar y estirar (1)

La perilla se estira mientras viaja, se asienta cuando llega.

.switch .knob { transition: transform var(--dur-base) var(--ease-settle); }
.switch[aria-checked="true"] .knob { transform: translateX(20px); }
.switch:active .knob { transform: scaleX(1.2); transform-origin: left; }
.switch[aria-checked="true"]:active .knob { transform: translateX(20px) scaleX(1.2); transform-origin: right; }

Enviar / enviar formulario: anticipación (2)

Solo en acciones de "confirmación" poco frecuentes. Retrocede 2px, luego avanza.

@keyframes send { 0% { transform: none } 30% { transform: translate(-2px, 2px) } 100% { transform: translate(24px, -24px); opacity: 0 } }
.send.is-sending svg { animation: send 280ms var(--ease-in-out) forwards; }

Enfoque de tarjeta: puesta en escena (3)

@media (hover: hover) {
  .grid:has(.card:hover) .card:not(:hover) { opacity: .6; }
}
.grid .card { transition: opacity var(--dur-base) var(--ease-out); }

Usar solo en cuadrículas densas donde una elección importa. Omitir en contenido que se lee.

Elevación de tarjeta + inclinación opcional: dibujo sólido (11)

.card { position: relative; transition: transform var(--dur-base) var(--ease-out); }
.card::after {
  content: ""; position: absolute; inset: 0; border-radius: inherit; pointer-events: none;
  box-shadow: 0 12px 32px -12px rgb(0 0 0 / .25);
  opacity: 0; transition: opacity var(--dur-base) var(--ease-out);
}
@media (hover: hover) {
  .card:hover { transform: translateY(-3px); }
  .card:hover::after { opacity: 1; }
}

Inclinación (solo para elementos de exhibición como un producto, precio o tarjeta de crédito; ≤6°, solo puntero, limitado por rAF):

if (matchMedia('(hover: hover) and (prefers-reduced-motion: no-preference)').matches) {
  for (const el of document.querySelectorAll('.tilt')) {
    let raf = 0;
    el.addEventListener('pointermove', (e) => {
      cancelAnimationFrame(raf);
      raf = requestAnimationFrame(() => {
        const r = el.getBoundingClientRect(); // leer una vez por fotograma, no por transición
        const x = (e.clientX - r.left) / r.width - .5, y = (e.clientY - r.top) / r.height - .5;
        el.style.transform = `perspective(800px) rotateX(${-y * 6}deg) rotateY(${x * 6}deg)`;
      });
    });
    el.addEventListener('pointerleave', () => { cancelAnimationFrame(raf); el.style.transform = ''; });
  }
}

Notificación / insignia: seguimiento (5)

.toast { transition: transform var(--dur-slow) var(--ease-settle), opacity var(--dur-fast) var(--ease-out); }
.toast[data-state="closed"] { transform: translateY(12px); opacity: 0; transition-timing-function: var(--ease-in); }

Rebasamiento solo en cosas que llegan (notificaciones, insignias, contadores), nunca en diseño o bloques de texto.

Vuelo al carrito: arcos (7)

Dividir X e Y en dos elementos anidados con diferentes curvas de easing; la trayectoria se curva.

.fly-x { transition: transform 300ms linear; }
.fly-y { transition: transform 300ms var(--ease-in); }
.flying .fly-x { transform: translateX(var(--dx)); }
.flying .fly-y { transform: translateY(var(--dy)) scale(.4); }

Establecer --dx/--dy a partir de una lectura de getBoundingClientRect() antes de añadir .flying.

Anillo de éxito: acción secundaria (8)

.btn.is-success::after {
  content: ""; position: absolute; inset: -4px; border-radius: inherit; border: 2px solid currentColor;
  animation: ring 400ms var(--ease-out) forwards; pointer-events: none;
}
@keyframes ring { from { opacity: .6; transform: scale(.95) } to { opacity: 0; transform: scale(1.15) } }

Sacudida de error: retroalimentación exagerada (10)

@keyframes shake { 20%,60% { transform: translateX(-4px) } 40%,80% { transform: translateX(4px) } }
.field[aria-invalid="true"] { animation: shake 280ms var(--ease-in-out); }

Volver a activar eliminando y re-añadiendo el atributo. Siempre acompañar con un mensaje de texto (accesibilidad).

Estado pendiente: Umbral de Doherty

Retroalimentación de presión inmediatamente; si la acción tarda >400ms, mostrar un spinner/progreso dentro del botón (mantener su ancho fijo para evitar cambios de diseño). Preferir UI optimista: mostrar el resultado, revertir en caso de error.

Entrada desordenada → salida limpia: Ley de Postel

Formatear en blur (números de teléfono, tarjetas de crédito, fechas), no en cada pulsación de tecla. Hacer una transición suave del valor con un cambio de opacidad de 150ms, sin movimiento.

Revelación al hacer scroll: aceleración/desaceleración (6) + agrupación (Miller, Hick)

Contenido visible por defecto; solo oculto una vez que JS confirma que puede revelarlo.

.js .reveal {
  opacity: 0; transform: translateY(var(--rise));
  transition: opacity var(--dur-slow) var(--ease-out), transform var(--dur-slow) var(--ease-out);
  transition-delay: calc(min(var(--i, 0), 5) * 50ms);
}
.js .reveal.in { opacity: 1; transform: none; }
document.documentElement.classList.add('js');
const io = new IntersectionObserver((entries) => {
  for (const e of entries) if (e.isIntersecting) { e.target.classList.add('in'); io.unobserve(e.target); }
}, { rootMargin: '0px 0px -10% 0px' });
document.querySelectorAll('.reveal').forEach((el) => io.observe(el));
  • Escalonar con style="--i: n"; limitado a 6 pasos (Miller). Las listas largas se revelan como un grupo.
  • Revelar una vez. Omitir cualquier cosa que esté en la parte superior de la página.
  • Frameworks: mismo CSS; ejecutar el observador en un efecto de montaje, desconectar al desmontar.

Superposiciones: Ley de Jakob

Solo movimiento convencional: los desplegables crecen desde su disparador (transform-origin en el lado del disparador), los modales se desvanecen + escalan 0.98→1 desde el centro, las hojas se deslizan desde su borde. Nativo primero: <dialog> / popover con @starting-style.

dialog, [popover] {
  opacity: 0; transform: translateY(4px) scale(.98);
  transition: opacity var(--dur-fast) var(--ease-in), transform var(--dur-fast) var(--ease-in),
              overlay var(--dur-fast) allow-discrete, display var(--dur-fast) allow-discrete;
}
dialog[open], [popover]:popover-open {
  opacity: 1; transform: none;
  transition-timing-function: var(--ease-out); transition-duration: var(--dur-base);
}
@starting-style {
  dialog[open], [popover]:popover-open { opacity: 0; transform: translateY(4px) scale(.98); }
}

Paleta de comandos / menú abierto por teclado muchas veces al día: la frecuencia de uso indica omitir la transición.

Pestañas: superficie de carpeta que se desliza (no una línea de acento)

La señal de IA/plantilla es la línea de acento fina, no el movimiento. Usar una forma física familiar (Jakob) y dejar que esa forma haga el movimiento:

  • Pestañas tipo carpeta (preferidas): la superficie de la pestaña seleccionada se fusiona con el panel y se desliza hacia la pestaña cliqueada.
  • Control segmentado: para 2–4 opciones; el segmento presionado se desliza de la misma manera.

Hacer que las pestañas tengan el mismo ancho para que la superficie solo necesite translateX (sin ancho ni scaleX, que distorsiona el radio y el borde). Usar una transición de ≤150ms para que siga siendo interrumpible. El contenido cambia instantáneamente (frecuencia de uso).

.tabs { position: relative; display: flex; gap: 2px; border-bottom: 1px solid var(--line); }
.tabs [role=tab] { position: relative; z-index: 1; flex: 0 0 96px; padding: 8px 0; cursor: pointer; border: none; background: none; color: inherit; }
.tabs .surface {
  position: absolute; bottom: -1px; left: 0; width: 96px; height: calc(100% + 1px);
  background: var(--surface); border: 1px solid var(--line); border-bottom-color: var(--surface);
  border-radius: 8px 8px 0 0;
  transition: transform 150ms var(--ease-out); pointer-events: none;
}

No scaleX, no transiciones de ancho.

Verificación

Nunca declarar terminado hasta que:

  • Sin animaciones de ancho/alto/top/left (usar transform)
  • Sin lineales: cubic-bezier en todos los lados
  • will-change solo durante la animación o en ≤3 elementos
  • prefers-reduced-motion respetado (sin movimiento, desvanecimiento permitido)
  • Efectos hover envueltos en @media (hover: hover)
  • Sin retrasos de contenido (sin loading=lazy en LCP, sin ocultar hasta JS)
  • Duración de UI < 300ms (dar o recibir 50ms para hero único)
  • Las pestañas cambian de contenido instantáneamente; solo se desliza la superficie
  • Las paletas de comandos, menús de teclado y navegación frecuente son instantáneos o tienen un desvanecimiento de ≤100ms
  • Los elementos que se revelan al hacer scroll son visibles por defecto (sin clase .js = sin rotura)
  • Sin parpadeo de más de 3 veces/segundo
  • Sin dos animaciones compitiendo en el mismo momento
  • La página se siente suave al navegar, sin tirones

Informe

Después de aplicar los patrones, informa cada punto de interacción tocado en:

## Cambios de movimiento

**touchpoint** | **archivo:línea** | **qué** | **principio** | **cómo ver**
---|---|---|---|---
Botón de registro | `src/components/Button.module.css:12` | Presión squash + área de impacto 44px | 1, Fitts | Hover y hacer clic el botón «Registrarse»; el área de impacto funciona aunque el botón sea pequeño
Entrada de tarjeta | `src/components/CreditCard/Input.tsx:45` | Formato en blur, desvanecimiento de 150ms | Postel | Escribir un número de tarjeta inválido y hacer clic fuera; se formatea suavemente
...

Solo enumerar los puntos de interacción modificados, no cada línea de CSS.

Skills relacionados