You own a design system whose components animate. How do you make reduced-motion support a structural guarantee rather than per-component discipline, and how do you let a user override the operating-system preference from inside the app?

## The failure this is solving Per-component discipline does not survive a growing team. The reduced-motion query is easy to forget, invisible in review unless the reviewer turns the OS setting on, and impossible to see in a screenshot. Any policy whose enforcement mechanism is "remember to add the block" degrades to partial coverage within a few quarters. The design-system answer is to move the decision to a single place that every component passes through anyway. ## One gate, consumed everywhere Define motion durations as custom properties, and forbid raw durations in component CSS. ```css :root { --motion-duration-fast: 120ms; --motion-duration-base: 240ms; --motion-ease: cubic-bezier(0.2, 0, 0, 1); } @media (prefers-reduced-motion: reduce) { :root { --motion-duration-fast: 0.01ms; --motion-duration-base: 0.01ms; } } .ds-dialog { transition: opacity var(--motion-duration-base) var(--motion-ease); } ``` This works because custom properties inherit and resolve at computed-value time: redefining them on the root changes what every descendant's `transition` computes to, with no per-component code. A component author who writes the token gets correct behaviour without knowing the preference exists, and a component author who writes `240ms` directly is caught by a lint rule rather than by an accessibility audit six months later. The near-zero rather than zero value carries the same reasoning as the classic reset: transitions and animations still complete, so `transitionend` and `animationend` still fire and any control flow hanging off them keeps working. ## Tokens are not enough on their own Durations are the easy half. Two further layers are needed. **Distance and property choice.** A slide that takes 0.01ms is not a slide, so duration tokens do neutralise movement — but they neutralise it by making it instant, which discards the feedback. Where a component's motion carried meaning, it should degrade to a crossfade rather than to nothing, and that decision is per component. A workable rule: the token layer guarantees safety, and components that care add an explicit `reduce` block to substitute rather than flatten. Safety is structural; quality is opt-in. **Motion outside CSS durations.** Autoplaying video, animated images, canvas loops, timer-driven carousels, and anything animated from script are untouched by a duration token. Those need the preference consulted at their own layer, and the design system should provide the primitive rather than leaving each product to reinvent it. ## The in-app override Users ask for a product-level control for good reasons: they want motion off on this site only, or they are on a shared or managed machine where they cannot change the OS setting, or the OS one is on for another reason entirely. The system preference is the default; the app setting is an explicit override of that default. ```css :root { --motion-duration-base: 240ms; } @media (prefers-reduced-motion: reduce) { :root { --motion-duration-base: 0.01ms; } } /* app setting wins over the system default, in both directions */ :root[data-motion="reduced"] { --motion-duration-base: 0.01ms; } :root[data-motion="full"] { --motion-duration-base: 240ms; } ``` The precedence here is not luck. A media query contributes nothing to specificity, so the rule inside it has the specificity of `:root` alone; `:root[data-motion="reduced"]` adds an attribute selector and therefore outranks it no matter where the blocks sit in the file. That is what makes the override robust against someone later reordering the stylesheet. The attribute itself is set by application code from the user's stored choice, which is outside CSS's remit. The genuinely contested design decision is whether to offer "full" at all. Letting an app setting turn motion *back on* for someone whose OS says reduce is arguably overriding an accessibility signal — the defensible position is that an explicit, per-site, opt-in choice by the user themselves is a preference, not a bypass, provided it is never the default and never remembered across a change in the system setting without them noticing. Some teams offer only "system default" and "reduced" for that reason. Be ready to argue your side. ## Making it stick - **Lint the raw value.** A rule that rejects time units in component CSS outside the token file turns policy into a build failure. - **Keep a global floor.** The universal near-zero reset still earns its place for third-party stylesheets and anything predating the tokens. - **Default the toggle to system.** Three states — system, reduced, full — with system as the shipped default, so doing nothing inherits the OS answer. - **Test it as a state.** Treat reduced motion like a theme: a snapshot dimension in visual tests, a row in the component checklist, part of the review template. - **Watch adoption, not intentions.** The measurable thing is the count of raw durations outside the token layer; if it is not trending to zero the policy is not real.