Communitygithub.com

无障碍动画(减少动效,分级处理)

用于处理用户提出的“尊重 prefers-reduced-motion”、“减少动效”、“让动画无障碍”、“修复前庭/晕动症问题”、“添加 useReducedMotion 钩子”、“为 GSAP / Framer Motion / Lenis 进行减少动效适配”或“满足 WCAG 2.3.3 / C39”等需求。提供分级(非全有或全无)的减少动效模式,涵盖 CSS 与 JS。

无障碍动画(减少动效,分级处理) 是什么?

该技能旨在帮助开发者以优雅降级的方式处理 `prefers-reduced-motion: reduce` 媒体查询,而非粗暴地禁止所有动画。核心思想是分级处理:将动画按触发前庭反应的风险分为三级——Tier 1(完全移除,如视差、大幅滑动、旋转缩放)、Tier 2(柔化缩短,如用 ≤200ms 的淡入淡出代替位移)、Tier 3(始终保留,如透明度变化、焦点环、加载指示器)。支持 CSS 层(通过媒体查询覆盖)和 JS 层(通过 `matchMedia` 动态控制 GSAP、Framer Motion、Lenis 等库),并提供 React 的 `useReducedMotion` 钩子。技能还包含 WCAG 映射、验证方法(包括截图对比工具)和常见陷阱说明。适用于 Web UI 动画的开发与审核,可有效预防晕动症并满足 WCAG 无障碍标准。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/dheerazsah/video-editor-skills/tree/HEAD/skills/accessible-animation

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

无障碍动画(减少动效,分级处理) 是做什么的?

尊重 prefers-reduced-motion: reduce,将其视为优雅降级,而非简单关闭。操作系统级设置(macOS: 系统设置 > 辅助功能 > 显示 > 减少动效;Windows: 设置 > 辅助功能 > 视觉效果 > 动画效果;iOS/Android 类似)表明前庭触发的动效会导致恶心、头晕或偏头痛。正确的做法是移除危险的动效,同时保留方向提示。

使用场景

在 Web UI 中添加或审核动画时、用户报告晕动症或 WCAG 发现时、或将动画库(GSAP、Framer Motion、Lenis 平滑滚动、Anime.js、CSS 关键帧)集成到无障碍产品中时使用。

核心原则:分级处理,而非全部禁用

移除所有动画是一个常见的过度纠正。没有过渡的即时状态变化可能更令人迷失方向(元素瞬间位移),并且会移除有用的视觉提示(焦点环、表示进度的加载旋转器)。将每个动画分为三个层级:

  • Tier 1 — 完全移除(前庭触发因素)。 视差;跨视口的大面积滑动/平移;大元素的缩放/放大;3D 旋转和旋转;自动播放的轮播和跑马灯;平滑滚动劫持(Lenis/Locomotive);滚动劫持的固定场景;运动路径动画;任何移动屏幕大部分区域或暗示深度/自我运动的动画。
  • Tier 2 — 柔化/缩短。 用短时的透明度淡入淡出(≤200ms)代替位移。减少距离和持续时间。保留过渡的事实(这样元素就不会瞬间位移),但移除位移效果。将 600ms 的从左侧滑入替换为 150ms 的交叉淡入淡出。
  • Tier 3 — 始终保留。 透明度淡入淡出、颜色/背景过渡、焦点环过渡、加载指示器以及对于传达含义至关重要的动画(WCAG 允许必要的动画)。这些很少会触发前庭反应,因为它们不暗示自我运动。

CSS 层:媒体查询分级

将动效作为默认值编写,然后在减少动效查询下进行覆盖。优先使用全局安全网加上针对性覆盖。

/* 全局安全网:中和过度的动画,但不要盲目设置为 0s,
   这可能会破坏等待 transitionend/animationend 的 JS,请使用 0.01ms。 */
@media (prefers-reduced-motion: reduce) {
  *,
  *::before,
  *::after {
    animation-duration: 0.01ms !important;
    animation-iteration-count: 1 !important;   /* 停止无限旋转/跑马灯 */
    transition-duration: 0.01ms !important;
    scroll-behavior: auto !important;          /* 禁用平滑滚动 */
  }
}

全局网络是后备。在其上叠加有意的、分级的覆盖,以便 Tier 3 动效得以保留:

.card {
  transition: transform 400ms ease, opacity 400ms ease, background-color 200ms ease;
}

@media (prefers-reduced-motion: reduce) {
  .card {
    /* Tier 2:移除 transform(移动),保留 opacity + color(Tier 3) */
    transition: opacity 150ms ease, background-color 150ms ease;
  }
  .parallax-layer { transform: none !important; }        /* Tier 1:移除 */
  .hero-zoom      { animation: none !important; }        /* Tier 1:移除 */
}

