用 Claude Code 实现高级 CSS 动画：性能、无障碍与可验证方案

CSS 动画不只是让界面动起来

让 Claude Code 写一个淡入、滑入或骨架屏动画很容易，真正困难的是让它进入生产环境后仍然稳定。好的动画应该解释界面发生了什么变化，而不是抢走用户注意力。它还必须足够快，尊重用户的减少动态效果设置，并且能被设计系统长期维护。

本文从实现角度讲高级 CSS 动画：transition 与 keyframes 的选择，为什么优先动画化 transform 和 opacity，什么是 layout thrash，如何处理 prefers-reduced-motion，如何做滚动联动和入口动画，骨架屏什么时候有用，怎样把动画参数做成设计令牌，以及如何用 Playwright 检查横向溢出和减少动态效果。

先解释几个术语。transition 是两个状态之间的平滑过渡，比如按钮 hover 时上移。keyframes 是带时间点的动画剧本，比如 0%、60%、100%。layout thrash 指浏览器反复重新计算元素尺寸和位置，通常会造成卡顿。设计令牌是有名字的设计值，例如 --motion-duration-fast，方便团队统一速度、缓动和距离。

相关主题可以继续阅读 Claude Code 性能优化、Claude Code CSS 变量 和 Claude Code 无障碍实现。

明确选择 transition 还是 keyframes

transition 适合小型状态变化：hover、focus、选中、展开、禁用。keyframes 适合需要设计中间过程的场景：入口动画、加载循环、分阶段提示、阅读进度或滚动显示。

给 Claude Code 的提示要直接说明这种选择。如果只说“做得更有动感”，生成代码可能会动画化 top、left、height 或 margin。这些属性容易触发布局计算，页面会显得不顺。更好的提示是：交互状态用 transition，时间轴动画用 keyframes，位移和出现优先使用 transform 与 opacity。

:root {
  --motion-duration-fast: 160ms;
  --motion-duration-normal: 280ms;
  --motion-ease-standard: cubic-bezier(0.2, 0, 0, 1);
  --motion-distance-sm: 12px;
}

.button {
  transition:
    background-color var(--motion-duration-fast) var(--motion-ease-standard),
    transform var(--motion-duration-fast) var(--motion-ease-standard);
}

.button:hover {
  transform: translateY(-2px);
}

.notice {
  opacity: 0;
  transform: translateY(var(--motion-distance-sm));
  animation: notice-enter var(--motion-duration-normal) var(--motion-ease-standard) forwards;
}

@keyframes notice-enter {
  from {
    opacity: 0;
    transform: translateY(var(--motion-distance-sm));
  }
  to {
    opacity: 1;
    transform: translateY(0);
  }
}

这里按钮使用 transition，因为它响应用户状态；通知使用 keyframes，因为它有明确入口过程。语法细节可以查 MDN 的 CSS animations 和 transform。

性能从 transform 和 opacity 开始

浏览器绘制一帧大致经过布局、绘制和合成。布局计算尺寸和位置，绘制负责颜色和阴影，合成把图层组合到屏幕上。transform 和 opacity 通常更容易停留在合成阶段，所以比修改宽高或边距更稳。

width、height、margin、top、left 会影响周围元素，频繁动画化时容易造成 layout thrash。写 React 组件时，也要把动画类名保持简单，让 Claude Code 和测试都容易检查。

import type { ReactNode } from "react";
import "./motion.css";

type AnimatedPanelProps = {
  children: ReactNode;
  isOpen: boolean;
};

export function AnimatedPanel({ children, isOpen }: AnimatedPanelProps) {
  return (
    <section
      className={isOpen ? "panel panel-enter" : "panel"}
      aria-hidden={!isOpen}
    >
      {children}
    </section>
  );
}

.panel {
  opacity: 0;
  transform: translateY(12px) scale(0.98);
  pointer-events: none;
}

.panel-enter {
  animation: panel-enter 220ms cubic-bezier(0.2, 0, 0, 1) forwards;
  pointer-events: auto;
}

@keyframes panel-enter {
  to {
    opacity: 1;
    transform: translateY(0) scale(1);
  }
}

will-change 也要谨慎。它不是性能万能药，长期挂在大量元素上会浪费内存。web.dev 的 animation performance guide 对属性选择和性能关系讲得很清楚。

三个以上真实使用场景

第一个场景是卡片、价格表或仪表盘模块的入口动画。短暂的淡入可以引导视线，但每张卡都延迟很久会让读者等待。建议只给关键区域轻微延迟，并保证动画失败时内容仍然可见。

第二个场景是滚动联动，例如阅读进度条或章节出现。CSS 的 animation-timeline 很方便，但需要用 @supports 包住。未支持的浏览器也必须能阅读内容，不能把信息只藏在动画里。

