Skip to main content

Rule 25 - CSS: Animations

Motion and transition rules.

Rules​

25.1. All animations and transitions MUST be optional and accessible.

25.2. Non-essential animations MUST be disabled when prefers-reduced-motion: reduce is active. The preferred mechanism is the --option-animations multiplier (see Rule 23.17) which handles this automatically via calc(). Per-component @media (prefers-reduced-motion) blocks SHOULD only be used when the option multiplier cannot express the fallback (e.g. swapping an animation for a static indicator). A block whose only declarations clear transitions (transition: none, a zero transition-duration) restates the multiplier and MUST NOT exist in a sheet whose transitions all run through it; where a transition the multiplier does not scale remains, the block is its fallback and stays until the transition is scaled.

/* Preferred: option multiplier handles reduced motion automatically */
button.btn {
transition-duration: calc(0.2s * var(--option-animations));
}

/* Fallback: per-component media query when a static swap is needed */
.spinner {
animation: spin 1s linear infinite;
}
@media (prefers-reduced-motion: reduce) {
.spinner {
animation: none;
}
}

25.3. transition SHOULD be preferred over animation - transitions are simpler, interruptible, and easier to disable.

/* Preferred */
.btn {
transition:
color 0.3s ease,
background 0.3s ease;
}

/* Avoid for simple state changes */
@keyframes fadeIn {
from {
opacity: 0;
}
to {
opacity: 1;
}
}
.btn:hover {
animation: fadeIn 0.3s;
}

25.4. Implementations SHOULD use shared transition tokens for consistent timing.

Example: transition: color calc(var(--btn-transition-duration) * var(--option-animations));, with --btn-transition-duration: var(--component-transition-duration); declared in the sidecar.

25.5. No animation MUST be REQUIRED for a component to function. Content MUST remain accessible and the component operable with all motion removed.

25.6. Animations MUST NOT cover more than 1/3 of the screen area, MUST NOT flash more than 3 times per second, and MUST NOT run indefinitely without user control (loading spinners excepted).

25.7. Loading indicators MAY use motion only when it conveys active progress. Under reduced motion, a static indicator SHOULD be preferred.


Enforced by

25.2 by yarn cli 25 (findRedundantReducedMotionBlocks in packages/cli/src/rules/25.js). 25.1, 25.3-25.7 are review only. See enforcement.md.