Animações de UI seguras com Claude Code: guia prático

Comece pelo objetivo

Uma animação de UI segura com Claude Code não começa com “deixe a tela mais bonita”. Começa com a pergunta: qual incerteza do usuário esta animação deve reduzir? Um bloco que aparece ao entrar na tela pode orientar a leitura. Uma pequena reação no botão confirma o clique. Um estado de carregamento mostra que a aplicação ainda está trabalhando. Se o movimento não ajuda uma dessas situações, ele provavelmente é apenas ruído.

O erro comum de iniciantes é pedir a Claude Code “adicione animações”. A demo pode ficar agradável, mas uma página real tem largura móvel, foco de teclado, títulos longos, blocos de código, anúncios, tabelas de preço, estados vazios e a preferência prefers-reduced-motion. Neste guia, a implementação fica simples: CSS, um helper pequeno de JavaScript e uma revisão crítica antes de publicar.

Para contexto, leia também Claude Code design system, Claude Code responsive design e Claude Code performance optimization. As referências oficiais usadas aqui são Claude Code docs, MDN CSS animation, MDN Intersection Observer API, MDN prefers-reduced-motion e web.dev CSS animations. Intersection Observer é a API que informa quando um elemento entra no viewport. prefers-reduced-motion respeita pessoas que configuraram o sistema para reduzir movimento.

Prompt com limites

Peça uma mudança pequena e revisável. Um patch local é fácil de testar; uma página inteira redesenhada com movimento não é.

Adicione uma animação UI leve a esta tela.
O escopo é apenas: cards antes do CTA, seção exibida depois do carregamento e reação do botão de salvar.
Não altere componentes existentes, rotas, texto nem design tokens.
Priorize CSS e um helper pequeno de JavaScript. Não adicione biblioteca de animação sem justificar.
Retorne Use case, Pitfall, acessibilidade, comportamento com prefers-reduced-motion e resultado em 375px.

Esse prompt diz o alvo, o que não pode mudar e quais evidências devem voltar. Claude Code funciona melhor quando a fronteira é clara. Em um site publicado, o CTA de produto, a tabela de preço ou o formulário de consultoria não podem ficar menos legíveis porque a animação chamou atenção demais.

Use case（casos práticos）

Use case	Objetivo	Área animada	Sinal de sucesso
Artigo com conversão	Levar o leitor ao próximo recurso	Cards relacionados e CTA	A leitura continua calma
Dashboard SaaS	Mostrar salvar, sincronizar, carregar e erro	Botões, toast, estados vazios	O sentido não depende só de cor
Página de produto	Guiar por preço e benefícios	Comparativos e cards	O CTA principal fica visível
Revisão em equipe	Tornar o diff do Claude Code auditável	Escopo e checklist	Intenção e risco ficam registrados

O primeiro Use case é um artigo técnico. Depois de copiar o código, o leitor pode procurar templates ou ajuda para a equipe. Um reveal discreto perto de produtos ClaudeCodeLab ou treinamento e consultoria Claude Code ajuda sem parecer um banner agressivo. Um CTA pulsando o tempo todo atrapalha a leitura.

O segundo Use case é um painel. Quando o botão de salvar reage rapidamente e depois mostra “Salvo”, o usuário entende que a ação funcionou. A animação não deve ser a única informação. Texto visível, aria-busy, foco e mensagens de erro continuam necessários.

O terceiro Use case é uma página de produto. Tabelas de preço e comparativos concentram muita informação. Uma entrada em sequência pode organizar o olhar, mas uma sequência lenta atrasa a decisão. Movimento decorativo costuma caber em 200 a 500 ms; feedback de ação precisa parecer imediato.

O quarto Use case é colaboração. Peça a Claude Code que explique qual Use case cada animação atende e qual Pitfall evita. Assim a revisão sai do gosto pessoal e passa a avaliar objetivo, acessibilidade e risco.

Modelo de implementação

Separe a solução em três camadas.

Camada	Responsabilidade	O que Claude Code deve verificar
HTML	Marcar elementos que podem animar	Títulos, texto e CTA mantêm significado
CSS	Definir opacidade, distância, duração e easing	Usa opacity e transform antes de propriedades de layout
JavaScript	Controlar momento e limpeza	Trata reduced motion, fallback e desconecta observer

Essa estrutura reduz o diff. O HTML recebe data-reveal e reveal; o CSS cuida do estilo comum; o JavaScript adiciona is-visible quando o elemento aparece. O padrão funciona em Astro, React, Next.js ou páginas estáticas.

HTML para copiar

