Seenry Motion
Motion exists to explain a change: where something came from, what the input did, what state the interface is in now. Build every animation through the sequence below, in order; steps 1 and 2 decide whether any code gets written at all.
Make the call and state it in one line; do not offer a menu of motion options. Extend the project's existing motion tokens and components instead of adding a parallel set.
The build sequence
1. Should it animate at all? Decide by frequency.
| How often people see it | Decision |
|---|---|
| 100+ times a day (command menu, keyboard shortcuts, list navigation with arrows) | No animation. Instant. |
| Tens of times a day (hover, tabs, toggles) | ≤150ms on opacity and color only, or nothing |
| Occasionally (menus, dialogs, sheets, toasts) | Standard motion from the table below |
| Rarely (onboarding, first success, empty-to-full moments) | Room for character |
Keyboard-triggered actions never wait on animation. If the gate says no, say so and ship the instant state change.
2. Name the purpose in one word: feedback, orientation (where it came from or went), state, continuity (avoid a jarring jump), explanation (marketing and onboarding only), or delight (rare moments only). No purpose, no animation. Data people are reading never moves for style.
3. Pick the cheapest tool that works.
| Need | Tool |
|---|---|
| Hover, press, color, class or attribute toggle | CSS transition |
Entrance on mount, exit before display: none, native <dialog> and popover | CSS transition + @starting-style + allow-discrete |
Height to auto | interpolate-size: allow-keywords, or the grid 0fr → 1fr track |
| Route changes, list → detail, morphing indicators | View Transitions API |
| Scroll-linked effects | animation-timeline: view() / scroll() |
| Programmatic, cancellable, no library | Web Animations (element.animate) |
| Springs with velocity, layout animation, gestures, presence in React | Motion (motion.dev) |
| A whole component (toast, drawer, command menu, select) | A maintained library, see libraries |
4. Pick the properties. translate, scale, rotate, opacity, clip-path, filter only. Never enter from scale(0): start at 0.95–0.97 with opacity 0. Popovers scale from their trigger (transform-origin on the trigger side); dialogs scale from center. Percent translates (translate: 0 100%) move by the element's own size.
5. Pick the curve and duration, or a spring.
| Motion | Duration | Easing |
|---|---|---|
| Press feedback | 100–160ms | --ease-out |
| Tooltip, small popover | 120–200ms | --ease-out |
| Menu, dropdown, select | 150–250ms | --ease-out |
| Dialog | 200–250ms | --ease-out |
| Sheet, drawer | 350–500ms | --ease-drawer |
| Element moving across the screen, morphs | 250–400ms | --ease-in-out |
| Color, background, border on hover | 150ms | ease |
| Progress, marquee, hold-to-confirm fill | as long as the work | linear |
--ease-out: cubic-bezier(0.23, 1, 0.32, 1), --ease-in-out: cubic-bezier(0.77, 0, 0.175, 1), --ease-drawer: cubic-bezier(0.32, 0.72, 0, 1). Never ease-in on interface motion: it delays exactly the moment people are watching. Prefer product UI under 300ms; longer sheet travel needs a reason. Exits are often ~20–30% faster than entrances, unless preserving a direct manipulation or spatial relationship warrants the same clock. Use a spring for anything the user drags, flicks or can reverse mid-way: Motion {type: "spring", duration: 0.5, bounce: 0.2} (bounce 0 for product UI, ≤0.3 for playful), or the CSS linear() springs in recipes.
6. Plan interruption and exit. Prefer CSS transitions for reversible property changes because they retarget from the current value. When geometry or choreography needs WAAPI, capture the current rendered state, cancel or retarget owned animations, and guard stale completion. A second input reverses or replaces the old request rather than queuing behind it. Publish the new logical state immediately; a separate presentation state may keep an exit painted.
Refine the interrupted change. Use these checks where they fit the component. They are design heuristics, not a guaranteed judge score. Try repeated inputs during entry and exit, including 50–150ms apart; record actual timings when making timing claims.
- Retain continuity and semantics. Related tabs, filters or status states can share one grid cell (
display:grid,grid-area:1/1) and transition opacity or a small translate. Keep inactive content out of the focus order and accessibility tree; mounted does not mean interactive. A quick outgoing phase (roughly 65–90ms) and incoming 120–160ms can be a starting point, not a required recipe. Unmount or hide only when the current transition permits it; a stale completion must never hide a newer state. Explicitly cancellable WAAPI and guarded native-dialog exits are valid alternatives. - Keep the result understandable. Avoid accidental blank intervals or unreadable competing text. Choose overlap, a short crossfade or an instant replacement based on content; a whole-label endpoint fade may be safer than moving text through artwork. Preserve an appropriate static cue while motion is unavailable or reduced. Inspect actual readability rather than using an opacity threshold as proof.
- One copy of a travelling thing. When a title, avatar or cover moves to a new place, avoid visible duplicate paint. Hide the destination until the traveller lands, then retire the temporary copy. Trace the text against the artwork and moving shell; an unclipped endpoint does not prove a readable path.
- The label agrees with its result. A label such as “Mark paid” becoming “Paid” follows the same accepted application state as its result. Reserve its footprint when useful and prevent stale text or focusable duplicate labels. Do not delay a real success state just to finish decoration.
- Sequences can be cancelled. Typing demos, staged reveals and replays share an owner for pending steps. Pause, reversal and new input cancel obsolete work and retarget visible motion from its current state. A stale timeout must not resume a paused sequence or overwrite newer content.
- Release finished animations. Establish the settled state through CSS or committed styles, then release finite owned WAAPI animations when appropriate.
fill:forwardsmust not keep overriding later state changes. Check for unexpected animations after the interaction settles, while allowing a purposeful ongoing loading indicator until its work ends. - Each move explains a relationship. Menus grow from their trigger, panels from their edge, and related content moves consistently with navigation. Use the duration ranges above as starting points; keep perceived response immediate and justify longer travel. Test interruption and reduced motion rather than treating a fixed duration as proof of quality.
Reaching 9. On the motion judge, 7 is correct but generic, 8 is clearly premium and 9 is distinctive at the level of Apple or Linear. Rounds stall at 7–8 for the same few reasons. Handle all of them before spending a run:
- One component at a time. Judge each component alone with
--labels "<Row>"until it scores 9, and keep the best version of each. A catalog's overall follows its weakest rows, so patching many rows at once never moves it, and a change that lowers a row is reverted even when the judge suggested it. - Apply every fix, not only the headline one. Small items that recur (hover, press and close-control feedback) hold
statesat 7 round after round.--prev <last motion.json>lists the criteria that did not rise and the interactions asked to fix again;check.mjspasses it automatically. - A problem that returns after its fix is structural. Retiming cannot fix a path that crosses. Shared elements keep their relative arrangement between states: a title below its cover stays below it in the detail view, so neither passes through the other.
- No empty frames. At every filmed moment (30–320ms) the changed region shows real content. A shell carries its content as it grows; a streaming answer grows from its first words. Never show a blank answer box or a skeleton that waits and then dissolves.
- One crafted idea per component. What persists travels and what is new is born from its cause. A fade, a 4px translate and a label swap score 7.
- Close where it opened. A surface that opens from a control closes from the same spot: the control becomes (or is replaced in place by) its close, so the hand never travels. It need not keep the same colour; it keeps the place and the size.
- A single run is not a score. One judge run (itself a median of three) moves by a point on unchanged code. Accept a 9 only when two separate runs both reach it, and compare versions on the same number of runs.
7. Ship reduced motion and input gating with it. Under prefers-reduced-motion: reduce, remove movement, parallax, blur and loops; keep short opacity changes that aid understanding. Gate hover motion with @media (hover: hover) and (pointer: fine). Every animated state change also leaves a static cue (label, icon, color) for when motion does not run.
Recipes
Start from recipes for press feedback, menus and popovers, tooltips, dialogs, sheets, toasts, accordions, staggered entrances, tab indicators, page and shared-element transitions, scroll reveals, icon swaps, number changes, hold-to-confirm, drag-to-dismiss (with velocity projection and rubber banding), crossfade masking, theme switching and first-render suppression. The native-CSS recipes are exercised in Chromium by the package tests.
Runnable assets
| Requested change | Focused route |
|---|---|
| Action menu or short status label | Original action menu, status switch and product transitions. If the menu is asked to animate open and closed, preserve its surface through the closing phase; conditional unmount on close skips that phase. For a status transition, move the text in a reserved slot; a plain text replacement or dot-color change alone is incomplete. The application owns the real action. |
| In-flow disclosure or changing geometry | Original expanding card, geometry helper and surface patterns. Preserve focus and retarget from current geometry. |
| Focused modal task | Original modal surface and surface patterns. Use a native dialog for top-layer and focus behavior; allow the exit to finish before closing, and make reversal cancel the pending close. |
| Changing number or icon | Number transitions and adapters. For a small integer count, prefer the original count-pop helper over rebuilding digit semantics. Keep one real accessible value; do not hide every digit and put aria-label on a plain <strong>. A digit transition needs per-place motion; keep units anchored. |
| Live voice input or output | Original voice presence accepts application-owned state and a normalized audio level. Keep controls and announcements in the DOM; a generated demo signal is not microphone activity. |
| Loading or process presence | Original signal field, boundary trace and loading patterns. Animation time is not progress. |
| Decoded image or expressive material | Original image reveal, reflective solid and rim surfaces, pointer tilt, surface effects and expressive effects. Keep useful content while a replacement loads; use reflection and tilt only where the material has a purpose. |
| Designing any new interactive component (brief, state graph, motion score, input contract, checklist) | Interaction craft |
| Toast or banner stack | Feedback patterns and original notification reducer. Remove overflow from active state before its exit; test the fourth event in a three-item stack. |
| Occasional completed milestone | Original confirmation burst. Record success in application state first, then play the finite decoration; the settled result must remain visible after it clears. |
| Selected tabs or ordered page change | Original selection surface for a shared highlight and directional stage for related views; the application owns selection, panels, route and history. Use navigation patterns for other structures. |
| Scroll or a coordinated system | Scroll choreography, worked scores, system choreography and the motion index. |
Select only the guide and helper needed for this change. The bundled original assets are reusable starting points, not automatic substitutes for a named source component or proof of fidelity to it. Keep licenses with any copied third-party runtime; the original Seenry assets use the repository's MIT license.
Never ship
| Never | Instead |
|---|---|
| Animation on a 100+/day or keyboard-driven action | Instant change |
transition: all | Name the properties |
Entrance from scale(0) | scale: 0.96 + opacity: 0 |
ease-in on UI | --ease-out |
Default ease/ease-out on a deliberate entrance | The custom curves above |
| Product UI motion over 300ms without a reason | 150–250ms |
| Popover scaling from its center | transform-origin at the trigger |
| Uncontrolled keyframes on re-triggered interactions | Retargetable transitions or explicitly cancellable WAAPI |
Animating width, height, top, left, margin | Transforms; grid-track or interpolate-size for height |
Ungated :hover movement | (hover: hover) and (pointer: fine) |
| No reduced-motion variant | Opacity-only or instant |
| A long list entering item by item | 30–50ms stagger capped at ~300ms total, or none |
| Motion as the only sign of a state change | A static cue as well |
Output
Write the code, then report in a few lines: the gate result (frequency and purpose, or why nothing animates), the ingredients (tool, properties, duration, curve or spring), and what was checked (normal speed, 10% speed in DevTools Animations, rapid repeat, reversal, keyboard, reduced motion, phone).
Research the observed behavior
When matching a supplied reference, inspect playback at normal speed and useful intermediate frames, not only endpoints. Motion research explains recordings, Seenry MCP, creator studies and source limits; load it only when research is needed. A static image cannot establish timing, interruption or keyboard behavior. Without playback, implement a proposed treatment and test it locally.
Recorded phase check: Match source checkpoints to the running browser animation. State jumps verify endpoints, not timing. See motion reconstruction.
Verify
Verify the behaviors you changed using the interaction verification checklist. A small fix needs its affected states and a regression check, not a new whole-site benchmark. Inspect normal-speed playback and useful slow-motion frames; check internal text/control fit as well as document overflow. During reversal, assert the final logical and accessible state and inspect the actual moving layers, not just their fixed container.
When the sibling seenry skill runtime and authorized model access are available, resolve ../seenry/scripts/motion_judge.mjs from this skill's installed directory and run it with Node against the page. Do not assume the caller's working directory is the skill directory. If the runtime is absent, report that check unavailable. Its configured bar is 9 overall with no violations; use its findings to inspect the relevant interaction. Keep that judgment separate from functional and rendered checks; an unavailable judge or missing recording is unverified, never a pass. Try relevant keyboard, narrow-width and reduced-motion states. For gestures, use touch emulation and a real phone when available, and report which you actually tested.
For deeper mechanics read motion craft, interaction anatomy, product transitions, scroll choreography, surface effects and number transitions. Use seenry for overall interface direction and material.