Add web animation skills (iart-ai/web-animation-skills)
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01GYeokZtSmqg42ZGWsLXX2C
This commit is contained in:
42 files changed
+4170
No files matched your search
Whitespace-only changes.
@@ -0,0 +1,231 @@
|
||||
---
|
||||
name: accessible-animation
|
||||
description: This skill should be used when the user asks to "respect prefers-reduced-motion", "honor reduced motion", "make my animations accessible", "fix vestibular / motion-sickness issues", "add a useReducedMotion hook", "gate GSAP / Framer Motion / Lenis for reduced motion", or "meet WCAG 2.3.3 / C39". Provides tiered (not all-or-nothing) reduced-motion patterns in CSS and JS.
|
||||
version: 0.1.0
|
||||
---
|
||||
|
||||
# Accessible Animation (Reduced Motion, Tiered)
|
||||
|
||||
Honor `prefers-reduced-motion: reduce` as a *graceful degradation*, not a kill switch. The OS-level setting (macOS: Settings > Accessibility > Display > Reduce motion; Windows: Settings > Accessibility > Visual effects > Animation effects; iOS/Android equivalents) signals that *vestibular-triggering* motion causes nausea, dizziness, or migraines. The correct response is to remove the dangerous motion while keeping orientation cues.
|
||||
|
||||
## When to use
|
||||
|
||||
Use when adding or auditing animation in a web UI, when a user reports motion sickness or WCAG findings, or when integrating animation libraries (GSAP, Framer Motion, Lenis smooth scroll, Anime.js, CSS keyframes) into an accessible product.
|
||||
|
||||
## The core principle: tier motion, do not nuke it
|
||||
|
||||
Removing *all* animation is a common over-correction. An instant state change with no transition can be more disorienting (elements teleport) and removes useful affordances (focus rings, loading spinners that communicate progress). Sort every animation into three tiers:
|
||||
|
||||
- **Tier 1 — Remove entirely (vestibular triggers).** Parallax; large-area slides/translates across the viewport; scale/zoom of large elements; 3D rotation and spin; continuous auto-playing carousels and marquees; smooth-scroll hijacking (Lenis/Locomotive); scroll-jacked pinned scenes; motion-path animation; anything that moves a large portion of the screen or implies depth/self-motion.
|
||||
- **Tier 2 — Soften / shorten.** Replace movement with a short opacity fade (≤200ms). Reduce distance and duration. Keep the *fact* of a transition (so elements don't teleport) but strip the displacement. Replace a 600ms slide-in-from-left with a 150ms cross-fade.
|
||||
- **Tier 3 — Always keep.** Opacity fades, color/background transitions, focus-ring transitions, loading indicators, and motion that is *essential* to meaning (WCAG allows essential animation). These rarely trigger vestibular responses because they imply no self-motion.
|
||||
|
||||
## CSS layer: media-query gating
|
||||
|
||||
Write motion as the default, then override under the reduce query. Prefer a global safety net plus targeted overrides.
|
||||
|
||||
```css
|
||||
/* Global safety net: neutralize runaway motion but DO NOT set 0s blindly,
|
||||
which can break JS that waits for transitionend/animationend. Use 0.01ms. */
|
||||
@media (prefers-reduced-motion: reduce) {
|
||||
*,
|
||||
*::before,
|
||||
*::after {
|
||||
animation-duration: 0.01ms !important;
|
||||
animation-iteration-count: 1 !important; /* stop infinite spins/marquees */
|
||||
transition-duration: 0.01ms !important;
|
||||
scroll-behavior: auto !important; /* kill smooth scroll */
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The global net is a backstop. Layer *intentional, tiered* overrides on top so Tier 3 motion survives:
|
||||
|
||||
```css
|
||||
.card {
|
||||
transition: transform 400ms ease, opacity 400ms ease, background-color 200ms ease;
|
||||
}
|
||||
|
||||
@media (prefers-reduced-motion: reduce) {
|
||||
.card {
|
||||
/* Tier 2: drop the transform (movement), keep opacity + color (Tier 3) */
|
||||
transition: opacity 150ms ease, background-color 150ms ease;
|
||||
}
|
||||
.parallax-layer { transform: none !important; } /* Tier 1: remove */
|
||||
.hero-zoom { animation: none !important; } /* Tier 1: remove */
|
||||
}
|
||||
```
|
||||
|
||||
Use the *positive* query `(prefers-reduced-motion: no-preference)` to opt motion IN, which is the safest pattern for elaborate effects:
|
||||
|
||||
```css
|
||||
.hero { opacity: 1; } /* visible, static by default */
|
||||
@media (prefers-reduced-motion: no-preference) {
|
||||
.hero { animation: zoom-in 1.2s ease both; } /* only animate when allowed */
|
||||
}
|
||||
```
|
||||
|
||||
## JS layer: matchMedia gating
|
||||
|
||||
CSS cannot gate JS-driven animation (GSAP timelines, Framer's `animate`, canvas/WebGL, Lenis). Read the same signal via `matchMedia` and react to live changes (users toggle the OS setting without reloading).
|
||||
|
||||
```js
|
||||
const REDUCE_QUERY = '(prefers-reduced-motion: reduce)';
|
||||
|
||||
export function prefersReducedMotion() {
|
||||
return typeof window !== 'undefined'
|
||||
&& window.matchMedia
|
||||
&& window.matchMedia(REDUCE_QUERY).matches;
|
||||
}
|
||||
|
||||
// Live updates: listen so toggling the OS setting takes effect immediately.
|
||||
export function onReducedMotionChange(cb) {
|
||||
const mq = window.matchMedia(REDUCE_QUERY);
|
||||
const handler = (e) => cb(e.matches);
|
||||
mq.addEventListener('change', handler); // modern API
|
||||
return () => mq.removeEventListener('change', handler);
|
||||
}
|
||||
```
|
||||
|
||||
### Library gating, applied as one reusable layer
|
||||
|
||||
```js
|
||||
// GSAP — use matchMedia(): GSAP reverts conditional setups on change.
|
||||
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 move
|
||||
} else {
|
||||
gsap.from('.hero', { opacity: 0, duration: 0.15 }); // Tier 2 fade
|
||||
}
|
||||
});
|
||||
|
||||
// Lenis smooth scroll — do not instantiate at all when reduced.
|
||||
import Lenis from 'lenis';
|
||||
let lenis = null;
|
||||
if (!prefersReducedMotion()) {
|
||||
lenis = new Lenis();
|
||||
const raf = (t) => { lenis.raf(t); requestAnimationFrame(raf); };
|
||||
requestAnimationFrame(raf);
|
||||
}
|
||||
```
|
||||
|
||||
## React: a `useReducedMotion` hook
|
||||
|
||||
```jsx
|
||||
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(); // sync after hydration
|
||||
mq.addEventListener('change', onChange);
|
||||
return () => mq.removeEventListener('change', onChange);
|
||||
}, []);
|
||||
|
||||
return reduced;
|
||||
}
|
||||
```
|
||||
|
||||
```jsx
|
||||
// Framer Motion has its own useReducedMotion(); the hook above also works.
|
||||
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 }}
|
||||
/>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
Initialize SSR-rendered state to `false` (motion) and re-sync in `useEffect` to avoid a hydration mismatch; the OS value is only known client-side.
|
||||
|
||||
## WCAG mapping
|
||||
|
||||
- **2.3.3 Animation from Interactions (AAA).** Motion triggered by interaction (scroll, hover) must be disable-able unless essential. Honoring `prefers-reduced-motion` is the standard technique.
|
||||
- **C39 (CSS technique).** Use the `prefers-reduced-motion` query to prevent motion. This is the named sufficient technique.
|
||||
- **2.2.2 Pause, Stop, Hide (A).** Any auto-playing motion lasting >5s must offer pause/stop. Auto-carousels and marquees fail this regardless of the media query — give a control too.
|
||||
|
||||
## Deliver & verify (standalone HTML)
|
||||
|
||||
> **Packaged helper** (`scripts/`): `scripts/seek-shot.sh anim.html 0 1.5 3` freezes the `?t=N` harness and screenshots each moment; `scripts/contact-sheet.sh sheet.png frame-*.png` tiles them for one-glance review. See `scripts/README.md`.
|
||||
|
||||
For a self-contained demo the deliverable is **one HTML file that opens directly in a browser** — markup, CSS, and any JS (GSAP/`matchMedia` from CDN) inline, no build step. For *this* skill the verification is the point: you must screenshot **both** the normal and the reduced-motion path and confirm the tiering is correct.
|
||||
|
||||
**Output contract:**
|
||||
- One `.html` file with the full motion AND its tiered reduced-motion overrides (CSS query + `matchMedia`/`gsap.matchMedia()` for JS-driven motion).
|
||||
- A seek harness to freeze a frame, plus a way to force the reduced-motion code path for screenshots.
|
||||
|
||||
**Seek harness — freeze a frame, force the preference.** `?t=N` freezes the timeline; `?reduce=1` forces the reduced path even when the OS setting is off (CSS can't be toggled from JS, so query the same flag you gate JS on, and screenshot with the OS/browser preference emulated for the CSS layer):
|
||||
|
||||
```html
|
||||
<script>
|
||||
const q = new URLSearchParams(location.search);
|
||||
const reduce = q.get("reduce") === "1"
|
||||
|| window.matchMedia("(prefers-reduced-motion: reduce)").matches;
|
||||
// build motion conditionally on `reduce` (Tier-1 removed, Tier-2 softened, Tier-3 kept)
|
||||
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>
|
||||
```
|
||||
|
||||
**Verify loop — screenshot BOTH states:** capture the normal path AND the reduced path, mid-animation each, and confirm Tier-1 motion is gone, Tier-2 is a short fade, Tier-3 survives. Emulate the preference for the CSS layer (Playwright `--reduced-motion=reduce`; the agent's browser tool can emulate it too):
|
||||
|
||||
```bash
|
||||
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
|
||||
```
|
||||
|
||||
**Before you finish:**
|
||||
1. Opens standalone — no console errors, CDN (if any) loads.
|
||||
2. The freeze + `?reduce=1` (and `--reduced-motion=reduce`) reliably exercises both code paths.
|
||||
3. Screenshotted in BOTH states, mid-animation — normal looks intentional, reduced strips Tier-1/softens Tier-2.
|
||||
4. `prefers-reduced-motion` honored as *tiering*, not a kill switch — no teleporting, Tier-3 fades/focus rings/spinners kept; any >5s auto-motion still has a pause control (2.2.2).
|
||||
5. Easing is intentional in both paths — no accidental `linear`, durations sane (reduced fades ≤200ms, `0.01ms` not `0s`).
|
||||
|
||||
## Quick reference
|
||||
|
||||
| Motion type | Tier | Reduced behavior |
|
||||
|---|---|---|
|
||||
| Parallax / depth | 1 | Remove (`transform: none`) |
|
||||
| Large slide / translate | 1 | Remove or replace with fade |
|
||||
| Scale / zoom (large) | 1 | Remove |
|
||||
| Spin / 3D rotate | 1 | Remove (`animation: none`) |
|
||||
| Auto carousel / marquee | 1 | Stop + provide pause control (2.2.2) |
|
||||
| Smooth-scroll (Lenis) | 1 | Don't instantiate |
|
||||
| Small slide / pop-in | 2 | Cross-fade ≤200ms |
|
||||
| Opacity fade | 3 | Keep (shorten if long) |
|
||||
| Color / focus-ring transition | 3 | Keep |
|
||||
| Loading spinner | 3 | Keep (essential feedback) |
|
||||
|
||||
## Gotchas
|
||||
|
||||
- `animation-duration: 0s` can break code waiting on `animationend`/`transitionend`; use `0.01ms` so the event still fires.
|
||||
- The global `*` reset alone over-removes Tier 3 motion; always layer intentional overrides.
|
||||
- Forgetting `animation-iteration-count: 1` leaves infinite spins running at near-zero duration (CPU churn, still animating).
|
||||
- No media query covers JS/canvas/WebGL — gate those with `matchMedia` or the loop never stops.
|
||||
- Toggling the OS setting fires no page reload; without a `change` listener the page keeps its stale state.
|
||||
- SSR: reading `matchMedia` during render throws or mismatches; default to motion and sync in an effect.
|
||||
- Auto-playing motion needs a visible pause control even when reduced-motion is off (2.2.2 is Level A).
|
||||
|
||||
## Reference files
|
||||
|
||||
- `references/patterns.md` — Full GSAP `matchMedia` teardown, Framer Motion `MotionConfig`, Lenis start/stop on live toggle, a reusable `animateWithMotionPreference` wrapper, marquee with pause control, and a tier-classification audit checklist.
|
||||
@@ -0,0 +1,196 @@
|
||||
# Reduced Motion — Detailed Patterns
|
||||
|
||||
## Reusable wrapper: animate with motion preference
|
||||
|
||||
A single helper that picks a "full" or "reduced" variant and stays live-reactive.
|
||||
|
||||
```js
|
||||
const REDUCE = '(prefers-reduced-motion: reduce)';
|
||||
|
||||
export function createMotionController() {
|
||||
const mq = window.matchMedia(REDUCE);
|
||||
const listeners = new Set();
|
||||
mq.addEventListener('change', () => listeners.forEach((fn) => fn(mq.matches)));
|
||||
|
||||
return {
|
||||
get reduced() { return mq.matches; },
|
||||
subscribe(fn) { listeners.add(fn); fn(mq.matches); return () => listeners.delete(fn); },
|
||||
// Pick a variant object: { full, reduced }
|
||||
pick(variants) { return mq.matches ? variants.reduced : variants.full; },
|
||||
};
|
||||
}
|
||||
|
||||
// Usage
|
||||
const motion = createMotionController();
|
||||
const opts = motion.pick({
|
||||
full: { translateY: ['40px', '0'], opacity: [0, 1], duration: 500 },
|
||||
reduced: { opacity: [0, 1], duration: 150 },
|
||||
});
|
||||
```
|
||||
|
||||
## GSAP: full matchMedia with teardown
|
||||
|
||||
`gsap.matchMedia()` automatically reverts (kills tweens, restores inline styles) when a condition stops matching, so toggling the OS setting cleans up correctly.
|
||||
|
||||
```js
|
||||
import gsap from 'gsap';
|
||||
import { ScrollTrigger } from 'gsap/ScrollTrigger';
|
||||
gsap.registerPlugin(ScrollTrigger);
|
||||
|
||||
const mm = gsap.matchMedia();
|
||||
|
||||
mm.add({
|
||||
motionOK: '(prefers-reduced-motion: no-preference)',
|
||||
motionReduce: '(prefers-reduced-motion: reduce)',
|
||||
}, (ctx) => {
|
||||
const { motionOK } = ctx.conditions;
|
||||
|
||||
if (motionOK) {
|
||||
// Tier 1 parallax — only when allowed
|
||||
gsap.to('.parallax-layer', {
|
||||
yPercent: -30,
|
||||
ease: 'none',
|
||||
scrollTrigger: { trigger: '.section', scrub: true },
|
||||
});
|
||||
gsap.from('.card', {
|
||||
y: 60, opacity: 0, stagger: 0.1,
|
||||
scrollTrigger: { trigger: '.grid', start: 'top 80%' },
|
||||
});
|
||||
} else {
|
||||
// Reduced: no parallax at all; cards cross-fade in place (Tier 2)
|
||||
gsap.from('.card', {
|
||||
opacity: 0, duration: 0.15, stagger: 0.03,
|
||||
scrollTrigger: { trigger: '.grid', start: 'top 80%' },
|
||||
});
|
||||
}
|
||||
|
||||
return () => { /* optional extra cleanup; mm reverts tweens automatically */ };
|
||||
});
|
||||
|
||||
// Tear everything down (e.g. SPA route change)
|
||||
// mm.revert();
|
||||
```
|
||||
|
||||
## Framer Motion: MotionConfig for app-wide reduction
|
||||
|
||||
`MotionConfig reducedMotion="user"` makes every child `motion` component automatically drop transform/layout animations while keeping opacity. Set it once at the root.
|
||||
|
||||
```jsx
|
||||
import { MotionConfig, motion } from 'framer-motion';
|
||||
|
||||
export function App() {
|
||||
return (
|
||||
<MotionConfig reducedMotion="user">
|
||||
{/* All descendant motion components honor the OS setting */}
|
||||
<motion.section
|
||||
initial={{ opacity: 0, y: 80 }} // y is auto-dropped when reduced
|
||||
animate={{ opacity: 1, y: 0 }}
|
||||
transition={{ duration: 0.6 }}
|
||||
/>
|
||||
</MotionConfig>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
For per-component control, Framer's own hook:
|
||||
|
||||
```jsx
|
||||
import { useReducedMotion } from 'framer-motion';
|
||||
|
||||
function Hero() {
|
||||
const reduced = useReducedMotion();
|
||||
const variants = reduced
|
||||
? { hidden: { opacity: 0 }, show: { opacity: 1, transition: { duration: 0.15 } } }
|
||||
: { hidden: { opacity: 0, scale: 0.9 }, show: { opacity: 1, scale: 1, transition: { duration: 0.8 } } };
|
||||
return <motion.div variants={variants} initial="hidden" animate="show" />;
|
||||
}
|
||||
```
|
||||
|
||||
## Lenis: start/stop on live toggle
|
||||
|
||||
Lenis hijacks scroll (Tier 1). Destroy it when reduced motion turns on, recreate when it turns off.
|
||||
|
||||
```js
|
||||
import Lenis from 'lenis';
|
||||
|
||||
let lenis = null;
|
||||
let rafId = null;
|
||||
|
||||
function startLenis() {
|
||||
if (lenis) return;
|
||||
lenis = new Lenis({ smoothWheel: true });
|
||||
const loop = (t) => { lenis.raf(t); rafId = requestAnimationFrame(loop); };
|
||||
rafId = requestAnimationFrame(loop);
|
||||
}
|
||||
function stopLenis() {
|
||||
if (!lenis) return;
|
||||
cancelAnimationFrame(rafId);
|
||||
lenis.destroy();
|
||||
lenis = null;
|
||||
// Restore native scroll so the page is still usable
|
||||
document.documentElement.style.removeProperty('scroll-behavior');
|
||||
}
|
||||
|
||||
const mq = window.matchMedia('(prefers-reduced-motion: reduce)');
|
||||
function sync() { mq.matches ? stopLenis() : startLenis(); }
|
||||
mq.addEventListener('change', sync);
|
||||
sync();
|
||||
```
|
||||
|
||||
## Auto-carousel / marquee with a pause control (WCAG 2.2.2)
|
||||
|
||||
Auto-playing motion longer than 5s needs a pause/stop control regardless of the media query. Reduced-motion users get it stopped by default; everyone gets the control.
|
||||
|
||||
```html
|
||||
<div class="marquee" data-playing="true">
|
||||
<button class="marquee__toggle" aria-pressed="false">Pause</button>
|
||||
<ul class="marquee__track"><!-- items --></ul>
|
||||
</div>
|
||||
```
|
||||
|
||||
```css
|
||||
.marquee__track { animation: scroll-left 20s linear infinite; }
|
||||
.marquee[data-playing="false"] .marquee__track { animation-play-state: paused; }
|
||||
@media (prefers-reduced-motion: reduce) {
|
||||
.marquee__track { animation-play-state: paused; } /* paused by default */
|
||||
}
|
||||
@keyframes scroll-left { to { transform: translateX(-50%); } }
|
||||
```
|
||||
|
||||
```js
|
||||
const root = document.querySelector('.marquee');
|
||||
const btn = root.querySelector('.marquee__toggle');
|
||||
// Respect the OS setting for the initial state
|
||||
if (window.matchMedia('(prefers-reduced-motion: reduce)').matches) {
|
||||
root.dataset.playing = 'false';
|
||||
btn.textContent = 'Play';
|
||||
btn.setAttribute('aria-pressed', 'true');
|
||||
}
|
||||
btn.addEventListener('click', () => {
|
||||
const playing = root.dataset.playing === 'true';
|
||||
root.dataset.playing = String(!playing);
|
||||
btn.textContent = playing ? 'Play' : 'Pause';
|
||||
btn.setAttribute('aria-pressed', String(playing));
|
||||
});
|
||||
```
|
||||
|
||||
## Tier classification audit checklist
|
||||
|
||||
For each animation in the codebase, ask in order:
|
||||
|
||||
1. Is it essential to meaning (e.g. a progress bar, a diagram step)? -> Tier 3, keep.
|
||||
2. Does a large area move, scale, spin, or imply depth/self-motion (parallax, zoom hero, slide-over)? -> Tier 1, remove under reduce.
|
||||
3. Is it a small entrance with displacement (pop-in, slide-up)? -> Tier 2, replace displacement with a ≤200ms opacity fade.
|
||||
4. Is it only opacity/color/focus? -> Tier 3, keep (shorten if >300ms).
|
||||
5. Does it auto-play >5s (carousel, marquee, looping video bg)? -> Add a pause control (2.2.2) on top of any tier handling.
|
||||
|
||||
## Testing
|
||||
|
||||
- macOS: System Settings > Accessibility > Display > Reduce motion.
|
||||
- Windows 11: Settings > Accessibility > Visual effects > Animation effects (off).
|
||||
- Chrome DevTools: Rendering panel > "Emulate CSS media feature prefers-reduced-motion".
|
||||
- Verify the `change` listener: toggle the OS setting with the page open and confirm motion stops without reload.
|
||||
- Confirm `transitionend`/`animationend`-dependent flows still complete (the `0.01ms` rule).
|
||||
|
||||
---
|
||||
Honor prefers-reduced-motion at every tier and motion stays inclusive by default. Built by **[iart.ai](https://iart.ai/?utm_source=github&utm_medium=readme&utm_campaign=web-animation-skills&utm_content=skill_footer&utm_term=accessible-animation)** — the AI motion agent for editable, on-brand motion graphics.
|
||||
Reference in new issue
Block a user