使用肯定查询 (prefers-reduced-motion: no-preference) 来选择性地引入动效,这对于复杂效果是最安全的模式:

.hero { opacity: 1; } /* 默认可见、静态 */
@media (prefers-reduced-motion: no-preference) {
  .hero { animation: zoom-in 1.2s ease both; } /* 仅在允许时动画 */
}

JS 层:matchMedia 分级

CSS 无法控制 JS 驱动的动画(GSAP 时间线、Framer 的 animate、Canvas/WebGL、Lenis)。通过 matchMedia 读取相同的信号,并响应实时变化(用户无需重新加载即可切换操作系统设置)。

const REDUCE_QUERY = '(prefers-reduced-motion: reduce)';

export function prefersReducedMotion() {
  return typeof window !== 'undefined'
    && window.matchMedia
    && window.matchMedia(REDUCE_QUERY).matches;
}

// 实时更新:监听以便操作系统设置切换时立即生效。
export function onReducedMotionChange(cb) {
  const mq = window.matchMedia(REDUCE_QUERY);
  const handler = (e) => cb(e.matches);
  mq.addEventListener('change', handler);          // 现代 API
  return () => mq.removeEventListener('change', handler);
}

库适配,应用为一个可复用的层

// GSAP — 使用 matchMedia():GSAP 在变化时会恢复条件性设置。
import gsap from 'gsap';
const mm = gsap.matchMedia();
mm.add({
  motionOK: '(prefers-reduced-motion: no-preference)',
  motionReduce: '(prefers-reduced-motion: reduce)',
}, (ctx) => {
  const { motionOK } = ctx.conditions;
  if (motionOK) {
    gsap.from('.hero', { y: 80, opacity: 0, duration: 1 });   // Tier 1 移动
  } else {
    gsap.from('.hero', { opacity: 0, duration: 0.15 });        // Tier 2 淡入
  }
});

// Lenis 平滑滚动 — 减少动效时完全不初始化。
import Lenis from 'lenis';
let lenis = null;
if (!prefersReducedMotion()) {
  lenis = new Lenis();
  const raf = (t) => { lenis.raf(t); requestAnimationFrame(raf); };
  requestAnimationFrame(raf);
}

React:一个 useReducedMotion 钩子

import { useState, useEffect } from 'react';

export function useReducedMotion() {
  const query = '(prefers-reduced-motion: reduce)';
  const get = () =>
    typeof window !== 'undefined' && window.matchMedia
      ? window.matchMedia(query).matches
      : false;
  const [reduced, setReduced] = useState(get);

  useEffect(() => {
    const mq = window.matchMedia(query);
    const onChange = () => setReduced(mq.matches);
    onChange();                                   // 水合后同步
    mq.addEventListener('change', onChange);
    return () => mq.removeEventListener('change', onChange);
  }, []);

  return reduced;
}
// Framer Motion 有自己的 useReducedMotion();上面的钩子也同样适用。
import { motion } from 'framer-motion';
function Card() {
  const reduced = useReducedMotion();
  return (
    <motion.div
      initial={reduced ? { opacity: 0 } : { opacity: 0, y: 40 }}
      animate={{ opacity: 1, y: 0 }}
      transition={{ duration: reduced ? 0.15 : 0.5 }}
    />
  );
}

初始化 SSR 渲染状态为 false(动效),并在 useEffect 中重新同步以避免水合不匹配;操作系统的值仅在客户端可知。

WCAG 映射

  • 2.3.3 交互触发的动画 (AAA)。 由交互(滚动、悬停)触发的动效应可禁用,除非必要。尊重 prefers-reduced-motion 是标准技术。
  • C39(CSS 技术)。 使用 prefers-reduced-motion 查询来阻止动效。这是命名的充分技术。
  • 2.2.2 暂停、停止、隐藏 (A)。 任何持续时间超过 5 秒的自动播放动效应提供暂停/停止控件。无论媒体查询如何,自动轮播和跑马灯都违反此条——请一并提供控件。

交付与验证(独立 HTML)

打包辅助脚本(scripts/):scripts/seek-shot.sh anim.html 0 1.5 3 冻结 ?t=N 测试架并截取每个时刻的截图;scripts/contact-sheet.sh sheet.png frame-*.png 将它们平铺以便快速审视。参见 scripts/README.md。

