Honors prefers-reduced-motion and explicit user settings by disabling non-essential animation, preserving essential feedback, and documenting per-pattern motion tiers in a testable matrix.
Package status: AI-assisted reference package. Static package validation has passed; implementation scenarios remain not run and human domain review is required before stable adoption.
Decision
Classify every motion pattern as decorative or essential, honor prefers-reduced-motion: reduce and an optional in-app override, and apply zero-duration or fade-only substitutes from motion-matrix.yaml for decorative motion while preserving accessible loading and focus feedback.
Scope
- OS media-query detection, in-app motion preference, and CSS or framework hooks that apply reduced tiers.
- Catalog of UI patterns with full-motion and reduced-motion implementations.
- Autoplaying loops, parallax, route transitions, modal enter animations, and theme swaps.
- CI enforcement that new animations must be registered in the matrix.
Outside this block
- Video captions, audio descriptions, or seizure-triggering flash limits beyond motion substitution.
- WCAG certification claims; this block supports design decisions aligned with WAI guidance.
- Game or immersive 3D experiences with distinct motion requirements.
Contract
- When reduced motion is active, decorative patterns in the matrix use their reduced substitute or are disabled entirely; parallax and large spatial translations are off by default.
- Essential patterns retain perceptible feedback without vestibular triggers: loading states may use subtle opacity change, not continuous rotation at high speed.
- Autoplaying animated content stops within the profile
autoplay_stop_sla_mswhen reduced motion activates mid-session; static first slide remains afterward. - In-app override to full motion is explicit opt-in and persists separately from OS preference when storage is available.
- Unlisted animations fail CI until classified with tier, full-motion spec, and reduced substitute in
motion-matrix.yaml. - Theme or mode swaps use zero transition duration when reduced motion is active.
- System mode follows OS preference changes live without requiring reload.
Implementation guidance
- Centralize motion tokens or utility classes that read a root
motion-reducedclass set by media query and user setting. - Prefer CSS
@media (prefers-reduced-motion: reduce)with a class override for in-app choice. - Document each pattern once in the matrix; link Storybook or component docs to matrix IDs.
- Pair with dark-mode theme contract for instant color swaps under reduced motion.
Failure handling and safeguards
- If preference storage is corrupt, default to system detection rather than assuming full motion.
- If a third-party embed ignores reduced motion, sandbox or replace with static preview and surface a settings link.
- If disabling animation breaks layout measurements, fix layout without relying on motion completion events.
- Do not use reduced motion as an excuse to remove required focus indicators or loading affordances.
Verification and operations
- Run automated checks that components reference matrix IDs and that reduced CSS bundles contain zero translate animations for decorative tiers.
- Sample manual tests with OS reduced motion enabled on macOS, Windows, and one mobile platform.
- Track override adoption rate and CI failures for unlisted animations each sprint.
Adoption assumptions
- Names and values in
example.yamlandmotion-matrix.yamlare an adoption profile, not universal defaults. - Teams classify product-specific patterns and keep the matrix current as UI evolves.