Animaciones UI seguras con Claude Code: guía práctica

Empieza por la intención

Una animación UI segura con Claude Code no empieza preguntando qué efecto se ve más moderno. Empieza con una pregunta de producto: qué duda del usuario queremos reducir. Una tarjeta que aparece al entrar en pantalla puede guiar la lectura. Una respuesta corta en un botón confirma que el clic se recibió. Un estado de carga evita que el usuario piense que la aplicación se congeló. Si el movimiento no cumple una función así, probablemente sea ruido.

El error típico de principiante es pedir “haz esta página más animada”. Claude Code puede producir una demo atractiva, pero una página real también tiene ancho móvil, foco de teclado, textos largos, bloques de código, anuncios, tablas de precio, estados vacíos y la preferencia prefers-reduced-motion. En este artículo implementamos scroll reveal, respuesta de botón y actualización de estado con CSS y JavaScript pequeño, sin depender de una librería pesada.

Para mantener el contexto, revisa también Claude Code design system, Claude Code responsive design y Claude Code performance optimization. Las referencias oficiales son Claude Code docs, MDN CSS animation, MDN Intersection Observer API, MDN prefers-reduced-motion y web.dev CSS animations. Intersection Observer es la API del navegador que avisa cuándo un elemento entra en el viewport. prefers-reduced-motion permite respetar a personas que han pedido menos movimiento en el sistema.

Prompt con límites claros

El primer paso es pedir un cambio pequeño y revisable. No conviene convertir una mejora puntual en un rediseño completo.

Añade una animación UI ligera a esta pantalla.
El alcance es solo: tarjetas antes del CTA, sección que aparece tras la carga y reacción del botón de guardar.
No cambies componentes existentes, rutas, copy ni tokens de diseño.
Prioriza CSS y un helper pequeño de JavaScript; no añadas librerías sin justificarlo.
Devuelve Use case, Pitfall, accesibilidad, comportamiento con prefers-reduced-motion y resultado en 375px.

Este prompt le da a Claude Code un marco de trabajo. Define los elementos, lo que no se debe tocar y las pruebas que esperamos. En un sitio publicado, esta disciplina importa más que el efecto visual. Un CTA de producto, una tabla de precios o un formulario de consulta no deben volverse menos claros porque el agente decidió animar demasiado.

Use case（casos prácticos）

Use case	Objetivo	Zona animada	Señal de éxito
Artículo que convierte	Ayudar a encontrar el siguiente recurso	Tarjetas relacionadas y CTA	La lectura sigue tranquila
Dashboard SaaS	Mostrar guardado, sincronización, carga y errores	Botones, toast, estados vacíos	El significado no depende solo del color
Página de producto	Guiar por precio y beneficios	Comparativas y tarjetas	El CTA principal no se oculta
Revisión en equipo	Hacer auditable el diff de Claude Code	Alcance y checklist	Se explican intención y riesgo

El primer Use case es una guía técnica. Después de leer el código, la persona puede necesitar plantillas o acompañamiento para equipo. Una aparición sutil cerca de productos ClaudeCodeLab o formación y consultoría Claude Code puede ayudar sin parecer publicidad invasiva. Si el CTA late todo el tiempo, distrae de copiar y comparar el código.

El segundo Use case es un panel interno. Cuando el botón de guardar reacciona rápido y luego cambia a “Guardado”, el usuario entiende que la acción se recibió. La animación no debe ser la única señal: texto visible, aria-busy, foco y mensajes de error siguen siendo obligatorios.

El tercer Use case es una página de producto. Las comparativas y las tablas de precios son densas. Un reveal escalonado puede ordenar la atención, pero si cada elemento tarda demasiado, retrasa la decisión de compra. Para movimiento decorativo, 200 a 500 ms suele ser suficiente. La respuesta a una acción debe sentirse inmediata.

El cuarto Use case es trabajo en equipo. Pide a Claude Code que explique qué Use case cubre cada movimiento y qué Pitfall evita. Así la revisión deja de ser una discusión de gustos y se convierte en una revisión de intención, accesibilidad y riesgo.

Modelo de implementación

Divide la solución en tres capas.

Capa	Responsabilidad	Qué debe comprobar Claude Code
HTML	Marcar qué elementos pueden moverse	La semántica de títulos, texto y CTA se conserva
CSS	Definir opacidad, distancia, duración y easing	Se usan opacity y transform antes que propiedades de layout
JavaScript	Controlar el momento y la limpieza	Hay reduce motion, fallback y desconexión del observer