<section class="motion-demo" aria-labelledby="motion-demo-title">
  <p class="eyebrow">ClaudeCodeLab workflow</p>
  <h2 id="motion-demo-title">Rollout seguro de animações UI</h2>
  <p>
    Defina objetivo, alvo e verificação antes de pedir o patch ao Claude Code.
  </p>

  <div class="motion-grid">
    <article class="reveal" data-reveal>
      <h3>Design</h3>
      <p>Escolha um Use case e uma condição de sucesso.</p>
    </article>
    <article class="reveal" data-reveal>
      <h3>Implementação</h3>
      <p>Use variáveis CSS e um helper JS pequeno sem quebrar a UI.</p>
    </article>
    <article class="reveal" data-reveal>
      <h3>Validação</h3>
      <p>Confira Pitfall, reduce motion, mobile e teclado.</p>
    </article>
  </div>

  <a class="motion-cta reveal" data-reveal href="/pt/training/">
    Conversar sobre treinamento Claude Code
  </a>
</section>

CSS para copiar

O CSS usa principalmente opacity e transform. Animar width, height, top ou left pode gerar mais trabalho de layout. will-change fica restrito aos elementos revelados.

: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 para copiar

O helper revela cada elemento uma vez e depois para de observar. Se o navegador não tiver Intersection Observer, ou se reduced motion estiver ativo, o conteúdo aparece diretamente.

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();
});

Em Astro ou React, chame setupScrollReveal() depois que o componente montar. Se um modal ou tab criar conteúdo depois, passe esse container como root para evitar varrer o documento inteiro.

Exemplo de feedback no botão

Resposta a uma ação deve ser mais curta que animação de leitura. Este exemplo usa Web Animations API, mas com reduced motion apenas altera texto e 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 = "Salvando...";

  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 = "Salvo";
});

A interface precisa continuar compreensível sem movimento. O texto muda, o foco segue visível e tecnologias assistivas conseguem ler o estado pelo DOM.

Pitfall（erros concretos）

O primeiro Pitfall é intenção vaga. “Ficar mais premium” não é verificável. “Revelar três cards de preço quando entrarem no viewport sem cobrir o botão de compra” é verificável.

O segundo Pitfall é duração longa. Em artigo técnico, a pessoa quer chegar ao código. Em página comercial, quer comparar. Sequências lentas passam sensação de peso.

O terceiro Pitfall é overflow horizontal no mobile. translateX(40px) com sombras, tabelas ou blocos de código pode criar scroll em 375px. Prefira translateY() e teste 375px, 414px e tablet.

O quarto Pitfall é comunicar erro só por cor ou tremor. Inclua texto de erro, aria-describedby, foco claro e labels visíveis.

O quinto Pitfall é instalar biblioteca cedo demais. Timelines complexas podem precisar de ferramenta especializada, mas reveal de cards, toast e botão geralmente cabem em CSS e JS nativo.

O sexto Pitfall é aceitar o patch gerado apenas porque parece bom. Peça a Claude Code arquivos alterados, variáveis CSS, comportamento acessível, alternativas descartadas e testes manuais.

Revisão e validação

Depois de implementar, envie um prompt apenas de revisão.

Revise apenas o diff atual. Não implemente nada novo.
Relate nesta ordem:
1. Riscos de acessibilidade
2. Falta de prefers-reduced-motion
3. Possíveis falhas em mobile de 375px
4. Riscos de performance
5. Conflitos com CSS ou componentes existentes
6. Testes manuais antes do release
Seja rigoroso e cite seletores ou arquivos quando possível.

A checagem humana cobre movimento normal, reduced motion, teclado, mobile, rede lenta e dados vazios. No DevTools, simule prefers-reduced-motion e veja se a informação continua clara. Confirme que os CTAs de produtos e treinamento continuam visíveis e fáceis de tocar, e que blocos de código rolam dentro deles sem alargar a página.

Conexão com conversão

Animação UI não gera receita sozinha. Ela protege o caminho para a próxima ação. Desenvolvedores individuais podem procurar templates e checklists em produtos ClaudeCodeLab. Equipes que adotam Claude Code em repositórios reais podem precisar de permissões, CI, regras de review, CLAUDE.md e workshops em treinamento e consultoria Claude Code.

Em testes com layout parecido com artigo, o melhor ganho não veio de uma grande animação no hero. Veio de cards de recurso e CTA aparecendo uma vez, com calma, no fim do conteúdo. Separar implementação, revisão e correção deixou o diff menor e os riscos mais visíveis.

Resultado ao testar

Testei este fluxo em uma página parecida com artigo. A primeira etapa pediu apenas cards data-reveal, suporte a reduced motion e feedback curto no botão de salvar. A segunda etapa foi só revisão: largura de 375px, foco de teclado, dados vazios e visibilidade de CTA.

O resultado foi mais fácil de auditar do que um prompt amplo de “anime a página inteira”. Limitar o movimento a opacity e transform: translateY() reduziu surpresas no mobile. A melhoria real veio de exigir que cada movimento explicasse seu Use case, seu Pitfall, a alternativa sem movimento e os testes manuais.