Communitygithub.com

accessible-animation

用於處理優先尊重「prefers-reduced-motion」、製作無障礙動畫、解決前庭/暈動症問題、新增 useReducedMotion hook、限制 GSAP/Framer Motion/Lenis 的動畫,或滿足 WCAG 2.3.3/C39 規範。提供分級(非全有全無)的減少動畫模式,涵蓋 CSS 與 JS。

accessible-animation 是什麼?

這項技能提供了一套全面的分級減少動畫(Tiered Reduced Motion)方法,用於尊重使用者的作業系統偏好設定(prefers-reduced-motion: reduce),而非簡單地「全部關閉」。它明確區分三種動畫層級:第一級(前庭觸發)應完全移除(如視差、大型平移、縮放、旋轉、自動輪播);第二級應弱化/縮短(如用 ≤200ms 淡入取代 600ms 滑入);第三級則應保留(如透明度變化、顏色轉場、焦點環)。此技能支援在 CSS 中使用媒體查詢進行門控,並在 JavaScript 中透過 matchMedia 動態回應即時變更。它也涵蓋了 React 的 useReducedMotion hook,以及對 GSAP(使用 matchMedia)、Framer Motion 和 Lenis 平滑滾動等函式庫的實作。此外,它還依照 WCAG 2.3.3、C39 和 2.2.2 規範進行設計,並提供驗證流程(含強制 reduce 路徑的時間軸控制工具),確保動畫在兩種狀態下都能正確分級。

相容平台~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 視為一種「優雅降級」(graceful degradation),而不是一個「終止開關」。作業系統層級的設定(macOS:設定 > 輔助使用 > 顯示器 > 減少動畫;Windows:設定 > 輔助使用 > 視覺效果 > 動畫效果;iOS/Android 類似選項)表示:觸發前庭的動畫會導致噁心、頭暈或偏頭痛。正確的應對方式是移除危險的動畫,同時保留方向感提示。

使用時機

在 Web UI 中加入或審查動畫時、使用者回報暈動症或 WCAG 檢測結果時、或將動畫函式庫(GSAP、Framer Motion、Lenis 平滑滾動、Anime.js、CSS 關鍵影格)整合到無障礙產品中時使用。

核心原則:分級動畫,不要全面消除

消除「所有」動畫是一種常見的矯枉過正。完全沒有轉場的瞬間狀態變更可能更加令人困惑(元素憑空消失),並會移除有用的視覺提示(如焦點環、顯示進度的載入旋轉器)。將每個動畫分為三個層級:

  • 第一級 — 完全移除(前庭觸發)。 視差;大面積的跨視窗滑動/平移;大型元素的縮放;3D 旋轉與旋轉;持續自動播放的輪播圖與跑馬燈;平滑滾動劫持(Lenis/Locomotive);滾動觸發的釘選場景;運動路徑動畫;任何使螢幕大面積移動或暗示深度/自我運動的效果。
  • 第二級 — 弱化 / 縮短。 以短時間的透明度淡入(≤200ms)取代移動。減少距離與持續時間。保留轉場的「事實」(讓元素不會憑空消失),但去除位移。將 600ms 從左側滑入取代為 150ms 的交叉淡入。
  • 第三級 — 永遠保留。 透明度淡入、顏色/背景轉場、焦點環轉場、載入指示器,以及對意義「至關重要」的動畫(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;          /* 關閉平滑滾動 */
  }
}

全域網路是一個備用方案。在上層疊加「有意的、分級的」覆寫,讓第三級動畫得以保留:

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

@media (prefers-reduced-motion: reduce) {
  .card {
    /* 第二級:移除 transform(移動),保留 opacity + color(第三級) */
    transition: opacity 150ms ease, background-color 150ms ease;
  }
  .parallax-layer { transform: none !important; }        /* 第一級:移除 */
  .hero-zoom      { animation: none !important; }        /* 第一級:移除 */
}

使用「正面」查詢 (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 讀取相同的信號,並即時回應變更(使用者在無需重新載入的情況下切換 OS 設定)。

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

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

// 即時更新:監聽,讓切換 OS 設定的效果立即生效。
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 });   // 第一級移動
  } else {
    gsap.from('.hero', { opacity: 0, duration: 0.15 });        // 第二級淡入
  }
});

// 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 hook

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();上面的 hook 也適用。
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 中重新同步,以避免水合不匹配;OS 的值只能在客戶端得知。

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/matchMedia 從 CDN 載入)都內嵌,無需建置步驟。對於「此」技能來說,驗證是關鍵:你必須截取「正常」和「減少動畫」兩種路徑的螢幕截圖,並確認分級正確。

輸出合約:

  • 一個 .html 檔案,包含完整的動畫及其分級減少動畫的覆寫(CSS 查詢 + 用於 JS 驅動動畫的 matchMedia/gsap.matchMedia())。
  • 一個用於凍結影格的控制工具,以及一種強制進入減少動畫程式碼路徑以進行螢幕截圖的方法。

影格控制工具 — 凍結影格,強制偏好。 ?t=N 凍結時間軸;?reduce=1 在 OS 設定關閉時仍強制進入減少動畫路徑(CSS 無法從 JS 切換,因此查詢與 JS 門控相同的標誌,並使用模擬的 OS/瀏覽器偏好進行 CSS 層級的螢幕截圖):

<script>
  const q = new URLSearchParams(location.search);
  const reduce = q.get("reduce") === "1"
    || window.matchMedia("(prefers-reduced-motion: reduce)").matches;
  // 根據 `reduce` 有條件地建立動畫(第一級移除、第二級弱化、第三級保留)
  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>

驗證循環 — 截取兩種狀態的螢幕截圖: 同時捕獲正常路徑和減少動畫路徑,各自在動畫中途,並確認第一級動畫已消失、第二級是短暫淡入、第三級保留。為 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. 在「兩種」狀態下於動畫中途截取螢幕截圖 — 正常看起來有設計感,減少後則移除第一級/弱化第二級。
  4. prefers-reduced-motion 被視為「分級」而非終止開關 — 無元素憑空消失,第三級淡入/焦點環/旋轉器保留;任何超過 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 以便事件仍能觸發。
  • 僅使用全域 * 重置會過度移除第三級動畫;務必疊加有意的覆寫。
  • 忘記 animation-iteration-count: 1 會讓無限旋轉以近乎為零的持續時間運行(CPU 消耗,但仍持續動畫)。
  • 沒有媒體查詢能涵蓋 JS/Canvas/WebGL — 請使用 matchMedia 進行門控,否則迴圈永遠不會停止。
  • 切換 OS 設定不會觸發頁面重新載入;如果沒有 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.

相關技能