用 Claude Code 安全实现 UI 动画的实务指南

先定义动画要解决的问题

用 Claude Code 做 UI 动画时，不要从“让页面更酷”开始，而要从“用户哪里会不安、哪里需要反馈”开始。安全的动画不是装饰，它应该帮助读者理解状态：内容已经加载、保存已经完成、错误需要处理、下一步可以去产品页或培训咨询页。只要这个目的说不清，动画就很容易变成干扰。

初学者常见的做法是直接让 Claude Code “加一点动画”。这样很快会得到能看的 demo，但上线页面里还有移动端宽度、键盘焦点、广告位、长标题、代码块、空数据、prefers-reduced-motion 等现实约束。本文用 CSS 和少量 JavaScript 做三个实用例子：滚动出现、按钮反馈、状态更新。代码可以复制到普通页面中试跑，也可以改造成 Astro、React 或 Next.js 组件。

建议同时阅读 Claude Code design system、Claude Code responsive design 和 Claude Code performance optimization。官方资料请参考 Claude Code docs、MDN CSS animation、MDN Intersection Observer API、MDN prefers-reduced-motion、web.dev CSS animations。Intersection Observer 是浏览器用来判断元素是否进入视口的 API；prefers-reduced-motion 则让你尊重系统里选择减少动态效果的用户。

给 Claude Code 的提示词

先把任务缩小。一个局部动画补丁容易审查，整页重做很难判断风险。

请给这个页面添加轻量 UI 动画。
只处理 CTA 前的卡片、加载完成后出现的区块、保存按钮的反馈。
不要重写现有组件、路由、文案或设计 token。
优先使用 CSS 和少量 JavaScript，除非说明原因，否则不要增加动画库。
请返回 Use case、Pitfall、可访问性检查、prefers-reduced-motion 处理方式，以及 375px 移动端检查结果。

这个提示词把目标元素、禁止事项和验收标准写清楚。Claude Code 很擅长生成代码，但如果边界太宽，它可能顺手调整周边布局。对于已经发布的站点，改动越小，越容易发现问题。尤其是文章、产品卡片、价格表、咨询表单这些转化路径，动画必须服务阅读和点击，而不是抢走注意力。

Use case（适合使用的场景）

Use case	目标	动画位置	成功标准
文章转化	让读者在学完后找到下一步	相关文章、产品卡片、CTA	不打断阅读和复制代码
SaaS 后台	让保存、同步、错误、空状态更明确	按钮、toast、空数据区	不只靠颜色表达含义
产品页面	引导读者看价格和优势	比较表、权益卡、购买 CTA	主按钮始终可见
团队审查	让 Claude Code 的 diff 更容易审	限定文件和检查清单	reviewer 能看到目的和风险

第一个 Use case 是教程或博客文章。读者读完代码后，可能需要现成模板，也可能需要团队落地支持。此时可以自然引导到 ClaudeCodeLab 产品 或 Claude Code 培训与咨询。但 CTA 不能一直跳动，否则会干扰读者复制代码。

第二个 Use case 是后台界面。保存按钮被点击后轻微缩放，再把文字改成“已保存”，用户就能确认操作被接收。这里的重点是：动画只是辅助，文字、aria-busy、焦点样式和错误信息仍然要存在。

第三个 Use case 是产品和价格页面。表格、套餐、权益说明信息量很大，顺序出现可以帮助视线移动。但每张卡都等一秒才出现，会拖慢购买判断。装饰动画通常控制在 200 到 500 毫秒，用户操作反馈则要更快。

第四个 Use case 是团队协作。让 Claude Code 说明每个动画服务哪个 Use case、避开哪个 Pitfall，审查时就不会只争论“好不好看”，而能回到业务目的和风险。

实现结构

把实现拆成三层，代码会更稳定。

层级	职责	需要 Claude Code 检查
HTML	标记哪些元素可以动	标题、正文、CTA 语义是否保留
CSS	定义透明度、位移、时长、缓动	是否优先使用 opacity 和 transform
JavaScript	控制出现时机和清理	是否处理 reduce motion、兼容性、observer 释放

这样拆分后，HTML 只加 data-reveal 和 reveal class；CSS 只管理统一的 motion 样式；JS 只负责添加 is-visible。未来要搬到组件框架里，也不会把业务逻辑和动画逻辑缠在一起。

可复制 HTML

<section class="motion-demo" aria-labelledby="motion-demo-title">
  <p class="eyebrow">ClaudeCodeLab workflow</p>
  <h2 id="motion-demo-title">安全 UI 动画上线流程</h2>
  <p>
    先确定目的、目标元素和验证方式，再让 Claude Code 生成小 diff。
  </p>

  <div class="motion-grid">
    <article class="reveal" data-reveal>
      <h3>设计</h3>
      <p>只选择一个 Use case 和一个成功条件。</p>
    </article>
    <article class="reveal" data-reveal>
      <h3>实现</h3>
      <p>用 CSS 变量和小 JavaScript helper，不破坏现有 UI。</p>
    </article>
    <article class="reveal" data-reveal>
      <h3>验证</h3>
      <p>检查 Pitfall、reduce motion、移动端和键盘操作。</p>
    </article>
  </div>

  <a class="motion-cta reveal" data-reveal href="/zh/training/">
    咨询 Claude Code 培训
  </a>