.scroll-progress {
  position: fixed;
  inset: 0 auto auto 0;
  z-index: 20;
  width: 100%;
  height: 3px;
  transform-origin: left;
  transform: scaleX(0);
  background: var(--color-accent, #2563eb);
}

@supports (animation-timeline: scroll()) {
  .scroll-progress {
    animation: progress-grow linear both;
    animation-timeline: scroll();
  }
}

@keyframes progress-grow {
  to {
    transform: scaleX(1);
  }
}

.reveal {
  opacity: 1;
  transform: none;
}

@supports (animation-timeline: view()) {
  .reveal {
    opacity: 0;
    transform: translateY(16px);
    animation: reveal-up 1ms linear both;
    animation-timeline: view();
    animation-range: entry 10% cover 30%;
  }
}

@keyframes reveal-up {
  to {
    opacity: 1;
    transform: translateY(0);
  }
}

第三个场景是骨架屏和加载状态。骨架屏能告诉用户页面正在加载，但强烈的 shimmer 循环会让等待感更明显。加载超过几秒时，应加入状态文字、重试或取消入口。

第四个场景是 SaaS 后台的操作反馈：保存成功、筛选应用、项目移动、错误面板打开。这类动画应该短而克制，因为用户会反复使用这些界面。

支持 reduced motion，并学会不动画

prefers-reduced-motion 能读取用户希望减少动态效果的设置。对一些用户来说，强烈运动会带来不适或分散注意力，所以生产代码必须尊重它。官方说明见 MDN 的 prefers-reduced-motion。

@media (prefers-reduced-motion: reduce) {
  *,
  *::before,
  *::after {
    scroll-behavior: auto !important;
    animation-duration: 1ms !important;
    animation-delay: 0ms !important;
    animation-iteration-count: 1 !important;
    transition-duration: 1ms !important;
  }

  .scroll-progress {
    animation: none;
    transform: scaleX(1);
  }

  .skeleton {
    animation: none;
    background-image: none;
  }
}

也有很多不该动画的地方：支付确认、法律说明、关键表单错误、长文章正文、密集数据表、每天打开很多次的菜单。在这些场景里，稳定和即时反馈比“有趣”更重要。

让 Claude Code 像审查者一样工作

不要只让 Claude Code “加动画”，要让它找风险。下面的提示可以直接复制使用：

Review and improve the CSS animation implementation for this UI.

Requirements:
- Use transition for simple hover/focus/open states.
- Use keyframes only when intermediate timing matters.
- Animate transform and opacity first; avoid top, left, width, height, and margin animations.
- Add design tokens for duration, easing, and distance.
- Respect prefers-reduced-motion.
- Keep content visible when scroll-linked animation is unsupported.
- Do not animate critical form errors, payment confirmation, or long reading content.

Return:
1. Risky selectors and why they are risky.
2. A corrected CSS/React implementation.
3. Manual and Playwright checks to verify overflow and reduced motion.

这样 Claude Code 会更容易发现 layout thrash、无限循环、过度使用 will-change、缺少 fallback、忽略用户动态偏好等问题。

用 Playwright 做可视化检查

动画问题通常是视觉问题，只靠单元测试不够。可以用 Playwright 检查横向溢出、内容是否可见，以及 reduced motion 下动画是否被关闭。

import { expect, test } from "@playwright/test";

test("animated page has no horizontal overflow", async ({ page }) => {
  await page.goto("/animation-demo");
  const overflow = await page.evaluate(() => {
    return document.documentElement.scrollWidth > window.innerWidth;
  });
  expect(overflow).toBe(false);
});

test("reduced motion keeps content visible", async ({ browser }) => {
  const context = await browser.newContext({ reducedMotion: "reduce" });
  const page = await context.newPage();
  await page.goto("/animation-demo");

  await expect(page.locator(".reveal").first()).toBeVisible();
  await expect(page.locator(".skeleton").first()).toHaveCSS("animation-name", "none");

  await context.close();
});

高风险页面还可以加桌面和移动截图对比。测试不能替代设计判断，但能尽早发现内容隐藏、横向滚动、减少动态设置失效等发布问题。

总结与下一步

生产级 CSS 动画从意图开始：简单状态用 transition，时间轴动作使用 keyframes，移动和显示优先用 transform 与 opacity，统一参数放进设计令牌，并为 reduced motion 和浏览器不支持的情况准备 fallback。Claude Code 最适合在这些约束明确时发挥作用。

下一步可以选择一个现有卡片列表或 CTA 区块，把本文的令牌、入口动画、reduced motion 规则和 Playwright 检查加进去。需要更系统的实现审查流程，可以查看训练与咨询。

实际验证结果：把动画限制在 transform 和 opacity 后，页面没有出现横向溢出；在 Playwright 的 reduced motion 环境中，.reveal 内容保持可见，骨架屏动画也被关闭。强 shimmer 在后台界面里显得累赘，因此更适合改成静态占位。