Esta separación mantiene el diff pequeño. HTML solo recibe data-reveal y la clase reveal; CSS define el patrón común; JavaScript añade is-visible cuando corresponde. Es un patrón fácil de llevar a Astro, React, Next.js o una página estática.

HTML copiable

<section class="motion-demo" aria-labelledby="motion-demo-title">
  <p class="eyebrow">ClaudeCodeLab workflow</p>
  <h2 id="motion-demo-title">Implementación segura de animaciones UI</h2>
  <p>
    Define objetivo, elemento y verificación antes de pedir a Claude Code el cambio.
  </p>

  <div class="motion-grid">
    <article class="reveal" data-reveal>
      <h3>Diseño</h3>
      <p>Elige un Use case y una condición de éxito.</p>
    </article>
    <article class="reveal" data-reveal>
      <h3>Implementación</h3>
      <p>Usa variables CSS y un helper pequeño sin romper la UI existente.</p>
    </article>
    <article class="reveal" data-reveal>
      <h3>Validación</h3>
      <p>Comprueba Pitfall, reduce motion, móvil y teclado.</p>
    </article>
  </div>

  <a class="motion-cta reveal" data-reveal href="/es/training/">
    Consultar formación Claude Code
  </a>
</section>

CSS copiable

El CSS usa opacity y transform. Animar width, height, top o left suele provocar más trabajo de layout. will-change está limitado a los elementos que se revelan.

:root {
  --motion-duration: 420ms;
  --motion-distance: 16px;
  --motion-ease: cubic-bezier(0.16, 1, 0.3, 1);
  --motion-border: #d8e2ee;
  --motion-bg: #ffffff;
  --motion-text: #182230;
  --motion-accent: #2563eb;
}

.motion-demo {
  color: var(--motion-text);
  max-width: 920px;
  margin: 48px auto;
  padding: 24px;
}

.eyebrow {
  margin: 0 0 8px;
  color: var(--motion-accent);
  font-weight: 700;
}

.motion-grid {
  display: grid;
  grid-template-columns: repeat(3, minmax(0, 1fr));
  gap: 16px;
  margin: 24px 0;
}

.motion-grid article {
  border: 1px solid var(--motion-border);
  border-radius: 8px;
  background: var(--motion-bg);
  padding: 16px;
}

.reveal {
  opacity: 0;
  transform: translateY(var(--motion-distance));
  transition:
    opacity var(--motion-duration) var(--motion-ease),
    transform var(--motion-duration) var(--motion-ease);
  will-change: opacity, transform;
}

.reveal.is-visible {
  opacity: 1;
  transform: translate3d(0, 0, 0);
}

.motion-cta {
  display: inline-flex;
  align-items: center;
  justify-content: center;
  min-height: 44px;
  padding: 0 18px;
  border-radius: 8px;
  background: var(--motion-accent);
  color: #ffffff;
  font-weight: 700;
  text-decoration: none;
}

.motion-cta:focus-visible {
  outline: 3px solid #f59e0b;
  outline-offset: 3px;
}

@media (max-width: 640px) {
  .motion-demo {
    margin: 32px auto;
    padding: 16px;
  }

  .motion-grid {
    grid-template-columns: 1fr;
  }
}

@media (prefers-reduced-motion: reduce) {
  .reveal {
    opacity: 1;
    transform: none;
    transition: none;
    will-change: auto;
  }
}

JavaScript copiable

El helper muestra cada elemento una sola vez y después deja de observarlo. Si el navegador no soporta Intersection Observer, o si la persona prefiere menos movimiento, el contenido se muestra directamente.

export function setupScrollReveal(root = document) {
  const targets = Array.from(root.querySelectorAll("[data-reveal]"));
  const reduceMotion = window.matchMedia("(prefers-reduced-motion: reduce)").matches;

  if (targets.length === 0) {
    return () => {};
  }

  if (reduceMotion || !("IntersectionObserver" in window)) {
    targets.forEach((target) => target.classList.add("is-visible"));
    return () => {};
  }

  const observer = new IntersectionObserver(
    (entries) => {
      for (const entry of entries) {
        if (!entry.isIntersecting) continue;
        entry.target.classList.add("is-visible");
        observer.unobserve(entry.target);
      }
    },
    {
      root: null,
      rootMargin: "0px 0px -10% 0px",
      threshold: 0.1,
    },
  );

  targets.forEach((target) => observer.observe(target));

  return () => observer.disconnect();
}

document.addEventListener("DOMContentLoaded", () => {
  setupScrollReveal();
});