对于自包含的演示,交付物是一个可以直接在浏览器中打开的 HTML 文件——标记、CSS 以及任何 JS(GSAP/来自 CDN 的 matchMedia)内联,无需构建步骤。对于这个技能,验证是关键:您必须截取正常和减少动效两种路径的屏幕截图,并确认分级是正确的。

输出合约:

  • 一个 .html 文件,包含完整的动效及其分级减少动效覆盖(用于 JS 驱动动效的 CSS 查询 + matchMedia/gsap.matchMedia())。
  • 一个用于冻结帧的搜索控制架,以及一种强制采用减少动效代码路径以进行截图的方法。

搜索控制架 — 冻结帧,强制偏好设置。 ?t=N 冻结时间线;?reduce=1 即使操作系统设置关闭也强制采用减少路径(无法通过 JS 切换 CSS,因此需查询你用来限制 JS 的相同标志,并使用模拟的 OS/浏览器偏好设置对 CSS 层进行截图):

<script>
  const q = new URLSearchParams(location.search);
  const reduce = q.get("reduce") === "1"
    || window.matchMedia("(prefers-reduced-motion: reduce)").matches;
  // 根据 `reduce` 条件性地构建动效(Tier-1 移除,Tier-2 柔化,Tier-3 保留)
  const t = q.get("t");
  if (t !== null) { tl.pause(); tl.seek(parseFloat(t)); }      // GSAP;CSS:el.style.animationDelay=(-t)+"s"; playState="paused"
  window.__ready = true;
</script>

验证循环 — 对两种状态截图: 捕获正常路径和减少路径,分别在动画中间,并确认 Tier-1 动效已消失,Tier-2 是短暂的淡入淡出,Tier-3 得以保留。为 CSS 层模拟偏好设置(Playwright --reduced-motion=reduce;代理的浏览器工具也可以模拟它):

npx playwright screenshot --wait-for-timeout=500 "file://$PWD/demo.html?t=0.6" normal.png
npx playwright screenshot --reduced-motion=reduce --wait-for-timeout=500 "file://$PWD/demo.html?t=0.6&reduce=1" reduced.png

完成前检查:

  1. 独立打开 — 无控制台错误,CDN(如有)正常加载。
  2. 冻结 + ?reduce=1(以及 --reduced-motion=reduce)能可靠地执行两条代码路径。
  3. 在动画中间对两种状态截图 — 正常状态看起来有意图,减少状态则剥离 Tier-1/柔化 Tier-2。
  4. prefers-reduced-motion 作为分级处理,而非关闭开关 — 无元素瞬间位移,保留 Tier-3 淡入淡出/焦点环/旋转器;任何超过 5 秒的自动动效仍然具有暂停控件(2.2.2)。
  5. 两条路径中的缓动效果都是有意图的 — 无意外 linear,持续时间合理(减少状态的淡入淡出 ≤200ms,0.01ms 而非 0s)。

快速参考

动效类型层级减少动效行为
视差 / 深度1移除 (transform: none)
大幅滑动 / 平移1移除或替换为淡入淡出
缩放(大幅)1移除
旋转 / 3D 旋转1移除 (animation: none)
自动轮播 / 跑马灯1停止 + 提供暂停控件 (2.2.2)
平滑滚动 (Lenis)1不初始化
小幅滑动 / 弹入2交叉淡入淡出 ≤200ms
透明度淡入淡出3保留(若过长则缩短)
颜色 / 焦点环过渡3保留
加载旋转器3保留(必要的反馈)

常见陷阱

  • animation-duration: 0s 可能破坏依赖 animationend/transitionend 的代码;使用 0.01ms 以便事件仍然触发。
  • 仅靠全局 * 重置会过度移除 Tier 3 动效;始终叠加有意的覆盖。
  • 忘记 animation-iteration-count: 1 会导致无限旋转以接近零的持续时间运行(CPU 空转,仍在动画中)。
  • 没有媒体查询覆盖 JS/Canvas/WebGL — 使用 matchMedia 进行门控,否则循环不会停止。
  • 切换操作系统设置不会触发页面重新加载;没有 change 监听器,页面将保持过时的状态。
  • SSR:在渲染期间读取 matchMedia 会抛出异常或不匹配;默认设置为动效,并在 effect 中同步。
  • 即使在减少动效关闭时,自动播放的动效也需要一个可见的暂停控件(2.2.2 是 A 级)。

参考文件

  • references/patterns.md — 完整的 GSAP matchMedia 分解、Framer Motion MotionConfig、Lenis 实时切换启动/停止、可复用的 animateWithMotionPreference 包装器、带暂停控件的跑马灯、以及层级分类审核清单。

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

相关技能