Motion recipes
How to animate Lily components in your own CSS without costing anyone access. Lily's
headless components never move on their own (AGENTS/accessibility.md); motion is a choice your stylesheet makes, so these recipes are CSS and a few lines
of script, not components. Each one names the WCAG criteria it keeps, and each has a prefers-reduced-motion fallback. The SvelteKit examples app shows all five
at /motion-recipes, checked by e2e/motion-recipes.spec.ts with reduced motion emulated. Source: spec/lessons/magicui.
Rules every recipe follows
- Motion is opt in, never opt out. Write animations inside
@media (prefers-reduced-motion: no-preference), so a browser or user that asks for less motion gets none by default, and an old browser gets the still version. - Reduced motion is not no information. The still version says everything the moving one does.
- Anything that moves for more than five seconds can be paused with a real control, not only by hovering (WCAG 2.2.2).
- Hover and focus parity. An effect shown on hover is shown on keyboard
focus too (
:hover, :focus-visible, or:focus-withinfor a group), or it is decoration only and carries no information or action (WCAG 2.1.1, 1.4.13). - Never hide content to reveal it. Content waiting to animate in is still in the page, in the accessibility tree, readable and at full contrast; motion changes how it arrives, not whether it is there (WCAG 1.3.1, 1.4.3, 2.4.7).
- Copies are hidden once. A repeated copy made for a visual loop is
aria-hidden="true"andinert, so it is neither read twice nor reachable by Tab. - Animated text keeps its real text. The value at rest is real text in the DOM; a live region announces only the value it lands on (the animated-text rule in AGENTS/accessibility.md).
Marquee
A strip of items that scrolls on its own: logos, partners, headlines. Lily has no marquee component (spec/lessons/magicui item 1 is a maintainer decision); this is the CSS-only version.
<section
class="marquee"
aria-label="Our partners"
>
<button
type="button"
class="marquee-pause"
aria-pressed="false"
>
Pause the partner list
</button>
<div class="marquee-track">
<ul class="marquee-list">
<li>North Clinic</li>
<li>South Clinic</li>
<li>East Clinic</li>
</ul>
<ul
class="marquee-list"
aria-hidden="true"
inert
>
<li>North Clinic</li>
<li>South Clinic</li>
<li>East Clinic</li>
</ul>
</div>
</section>
/* Still (reduced motion, or paused): the items wrap and the copy is not drawn, so nothing is clipped. */
.marquee-list {
display: flex;
flex-wrap: wrap;
}
.marquee-list[aria-hidden="true"] {
display: none;
}
@media (prefers-reduced-motion: no-preference) {
.marquee:not([data-paused]) {
overflow: hidden;
}
.marquee:not([data-paused]) .marquee-track {
display: flex;
inline-size: max-content;
animation: marquee 30s linear infinite;
}
.marquee:not([data-paused]) .marquee-list {
flex-wrap: nowrap;
}
.marquee:not([data-paused]) .marquee-list[aria-hidden="true"] {
display: flex;
}
.marquee:hover .marquee-track,
.marquee:focus-within .marquee-track {
animation-play-state: paused;
}
}
@keyframes marquee {
to {
transform: translateX(-50%);
}
}
/* Right to left: scroll the other way. */
:dir(rtl) .marquee-track {
animation-direction: reverse;
}
const marquee = document.querySelector(".marquee");
const pause = marquee.querySelector(".marquee-pause");
pause.addEventListener("click", () => {
const paused = pause.getAttribute("aria-pressed") !== "true";
pause.setAttribute("aria-pressed", String(paused));
marquee.toggleAttribute("data-paused", paused);
});
- The first list is the content; the copy exists only to close the loop, so it is
aria-hiddenandinert. - The pause button is a real toggle (
aria-pressed) with the consumer's words, and it stops the motion for good, not only while the pointer rests on it (WCAG 2.2.2). Hover and focus both pause it (parity). - Under reduced motion, or once paused, the strip is still and its items wrap, so none is clipped at 320px (WCAG 1.4.10). Keeps: 1.4.10, 2.1.1, 2.2.2, 2.3.3.
A number that changes
A statistic whose value changes (a count of waiting patients, a total). The value
is real text; the motion is a short slide of the new value, and the announcement is the final
value, once.
<div class="statistic">
<span class="statistic-label">Waiting</span>
<span
class="statistic-value"
aria-live="polite"
data-changed
>13</span
>
</div>
@media (prefers-reduced-motion: no-preference) {
.statistic-value[data-changed] {
animation: statistic-arrive 300ms ease-out;
}
}
@keyframes statistic-arrive {
from {
transform: translateY(0.4em);
opacity: 0.4;
}
}
function setValue(element, text) {
element.removeAttribute("data-changed");
void element.offsetWidth; // restart the animation
element.textContent = text; // the real value, at once
element.setAttribute("data-changed", "");
}
- The text changes immediately; only its arrival moves, so a screen reader and a copy-paste always get the true value.
- Do not count up through every number in between: each one would be announced, or would
be wrong for a moment. If you want rolling digits, draw them in an
aria-hiddencopy that is removed when it settles. - Under reduced motion the number simply changes. Keeps: 2.3.3, 4.1.3.
Ease in on scroll, without hiding or fading anything
Content that rises into place as it scrolls into view (the "fade-in" of most libraries, without the fade). It is never removed, made invisible or faded first, so a reader, a search engine and a keyboard user who tabs to it see it at once, at full contrast.
@media (prefers-reduced-motion: no-preference) {
@supports (animation-timeline: view()) {
.ease-in {
animation: ease-in linear both;
animation-timeline: view();
animation-range: entry 0% cover 25%;
}
}
}
.ease-in:focus-within {
animation: none;
}
@keyframes ease-in {
from {
transform: translateY(1.5rem);
}
}
- Move, do not fade. Text below full opacity fails contrast for as long as it is faint: body text faded to 0.35 measures about 2:1, and a link stays under 4.5:1 even at 0.75 (WCAG 1.4.3). If you must fade, fade a decorative layer, never the text.
- Never start from
visibility: hiddenordisplay: none, and apply the start state by the animation alone, so without support, without CSS or under reduced motion the content is simply there. - A focused element inside is shown at once (
:focus-within), so keyboard focus is never on something still moving (WCAG 2.4.7). - No script, no IntersectionObserver class that a failed script would leave hidden. Keeps: 1.3.1, 1.4.3, 2.3.3, 2.4.7.
Theme change transition
A short cross-fade when the theme changes, using the View Transition API. theme-picker will offer this as the opt-in viewTransition option (tasks.md P32-T4); until then, wrap your own apply step:
function applyTheme(apply) {
const reduce = matchMedia("(prefers-reduced-motion: reduce)").matches;
if (document.startViewTransition && !reduce) document.startViewTransition(apply);
else apply();
}
::view-transition-old(root),
::view-transition-new(root) {
animation-duration: 200ms;
}
@media (prefers-reduced-motion: reduce) {
::view-transition-group(*),
::view-transition-old(*),
::view-transition-new(*) {
animation: none;
}
}
- The theme is applied the same way either way; the transition only changes how the switch looks.
- Without the API, or under reduced motion, the theme changes at once. Keeps: 2.3.3.
Terminal transcript
A record of commands and their output, as on an install page. Input lines are <kbd>, output lines <samp>, and the prompt is CSS-generated text, so copying
a command never copies the prompt.
<pre
class="code-block terminal"
tabindex="0"
aria-label="Installing the Svelte catalog"
><code><kbd>npm install @lilydesignsystem/svelte-headless</kbd>
<samp>added 1 package in 2s</samp></code></pre>
.terminal kbd::before {
content: "$ " / "";
}
content: "$ " / ""gives the prompt an empty alternative text, so a screen reader does not read "dollar" before every command.- The block scrolls inside itself (
tabindex="0", a name), not the page (WCAG 1.4.10). - No typing effect. If you add one, it follows the animated-text rule: the full command is
real text at rest, the effect is an
aria-hiddencopy, and under reduced motion there is none. Keeps: 1.3.1, 1.4.10, 2.3.3.
Sources
- WCAG 2.2: Pause, Stop, Hide (2.2.2), Animation from Interactions (2.3.3), Content on Hover or Focus (1.4.13)
- MDN: prefers-reduced-motion, scroll-driven animations, View Transition API
- Magic UI (the components these recipes answer), reviewed in spec/lessons/magicui