En Astro o React, llama a setupScrollReveal() después de montar el componente. Si un modal o tab crea contenido más tarde, pasa ese contenedor como root para no recorrer todo el documento.

Ejemplo de respuesta de botón

La respuesta a una acción debe ser más corta que una animación de lectura. Este ejemplo usa Web Animations API, pero con reduce motion solo actualiza texto y estado ARIA.

const button = document.querySelector("[data-save-button]");
const status = document.querySelector("[data-save-status]");

button?.addEventListener("click", async () => {
  const reduceMotion = window.matchMedia("(prefers-reduced-motion: reduce)").matches;
  button.setAttribute("aria-busy", "true");
  status.textContent = "Guardando...";

  if (!reduceMotion) {
    await button.animate(
      [
        { transform: "scale(1)" },
        { transform: "scale(0.97)" },
        { transform: "scale(1)" },
      ],
      { duration: 180, easing: "ease-out" },
    ).finished;
  }

  await new Promise((resolve) => window.setTimeout(resolve, 300));
  button.setAttribute("aria-busy", "false");
  status.textContent = "Guardado";
});

La interfaz debe entenderse aunque nada se mueva. El texto cambia, el foco sigue visible y las tecnologías de asistencia pueden leer el estado desde el DOM.

Pitfall（errores concretos）

El primer Pitfall es no tener intención. “Más premium” no se puede revisar. “Mostrar las tres tarjetas de precio cuando entran en pantalla sin ocultar el botón de compra” sí se puede comprobar.

El segundo Pitfall es alargar demasiado la duración. En una guía técnica, el lector quiere llegar al código; en una página comercial, quiere comparar rápido. Si todo entra lentamente, la página parece pesada.

El tercer Pitfall es el desbordamiento móvil. translateX(40px) con sombras, tablas o bloques de código puede crear scroll horizontal a 375px. Prefiere movimiento vertical y prueba 375px, 414px y tablet.

El cuarto Pitfall es comunicar errores solo con color o sacudidas. Añade texto de error, aria-describedby, foco claro y etiquetas visibles.

El quinto Pitfall es instalar una librería antes de necesitarla. Una timeline compleja puede justificar una herramienta especializada; un reveal de tarjetas y una respuesta de botón casi siempre caben en CSS y JS nativo.

El sexto Pitfall es aceptar el patch generado porque “se ve bien”. Pide a Claude Code una lista de archivos cambiados, variables CSS nuevas, comportamiento accesible, alternativas descartadas y pruebas manuales.

Revisión y validación

Después de implementar, usa un prompt solo de revisión.

Revisa únicamente el diff actual. No implementes nada nuevo.
Informa en este orden:
1. Riesgos de accesibilidad
2. Falta de prefers-reduced-motion
3. Posibles fallos en móvil de 375px
4. Riesgos de rendimiento
5. Choques con CSS o componentes existentes
6. Pruebas manuales antes de publicar
Sé estricto y cita selectores o archivos concretos cuando puedas.

La revisión humana debe cubrir movimiento normal, reduce motion, navegación por teclado, móvil, red lenta y datos vacíos. En DevTools, emula prefers-reduced-motion y comprueba que la página comunica lo mismo. Revisa que los CTA de productos y formación sigan visibles, que el bloque de código no ensanche toda la página y que el foco sea fácil de ver.

Conexión con conversión

La animación UI no vende por sí misma. Ayuda a que la persona llegue al siguiente paso sin perder confianza. Un desarrollador individual puede necesitar plantillas y checklists en ClaudeCodeLab productos. Un equipo que introduce Claude Code en repositorios reales puede necesitar permisos, CI, reglas de revisión y sesiones internas en Claude Code formación y consultoría.

En pruebas con un layout parecido a un artículo, el cambio más útil no fue una gran animación hero, sino hacer que las tarjetas de recursos y el CTA aparecieran una vez, con calma, al final del contenido. Dividir el trabajo en implementación, revisión y corrección redujo el ruido del diff y encontró problemas antes de publicar.

Resultado al probarlo

Probé este flujo sobre una página tipo artículo. La primera pasada pidió solo tarjetas data-reveal, soporte de reduce motion y reacción breve del botón de guardar. La segunda pasada fue solo revisión: ancho 375px, foco de teclado, datos vacíos y visibilidad de CTA.

El resultado fue más fácil de auditar que un prompt grande de “anima toda la página”. Limitar el movimiento a opacity y transform: translateY() redujo sorpresas en móvil. La mejora real vino de obligar a cada animación a explicar su Use case, su Pitfall, su alternativa sin movimiento y su comprobación manual.