</section>

可复制 CSS

CSS 主要动画 opacity 和 transform。尽量不要动画 width、height、top、left，因为它们更容易触发布局计算。will-change 只给需要出现的元素使用，不要全局乱加。

: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

下面的 helper 只让元素出现一次，然后取消观察。对 reduce motion 用户或不支持 Intersection Observer 的浏览器，内容会直接显示。

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

如果页面切换后会重新挂载内容，就在对应生命周期里再次调用 setupScrollReveal()。如果 tab 或 modal 里动态插入卡片，可以把容器作为 root 传入，避免重新扫描整个 document。

按钮反馈示例

按钮反馈要比滚动出现更短。下面例子使用 Web Animations API，但 reduce motion 时不会播放动画，仍然通过文字和 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 = "正在保存...";

  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 = "已保存";
});

这个例子体现了可访问性原则：没有动画时，界面仍然可理解。状态文字会变化，焦点仍然可见，辅助技术可以从 DOM 读到处理状态。

Pitfall（具体陷阱）

第一个 Pitfall 是目的不清。无法验证“更有高级感”，但可以验证“价格卡片进入视口时出现，并且购买按钮不被遮挡”。让 Claude Code 先写出目标，再写代码。

第二个 Pitfall 是动画太慢。教程文章的读者想快速看到代码，产品页的读者想快速比较价格。卡片依次出现可以，但每个元素延迟太久会让页面显得迟钝。

第三个 Pitfall 是移动端横向溢出。translateX(40px)、阴影、表格和代码块叠在一起时，很容易让 375px 宽度出现横向滚动。优先使用纵向位移，发布前检查 375px、414px 和平板宽度。

第四个 Pitfall 是只用颜色或晃动表达错误。表单字段变红还不够，必须有错误文本、aria-describedby、合理的焦点移动和可点击区域。

第五个 Pitfall 是过早引入动画库。复杂时间线可以用专业库，但文章卡片出现、toast、按钮反馈通常不需要。先用原生 CSS 和小 JS 证明需求，再考虑依赖。

第六个 Pitfall 是直接接受生成结果。请 Claude Code 列出改动文件、新增 CSS 变量、手动检查项、没有采用的方案和已知风险。这样 reviewer 才能判断它是否真的安全。

审查与验证

实现后，再发一次只审查的提示词，不要让 Claude Code 同时继续写新功能。

只审查当前 diff，不要实现新功能。
请按顺序指出：
1. 可访问性风险
2. prefers-reduced-motion 漏洞
3. 375px 移动端可能崩的位置
4. 性能问题
5. 与现有 CSS 或组件冲突的地方
6. 发布前人类必须手动确认的操作
请尽量引用具体 selector 或文件。

人工检查要覆盖普通动画、reduce motion、键盘导航、移动端、慢网络、空数据。用浏览器开发者工具模拟 prefers-reduced-motion，确认页面没有动画也能传达同样的信息。还要检查 产品页 和 培训咨询页 的 CTA 是否容易点击，代码块是否只在自身内部横向滚动，而不是撑宽整个页面。

和转化路径连接

UI 动画本身不会创造收入，它只是保护用户走向下一步的路径。个人开发者可能需要提示词模板、检查清单或可下载材料，可以去 ClaudeCodeLab 产品。团队如果要把 Claude Code 放进真实仓库，就需要权限、review gate、CI、CLAUDE.md 和培训流程，可以看 Claude Code 培训与咨询。

Masa 在类似博客布局中试过后，感觉最有价值的不是大幅 hero 动画，而是让相关文章、产品卡片和 CTA 在合适时机轻轻出现。这样既不会打断复制代码，也让读者在读完后自然看到下一步。把实现、审查、修正分成三步，比一次性让 Claude Code “重做动画”更容易控制风险。

实际试用后的结果

这套流程在接近真实文章页的布局里测试过：第一次只让 Claude Code 添加 data-reveal 卡片、reduce motion 处理和保存按钮反馈；第二次只做审查，重点看 375px 宽度、键盘焦点、空数据和 CTA 可见性。

结果是，小范围 diff 更容易发现 Pitfall。把动画限制在 opacity 和 transform: translateY() 后，移动端横向溢出明显减少。真正提升质量的不是动画数量，而是每个动画都能说明 Use case、保留文字状态、尊重 reduced motion，并且在发布前有明确的验证清单。