# Motionary 17.0.1

> Motionary is a zero-dependency motion library: scroll animations, 200+ presets and 209 animated Web Components (<usa-*>) that work in plain HTML and every framework, plus motionary/runtime — its own tween/timeline engine and format loaders.

Install: `npm i motionary` · CDN: https://unpkg.com/motionary@17/dist/components.umd.js (+ https://unpkg.com/motionary@17/dist/widgets.umd.js for 6.x+ widgets) · Manifest: https://harrisoncn.github.io/Motionary/components.json · Full text: https://harrisoncn.github.io/Motionary/llms-full.txt

Rules for using a component: (1) import its define function from `import.path` and call it once (or load the CDN bundle); (2) if `requires` is non-empty, install / import / register the prerequisites first (see the component's Prerequisites); (3) then use the tag in HTML.

## Runtime modules

- [motionary/runtime](https://github.com/HarrisonCN/Motionary/blob/main/docs/runtime/core.md): Shared ticker (one rAF loop), tween + timeline engine with easing, module registry with clear errors.
- [motionary/runtime/format-css](https://github.com/HarrisonCN/Motionary/blob/main/docs/runtime/format-css.md): Import CSS @keyframes text or live CSSKeyframesRule objects and Web Animations API keyframes (array or property-indexed) into a runtime timeline.
- [motionary/runtime/format-motion](https://github.com/HarrisonCN/Motionary/blob/main/docs/runtime/format-motion.md): Play Motion / Framer-style { initial, animate, transition } JSON (arrays as keyframes, times, repeatType, springs) with the runtime.
- [motionary/runtime/scroll](https://github.com/HarrisonCN/Motionary/blob/main/docs/runtime/scroll.md): Scroll-linked scenes: start / end rules, scrub (direct or smoothed), pin, markers, enter / leave callbacks and per-edge actions for a runtime tween or timeline.
- [motionary/runtime/format-svg](https://github.com/HarrisonCN/Motionary/blob/main/docs/runtime/format-svg.md): Replay SVG SMIL animations (animate, set, animateTransform, animateMotion) on the runtime timeline, morph between any two paths, and measure paths without the DOM.
- [motionary/runtime/text](https://github.com/HarrisonCN/Motionary/blob/main/docs/runtime/text.md): Split text into characters (grapheme-aware), words and lines for animation while keeping it accessible (aria-label with the full text, pieces hidden from assistive tech).
- [motionary/runtime/format-sprite](https://github.com/HarrisonCN/Motionary/blob/main/docs/runtime/format-sprite.md): Play TexturePacker / Aseprite sprite sheets and numbered image sequences on a canvas or an element background, as runtime timelines (scrubbable).
- [motionary/runtime/smooth](https://github.com/HarrisonCN/Motionary/blob/main/docs/runtime/smooth.md): Smooth, inertial wheel scrolling (lerp or fixed-duration glide) for the window or any scroll container, anchor links that glide, off under prefers-reduced-motion; real scroll events keep scroll scenes and observers working.
- [motionary/runtime/format-gif](https://github.com/HarrisonCN/Motionary/blob/main/docs/runtime/format-gif.md): Decode animated GIFs (own LZW decoder, no DOM) into composited RGBA frames and play / scrub / reverse them on a canvas as a runtime timeline.
- [motionary/runtime/format-apng](https://github.com/HarrisonCN/Motionary/blob/main/docs/runtime/format-apng.md): Split animated PNGs into standalone frame PNGs (decoded by the browser), composite them (dispose / blend) and play them on a canvas as a runtime timeline.
- [motionary/runtime/format-webp](https://github.com/HarrisonCN/Motionary/blob/main/docs/runtime/format-webp.md): Split animated WebP files (ANIM / ANMF) into standalone frames (decoded by the browser), composite them (blend / dispose) and play them on a canvas as a runtime timeline.
- [motionary/runtime/gl](https://github.com/HarrisonCN/Motionary/blob/main/docs/runtime/gl.md): A small WebGL2 renderer with its own API: scene graph, camera, lights, box / plane / sphere / torus, PBR-style materials, shader materials, image and video textures, orbit controls — not a Three.js clone.
- [motionary/runtime/format-gltf](https://github.com/HarrisonCN/Motionary/blob/main/docs/runtime/format-gltf.md): Load glTF 2.0 (.gltf with external or data: buffers, .glb) into motionary/runtime/gl nodes: node hierarchy, meshes, PBR metallic-roughness materials, embedded / external images.
- [motionary/runtime/format-obj](https://github.com/HarrisonCN/Motionary/blob/main/docs/runtime/format-obj.md): Load Wavefront OBJ (+ MTL materials and diffuse textures) into motionary/runtime/gl nodes: polygons triangulated, groups, per-material meshes.
- [motionary/runtime/vector](https://github.com/HarrisonCN/Motionary/blob/main/docs/runtime/vector.md): Plays Lottie (bodymovin JSON) and dotLottie (.lottie) files on Canvas 2D with Motionary’s own renderer (no lottie-web code): shapes, gradients, trim paths, masks, track mattes, precomps, images; a runtime timeline you can seek, reverse and scrub.
- [@rive-app/canvas](https://github.com/HarrisonCN/Motionary/blob/main/docs/runtime/rive.md): The official MIT-licensed Rive runtime, used by <usa-rive> to play .riv files (artboards, animations, state machines with inputs). Optional peer dependency: lazy-loaded on first use, never bundled into Motionary.
- [motionary/runtime/physics](https://github.com/HarrisonCN/Motionary/blob/main/docs/runtime/physics.md): A small 2D rigid-body engine written for Motionary (own implementation and API — no Matter.js / Box2D code): circles, boxes and convex polygons, mass from density, restitution, friction, sensors, collision groups, sleeping, distance / spring / pin constraints, pointer drag, a fixed time step on the shared ticker.
- [motionary/runtime/format-scene](https://github.com/HarrisonCN/Motionary/blob/main/docs/runtime/format-scene.md): The versioned motionary-scene@1 format: a JSON description of a 2D physics scene (world, named materials, bodies, constraints, per-body style) — validate, migrate older drafts, load into a physics world and save one back.
- [motionary/runtime/drag-snap](https://github.com/HarrisonCN/Motionary/blob/main/docs/runtime/drag-snap.md): Pointer drag along one axis with velocity tracking, inertial throws, rubber-band edges and spring-animated snap points on the shared ticker — the engine of <usa-snap-carousel>, usable for sheets, sliders and pickers (own implementation).
- [motionary/runtime/gltf-anim](https://github.com/HarrisonCN/Motionary/blob/main/docs/runtime/gltf-anim.md): Plays glTF 2.0 animations on models loaded by motionary/runtime/format-gltf: translation / rotation / scale / weights channels with LINEAR, STEP and CUBICSPLINE samplers, skins (4 joints per vertex) and morph targets, deformed on the CPU and re-uploaded to motionary/runtime/gl (own implementation).
- [motionary/runtime/lottie-state](https://github.com/HarrisonCN/Motionary/blob/main/docs/runtime/lottie-state.md): Resolves Lottie slots with dotLottie themes (Color / Scalar / Vector / Text rules, static or keyframed) and runs a subset of dotLottie state machines (playback states, Event / Numeric / String / Boolean guards, pointer + completion interactions, input / theme / frame actions) for motionary/runtime/vector — own implementation, used by <usa-dotlottie>.
- [motionary/runtime/gltf-decoders](https://github.com/HarrisonCN/Motionary/blob/main/docs/runtime/gltf-decoders.md): Lets motionary/runtime/format-gltf load KHR_draco_mesh_compression meshes and KHR_texture_basisu (KTX2) textures through the official decoders — Google draco3d and the Basis Universal transcoder — registered as lazy loaders; Motionary does not reimplement them.
- [draco3d](https://github.com/HarrisonCN/Motionary/blob/main/docs/runtime/draco3d.md): Google’s official Draco geometry decoder (Apache-2.0, WASM / JS), used by motionary/runtime/gltf-decoders for KHR_draco_mesh_compression meshes. Optional peer dependency: lazy-loaded when the first Draco file is opened, never bundled into Motionary.
- [basis_transcoder.js](https://github.com/HarrisonCN/Motionary/blob/main/docs/runtime/basis-transcoder.md): Binomial’s official Basis Universal transcoder (Apache-2.0, basis_transcoder.js + .wasm from the basis_universal repository), used by motionary/runtime/gltf-decoders for KHR_texture_basisu (KTX2) textures. Optional: lazy-loaded when the first KTX2 texture is decoded, never bundled into Motionary.

## Components

- `<usa-accordion>` (motionary/components/transitions): Smooth expand / collapse for native <details> — semantics, keyboard and find-in-page kept; no wrapper elements.
- `<usa-acrylic>` (motionary/components/background): Windows Fluent materials: frosted acrylic (backdrop blur + tint + noise) and mica. Solid fallback when transparency is reduced.
- `<usa-add-to-cart>` (motionary/components/widgets): 7.3: a buy button — the product photo flies on an arc into the cart, the cart badge bumps and the button morphs into a ✓ “Added” state. Works with <usa-cart-dra
- `<usa-ambient>` (motionary/components/page): A fixed page-wide layer: drifting particles, falling snow, twinkling stars, film grain or a gradient that shifts with scroll.
- `<usa-anim-icon>` (motionary/components/svg): Stroke icons that move: the bell rings, the heart beats, the check draws, the gear turns. Hover, click, in view or loop; decorative unless labelled.
- `<usa-audio>` (motionary/components/effects): 5.6: <usa-audio> renders a toggle (a user gesture starts Web Audio), detects beats and plays any registered effect on children with data-usa-beat="effect". JS: 
- `<usa-aurora>` (motionary/components/background): A slow drifting gradient mesh behind its content. Transforms only, paused off-screen, still under reduced motion.
- `<usa-auto-animate>` (motionary/components/layout): Wrap a list or grid: items that are added fade in, removed ones fade out in place, and everything else glides to its new spot — on sort, filter or resize. Zero 
- `<usa-auto-skeleton>` (motionary/components/page): Set loading and every heading, paragraph, image and button inside becomes a shimmering placeholder of its own size — no extra markup.
- `<usa-avatar-stack>` (motionary/components/ui): Overlapping avatars that spread apart with a spring on hover; extras collapse into “+N”.
- `<usa-back-to-top>` (motionary/components/page): Appears after you scroll, shows reading progress as a ring and springs the page back up, then moves focus to the top.
- `<usa-badge>` (motionary/components/ui): Count or dot badge that bumps with a spring when its value changes; 99+ capping, optional pulse.
- `<usa-badge-wall>` (motionary/components/widgets): 7.5: an achievement grid — locked badges are grey with a 🔒; unlock(name) flips a badge to its colour side with a shine and the “n / m unlocked” counter updates
- `<usa-bar-chart>` (motionary/components/widgets): 7.2: bars grow from the baseline in a stagger on first view and new data glides every bar to its new height — bars that appear grow in, bars that leave shrink a
- `<usa-bg-generator>` (motionary/components/widgets): 9.3: a background generator — pick a palette and a style (mesh gradient, grain, stripes, dots), shuffle the seed and copy the CSS.
- `<usa-blobs>` (motionary/components/background): Soft colour blobs that slowly morph and drift — a fluid gradient backdrop.
- `<usa-bottom-sheet>` (motionary/components/ui): A draggable sheet with snap points, inertia and drag-down-to-dismiss — the iOS / Android pattern for web and Windows web-view apps.
- `<usa-button>` (motionary/components/click): Spring-driven button click deformation: squash & stretch, elastic border-radius wobble, gooey liquid droplets, and a dent toward the pressed point. Combine them
- `<usa-card>` (motionary/components/cards): Ten card effects you can combine (effect="lift sheen"): flip (hover or click, x/y axis), holo, glass, border-glow, conic-border, lift, spotlight, sheen, paralla
- `<usa-card-stack>` (motionary/components/cards): A deck where the top card swipes away left or right (pointer, touch, arrow keys) and the next springs forward. loop sends cards to the back.
- `<usa-carousel>` (motionary/components/widgets): 6.2: swipe, drag, arrow keys, dots and autoplay (pauses on hover, focus, off screen). Four transitions — slide, fade, scale and a 3D "cards" coverflow. Reduced 
- `<usa-carousel-3d>` (motionary/components/cards): Items on a 3D ring, rotated by drag, arrow keys, clicks or autoplay — with spring motion. Reduced motion shows one flat item at a time.
- `<usa-cart-drawer>` (motionary/components/widgets): 7.3: a cart button with a count badge and a drawer that slides in from the side — lines slide in (or bump their quantity), removed lines collapse, the badge bum
- `<usa-chapter-nav>` (motionary/components/widgets): 9.1: chapter navigation for long-form stories — one entry per chapter with a reading-progress bar that fills as you scroll, the current chapter highlighted, cli
- `<usa-chat-composer>` (motionary/components/widgets): 7.8: an AI chat input that grows with its text; Enter sends, the send button pops when there is text and morphs into Stop while busy, with a thinking glow runni
- `<usa-check>` (motionary/components/feedback): The circle draws itself, then a check, cross or exclamation strokes in with a pop. Great after a payment or upload.
- `<usa-checkbox>` (motionary/components/click): Form-associated checkbox: the box springs and the check draws itself; indeterminate state, circle shape.
- `<usa-click>` (motionary/components/click): Wrap anything: ripple, burst (circle, star, heart, emoji), confetti, squish, press-spring and error shake — combinable, keyboard-friendly, optional haptics.
- `<usa-clock-control>` (motionary/components/widgets): 8.0: a pause / speed bar for the unified motion clock — pause, slow down or speed up every Motionary animation and frame loop on the page at once (motionClock i
- `<usa-code-export>` (motionary/components/widgets): 8.9 low-code: shows copy-paste code (HTML, React, Vue or JSON) for a live, configured component next to it, follows its attribute changes and copies with one cl
- `<usa-color-picker>` (motionary/components/widgets): 6.9: a saturation / brightness square and a hue strip with spring-follow thumbs (both keyboard sliders), a preview chip that morphs to the new colour and swatch
- `<usa-command-palette>` (motionary/components/widgets): 7.9: a ⌘K command palette on the native <dialog> — scales in, filters as you type with fuzzy matching and highlighted letters, results stagger in and a highligh
- `<usa-compare>` (motionary/components/widgets): 6.5: drag the handle (or hover with the hover attribute), click to jump, or use the keyboard slider; horizontal or vertical; an intro sweep plays once when it s
- `<usa-countdown>` (motionary/components/widgets): 7.3: a split-flap countdown to a date (to) or for a number of seconds — every digit flips when it changes; fires usa:done at zero. The timer label updates once 
- `<usa-counter>` (motionary/components/text): Counts up to a number when visible, locale-formatted with tabular digits. Set .value to animate live dashboards.
- `<usa-cube>` (motionary/components/depth): Up to six children become the faces of a CSS 3D cube. Drag / swipe, arrow keys, autoplay or show("top"); spring-driven, the front face is the only one exposed t
- `<usa-cube-gallery>` (motionary/components/widgets): 6.5: slides sit on adjacent faces of a 3D cube that turns between them — swipe, arrow keys, buttons or autoplay (pauses on hover / focus / off screen); turn aro
- `<usa-cursor>` (motionary/components/page): A spring-lagged ring, a magnetic ring that wraps buttons and links, or a soft glow following the pointer. Mouse / pen only. (6.0: for a comet tail use the comet
- `<usa-date-picker>` (motionary/components/widgets): 6.9: months slide in from the direction of travel, the chosen day pops inside a spring circle, today has a ring. A real date grid: arrows, PageUp / PageDown, Ho
- `<usa-depth>` (motionary/components/depth): Layers with data-depth (-1…1) shift and scale by depth as the pointer moves, the phone tilts (source="orientation") or the page scrolls; optional whole-scene ro
- `<usa-dialog>` (motionary/components/transitions): Animated modal, side drawers and bottom sheet on the native <dialog>: top layer, focus trap, Esc, backdrop click.
- `<usa-disclosure>` (motionary/components/widgets): 6.2: native <details> that spring open and closed (height + fade) with an overshooting chevron; one open at a time unless multiple. Find-in-page and keyboard ke
- `<usa-distort>` (motionary/components/webgl): The image bulges and splits into RGB around the pointer. Without WebGL (or a cross-origin image without CORS) it falls back to a gentle CSS zoom.
- `<usa-dock>` (motionary/components/widgets): 6.6: items magnify with a smooth cosine falloff as the pointer moves along the dock, neighbours make room, labels pop above the hovered item and a click bounces
- `<usa-dot-network>` (motionary/components/background): A dot grid that swells and links up with lines around the pointer.
- `<usa-dotlottie>` (motionary/components/dotlottie; requires motionary/runtime/vector + motionary/runtime/lottie-state): 10.9: plays .lottie files with their themes (slots recoloured by a theme from the file) and state machines — playback states, event / numeric / boolean guards, 
- `<usa-double-tap>` (motionary/components/click): Double tap or double click a photo to pop a heart (or any emoji) at the tap point. L for keyboard users.
- `<usa-draggable>` (motionary/components/physics): Drag with mouse, touch, pen or arrow keys. spring-back returns home with a wobble; inertia glides after a flick; snap to a grid or points; rubber-band bounds.
- `<usa-draw>` (motionary/components/svg): Every stroke of the SVG inside draws itself — on view, hover, click or scrubbed with scroll — staggered between shapes, optional fill afterwards. No getTotalLen
- `<usa-drawer>` (motionary/components/ui): A side panel that springs in, drags / swipes closed, traps the page behind a backdrop and returns focus on close. Left, right, top or bottom.
- `<usa-equalizer>` (motionary/components/widgets): 7.1: one vertical slider per band with springy caps and a smooth response curve drawn through them; presets glide every band to its gain.
- `<usa-fab>` (motionary/components/ui): A floating action button whose actions fan out with a staggered spring: up, down, left, right or radial.
- `<usa-festival-banner>` (motionary/components/widgets): 8.1: an announcement banner with an ambient festive scene behind the text — lunar lanterns and sparkles, Christmas lights and snow, Halloween bats and moon, or 
- `<usa-field>` (motionary/components/widgets): 7.7: a text input whose label floats up on focus, with a growing underline; validates on blur — invalid shakes and slides the message in, valid draws a check. s
- `<usa-file-drop>` (motionary/components/widgets): 6.9: dragging files over it lights marching-ants borders and lifts the icon; dropped (or browsed) files fly into a list with progress bars that end in a drawn c
- `<usa-fullpage>` (motionary/components/page): Full-screen sections that snap one at a time, with keyboard paging, dot navigation and a usa:section event.
- `<usa-fx>` (motionary/components/fx): <usa-fx> plays any registered effect on its child: pulse, pop, jelly, wiggle, heartbeat, bounce, flash (≤ 2 per second), tada, shake. Click the button.
- `<usa-gauge>` (motionary/components/widgets): 7.2: a semicircular gauge — the needle swings to the value on a damped spring (overshoot, settle), the arc fills in the colour of its zone and the number counts
- `<usa-gen-art>` (motionary/components/widgets): 9.3: seeded generative art on a canvas — flow fields, circle packing, Truchet tiles or layered waves in curated palettes; it draws itself in on screen and a tap
- `<usa-gesture-fx>` (motionary/components/effects): 5.7: <usa-gesture-fx> plays any registered effect on a fling (fast release), a two-finger twist or a long press that charges --usa-charge 0 → 1. JS: bindGesture
- `<usa-gesture-sticker>` (motionary/components/widgets): 8.7: a multi-touch sticker — drag with one finger, pinch with two to scale and twist to rotate, all at once, with a lifted shadow while held (wheel / Shift + wh
- `<usa-gl-model>` (motionary/components/gl-model; requires motionary/runtime/gl + motionary/runtime/format-gltf + motionary/runtime/gltf-decoders + draco3d + basis_transcoder.js): 10.9: <usa-gl-scene> for compressed glTF — Draco meshes and KTX2 (Basis Universal) textures decoded by the official decoders (Google draco3d, Binomial’s Basis U
- `<usa-gl-scene>` (motionary/components/widgets; requires motionary/runtime/gl + motionary/runtime/format-gltf + motionary/runtime/format-obj + motionary/runtime/gltf-anim): 10.5: a WebGL2 3D viewer on Motionary’s own renderer — glTF 2.0 / GLB and OBJ / MTL models or built-in shapes, PBR-style materials, orbit controls (drag, wheel,
- `<usa-glitch>` (motionary/components/text): An RGB-split, sliced glitch — always on or on hover.
- `<usa-globe>` (motionary/components/widgets): 7.6: an SVG globe in orthographic projection — graticule, pulsing markers, spins while on screen, drag to turn it, flyTo(name) brings a city round to the front.
- `<usa-gpu-particles>` (motionary/components/widgets): 10.5 (WebGPU effects 2.0): tens of thousands of particles simulated by a WebGPU compute shader and drawn as instanced quads — swirl, galaxy or fountain, pointer
- `<usa-gradient-text>` (motionary/components/text): Text filled with a multi-colour gradient that keeps flowing.
- `<usa-grain>` (motionary/components/background): An SVG-noise grain overlay — no image to ship. animated makes it jitter like film.
- `<usa-grid-glow>` (motionary/components/background): A line grid behind the content that lights up around the pointer.
- `<usa-gyro-card>` (motionary/components/widgets): 8.7: a 3D card that tilts with the phone’s gyroscope (and with the pointer on desktop), with a moving glare and layers that float at different depths.
- `<usa-handwriting>` (motionary/components/text): The text draws itself stroke by stroke, then fills in — signatures, hero words.
- `<usa-hero-video>` (motionary/components/widgets): 9.4: a full-bleed hero with a background video — poster first, cross-fade to the video, a readable scrim, an always-there pause button and an optional scroll-sc
- `<usa-hold>` (motionary/components/click): Press and hold (pointer, Space or Enter) while a ring fills; releasing early rewinds. For destructive actions.
- `<usa-hud-panel>` (motionary/components/widgets): 8.4: a sci-fi HUD panel — angled corners, a glowing frame that draws itself in when the panel scrolls into view, a header with a blinking status light, and data
- `<usa-hydrate>` (motionary/components/widgets): 8.0: server-rendered children animate in on hydration — hidden only while JS is on and not yet upgraded (ssrHead() in the head, 3 s CSS fallback), then staggere
- `<usa-icon-morph>` (motionary/components/click): Icons that morph point-by-point with a spring: play ↔ pause, menu ↔ close, plus ↔ minus, check, arrow. toggle makes it a button with per-icon labels.
- `<usa-install-button>` (motionary/components/widgets): 10.1: one-click install snippet with npm / pnpm / yarn / bun / CDN tabs and a copy button that confirms with a check; `cdn` sets the URL of the CDN tab.
- `<usa-kanban>` (motionary/components/widgets): 6.8: drag cards between columns — the card lifts and tilts toward the drag, a placeholder opens where it will land and the other cards glide aside (FLIP). Full 
- `<usa-keyframe-editor>` (motionary/components/widgets): 6.9: a compact timeline for <usa-player> JSON — drag a bar to move a track, drag its edge to resize, scrub the playhead or press play; exports format use-scroll
- `<usa-kpi>` (motionary/components/widgets): 7.2: the value counts up keeping prefix, suffix and decimals ("$12.4k", "98.2%"), the delta chip slides in with an arrow coloured by sign, and an optional trend
- `<usa-leaderboard>` (motionary/components/widgets): 7.5: a ranked list — when scores change, rows glide to their new rank, climbers flash green with ▲n and fallers red with ▼n, scores roll and the top three get m
- `<usa-like>` (motionary/components/click): A heart that pops with a spring and bursts into particles; aria-pressed, optional count.
- `<usa-liquid>` (motionary/components/webgl): Click or tap to send water ripples through the image; hover adds a gentle wobble. The plain image stays when WebGL is unavailable.
- `<usa-liquid-nav>` (motionary/components/widgets): 8.3: a navigation bar whose active indicator is a drop of liquid — it stretches like a droplet towards the next item and settles with a wobble (gooey SVG filter
- `<usa-loading-bar>` (motionary/components/page): A slim NProgress-style bar for route changes and fetches: loadingBar.start() trickles, done() completes and fades.
- `<usa-location-card>` (motionary/components/widgets): 7.6: a place card with a stylised mini map — the route from the origin draws itself, the pin drops in with a bounce and a ring pulses; distance computed with ha
- `<usa-lottie>` (motionary/components/widgets): 9.2: plays Lottie (After Effects / bodymovin) files without lottie-web — vector layers render as SVG and their keyframes run as native animations on Motionary’s
- `<usa-lottie-icon>` (motionary/components/widgets): 9.2: an animated icon set shipped as tiny Lottie files — heart beat, bell swing, check draw-in, spinner, star twinkle, bolt zap — on click, hover, enter or loop
- `<usa-lottie-player>` (motionary/components/widgets; requires motionary/runtime/vector): 10.6: plays Lottie JSON and dotLottie (.lottie) files with Motionary’s own Canvas 2D renderer — shapes, gradients, trim paths, masks, track mattes, precomps and
- `<usa-lyrics>` (motionary/components/widgets): 7.1: LRC or [data-t] lines; the active line glows, scrolls to the centre and a highlight sweeps across it while past lines dim. Follows an <audio>, <video> or <
- `<usa-magnetic>` (motionary/components/interaction): Content leans toward the pointer when it comes near and springs back. Fine pointers only; off under reduced motion.
- `<usa-marquee>` (motionary/components/background): A seamless infinite ticker with constant speed, pause on hover, soft edges and vertical mode. Clones are hidden from AT.
- `<usa-mask-reveal>` (motionary/components/svg): Reveal images or sections through a growing mask: circle, diamond, star, iris or wipes, from any origin.
- `<usa-masonry>` (motionary/components/layout): Pinterest-style masonry: items drop into the shortest column and glide when the width, the items or their sizes change. CSS columns before JS runs.
- `<usa-masonry-flow>` (motionary/components/widgets): 6.5: a masonry grid whose items glide to their new places (FLIP) on resize, insert / remove, filter(), shuffle() and sort(); hidden items scale out, new ones sc
- `<usa-menu>` (motionary/components/widgets): 6.3: the list scales (or folds / slides) out of its button and the items cascade in. Full menu keyboard support — arrows, Home / End, Esc, Tab — and outside cli
- `<usa-menu-toggle>` (motionary/components/widgets): 6.6: the three bars morph into a cross, a back arrow, a minus or a spinning plus-to-cross; a real toggle button with aria-expanded that can open the element it 
- `<usa-message-list>` (motionary/components/widgets): 7.4: a chat thread — new bubbles pop in from their side, consecutive messages group, the list sticks to the bottom (or shows a “↓ New messages” pill when you sc
- `<usa-milestones>` (motionary/components/widgets): 6.5: a progress line grows down the rail as you scroll; each milestone pops its dot and slides its card in when the line reaches it. Alternating sides on wide s
- `<usa-modal>` (motionary/components/widgets): 6.3: native <dialog> (top layer, focus trap, Esc) with animated open / close and a blurred backdrop — scale, slide-up, flip, or origin: it grows out of the butt
- `<usa-morph>` (motionary/components/svg): Morph an SVG path through a list of shapes (paths="A | B | C") on click, hover, in view or automatically. Same-structure paths morph point by point.
- `<usa-motion>` (motionary/components/widgets): 9.0: the declarative motion DSL — describe motion as one readable string (“enter: fade-up 600ms stagger 80ms; hover: pop”) on <usa-motion> or any element’s data
- `<usa-motion-inspector>` (motionary/components/widgets): 10.2: a live panel listing the running animations in a scope (CSS animations, transitions, element.animate(), components) with state and progress, plus the moti
- `<usa-motion-prefs>` (motionary/components/widgets): 9.5: a motion settings panel for your users — motion level (full, gentle, minimal, none), animation speed, pause autoplaying video, no parallax — applied instan
- `<usa-motion-prompt>` (motionary/components/widgets): 10.7 (AI-assisted motion): describe a motion in English or Chinese and get a live preview plus ready code — Web Animations, CSS (with a reduced-motion guard) or
- `<usa-motion-spec>` (motionary/components/widgets): 9.7: a motion spec sheet for design hand-off — each rule of a motion string with its trigger, a duration bar on a shared timeline and the easing curve, a Play p
- `<usa-motion-switch>` (motionary/components/page): Let users pick Off · Low · Normal · High for the whole app; scales every component, persists, and Off equals reduced motion.
- `<usa-motion-theme>` (motionary/components/effects): 5.8: <usa-motion-theme name> applies a theme pack — design tokens (--usa-theme-*), motion tokens and effect presets per role (enter / hover / click / attention 
- `<usa-music-player>` (motionary/components/widgets): 7.1: the cover spins like a record while playing, play morphs to pause, mini equalizer bars dance and the progress bar is a scrubbable slider. Plays a child <au
- `<usa-native-preview>` (motionary/components/widgets): 9.8: preview web motion as it will feel on a phone — an iOS / Android device frame replays the entrance with the rule’s curve and presses with a spring — and co
- `<usa-nav-morph>` (motionary/components/widgets): 6.6: the indicator follows the hovered or focused link — stretching from the old one, leading edge first — and settles back on the current page. Underline, pill
- `<usa-navbar>` (motionary/components/ui): Hides while you scroll down, slides back on the first scroll up; shrink makes it compact once scrolled. This page’s demo scrolls an inner box.
- `<usa-notification-bell>` (motionary/components/widgets): 7.4: a bell with an unread badge and a dropdown — notify() swings the bell, bumps the badge and slides the notice in; “Mark all read” shrinks the badge away. Es
- `<usa-odometer>` (motionary/components/widgets): 6.4: rolling digit wheels — every digit spins forward to its new value, new digits slide in, locale grouping via Intl.NumberFormat, decimals, prefix / suffix. T
- `<usa-organic-card>` (motionary/components/widgets): 8.3: a card with a soft, living blob shape — its outline slowly breathes on screen, morphs on hover and comes in leaf, ocean, petal and sand tints.
- `<usa-otp>` (motionary/components/widgets): 7.7: one-time-code boxes that auto-advance, step back on Backspace and take a pasted code; digits pop in, error() shakes the row red, success() sends a green wa
- `<usa-overscroll>` (motionary/components/physics): A scroll container whose edges stretch with iOS-style rubber-band resistance and spring back — touch, trackpad and wheel.
- `<usa-pack>` (motionary/components/packs): Product cards reveal and lift, “Add to cart” presses and flies the product into the cart (which bumps), prices count up, badges pulse.
- `<usa-pagination>` (motionary/components/widgets): 6.7: the highlight springs to the chosen page (squashing on the way) and page numbers slide in from the direction of travel when the window shifts. Prev / next,
- `<usa-panorama>` (motionary/components/widgets): 8.8: a 360° panorama — drag or swipe to look around with inertia, a slow auto-rotate, a compass for the heading and a “View in XR” badge when the browser offers
- `<usa-parallax-layers>` (motionary/components/widgets): 10.4: a parallax container — children with data-depth move at different speeds while it crosses the viewport (native view() scroll timeline first, JS fallback),
- `<usa-particles>` (motionary/components/background): A canvas constellation that drifts away from the pointer. Runs only while visible, DPR ≤ 2, a still frame under reduced motion.
- `<usa-pause-all>` (motionary/components/widgets): 9.5: one button that pauses all motion on the page (WCAG 2.2.2) — Motionary’s shared clock, every CSS / Web animation and autoplaying media — and resumes it aga
- `<usa-perf-monitor>` (motionary/components/widgets): 9.6: a live performance overlay for motion work — FPS with a sparkline, active Motionary animations, frame-loop callbacks, long tasks and the shared clock — fla
- `<usa-physics-playground>` (motionary/components/widgets; requires motionary/runtime/physics + motionary/runtime/format-scene): 10.7: a 2D rigid-body sandbox on Motionary’s own physics engine — circles, boxes and polygons, friction, restitution, constraints, sleeping — loaded from a vers
- `<usa-pinch-zoom>` (motionary/components/gesture): Pinch with two fingers or Ctrl + wheel / trackpad pinch, pan while zoomed, double-tap to toggle; scale and position spring back inside the bounds.
- `<usa-player>` (motionary/components/effects): 5.9: <usa-player> plays a JSON animation — timeline presets, your own keyframes and any registered effect on a shared clock; play / pause / seek / rate / loop, 
- `<usa-plugin-card>` (motionary/components/widgets; requires motionary/runtime): 10.1: a plugin’s name, version and author with a Motionary compatibility badge (semver `engine` range), a signature badge (SHA-256 integrity checked with Web Cr
- `<usa-plugin-store>` (motionary/components/widgets): 9.0: the plugin marketplace as a component — search the catalogue of effect packs, see each plugin’s effects and install it with one click (imports and register
- `<usa-popover>` (motionary/components/ui): Click-to-open panel that springs from its trigger; Esc / outside click closes, focus returns.
- `<usa-post-fx>` (motionary/components/webgl): Chainable GPU passes over an image (4.8): vignette, grain, chromatic aberration, scanlines, CRT, bloom, pixelate, duotone and glitch, with one intensity. Withou
- `<usa-presence>` (motionary/components/widgets): 7.4: an avatar with a live status dot (online, away, busy, offline) — coming online sends a ripple, speaking adds a pulsing ring and story an animated gradient 
- `<usa-press>` (motionary/components/interaction): Tactile press: dips while pressed and springs back, or bounces once with bounce. Mouse, touch, pen and keyboard.
- `<usa-prize-wheel>` (motionary/components/widgets): 7.5: a lottery wheel — Spin whirls it and it eases out on the result (random or spin(index)), the pointer ticks and the wheel glows; usa:result reports the priz
- `<usa-product-gallery>` (motionary/components/widgets): 7.3: product photos with a thumbnail strip — the stage cross-slides in the direction of travel, the selection ring glides between thumbnails, hover zooms under 
- `<usa-progress>` (motionary/components/feedback): Determinate bars glide between values; without a value it shows the Fluent indeterminate animation. Paused / error states.
- `<usa-progress-ring>` (motionary/components/widgets): 6.4: the arc eases to every new value with a little overshoot while the label counts up; ring, bar or semicircle gauge, gradient strokes, indeterminate spinner 
- `<usa-prop-panel>` (motionary/components/widgets): 8.9 low-code: a property editor for a live component — typed fields (number / range, select, color, switch, text) bound to its attributes, so the component re-r
- `<usa-pull-cord>` (motionary/components/widgets): 6.8: pull the cord down and let go — past the threshold the lamp switches, and the cord swings back on a damped spring. Click, Space or Enter tug it too; role="
- `<usa-pull-refresh>` (motionary/components/ui): Pull down at the top of a list: the spinner stretches in with rubber-band resistance; release past the threshold to refresh.
- `<usa-radar>` (motionary/components/widgets): 8.4: a sci-fi radar scope — a conic beam sweeps round and each target lights up and fades as the beam passes over it.
- `<usa-reactions>` (motionary/components/widgets): 7.4: a reaction bar — clicking a pill toggles your reaction: the emoji pops, the count rolls and copies float up; ＋ springs open a picker. Each pill is a toggle
- `<usa-red-envelope>` (motionary/components/widgets): 8.1: a Lunar New Year red envelope — tap and the flap swings open, the card slides out with the amount counting up and gold coins pop out.
- `<usa-retro-button>` (motionary/components/widgets): 8.2: buttons in four eras with matching press motion — 8-bit pixel (stepped press), CRT phosphor (flicker), Y2K chrome pill (bounce) and Windows 95 bevel (sink)
- `<usa-reveal>` (motionary/components/reveal): Fade, slide, zoom, blur or flip content in as it enters the viewport. 12 effects, replay on re-entry with repeat.
- `<usa-ripple>` (motionary/components/interaction): Ink ripple from the pointer — or from the centre for Space/Enter — on any button, list item or card.
- `<usa-rive>` (motionary/components/widgets; requires @rive-app/canvas): 10.6: plays Rive (.riv) files — artboards, animations and state machines with inputs — through the official Rive runtime @rive-app/canvas, an optional peer depe
- `<usa-route-transition>` (motionary/components/widgets): 10.3: View Transitions 2.0 — link clicks swap the container’s content with the target page (fetched) or an inline <template data-route>, animated with the View 
- `<usa-scene>` (motionary/components/widgets): 9.1: a scroll-scrubbed cinematic shot — while the scene crosses the screen its image follows a camera move (dolly, pan, tilt, zoom, orbit) and captions fade in 
- `<usa-scramble>` (motionary/components/text): Decodes text out of random glyphs, left to right. Trigger on view, hover/focus or manually.
- `<usa-scroll-highlight>` (motionary/components/text): Words light up one by one as you read down the page, or a highlighter marker sweeps behind the text.
- `<usa-scroll-progress>` (motionary/components/reveal): Reading progress of the page or of one article. Compositor-only scaleX, role="progressbar".
- `<usa-scroll-ring>` (motionary/components/widgets): 10.4: a circular scroll-progress indicator for the page or any scroll container (for=".article"), optional percentage label and back-to-top button. Scroll-drive
- `<usa-scroll-scene>` (motionary/components/widgets; requires motionary/runtime/scroll): 10.2: a scroll-linked scene — children with data-scrub="opacity: 0 -> 1; x: -80 -> 0" are tweened as you scroll, scrubbed directly or smoothed (scrub="120"), wi
- `<usa-scrolly>` (motionary/components/reveal): A pinned graphic while [data-step] blocks scroll past; the active step drives the graphic via attributes, a CSS variable and events.
- `<usa-segmented>` (motionary/components/widgets): 6.7: an iOS-style thumb slides under the chosen segment with a spring and stretches while it travels. A real radio group: arrow keys, Home / End. iOS, pill or o
- `<usa-shader>` (motionary/components/webgl): A GPU shader behind your content: gradient, plasma, waves or aurora presets — or your own fragment shader in a <script type="x-shader/x-fragment">. Falls back t
- `<usa-shader-backdrop>` (motionary/components/widgets): 10.5 (WebGPU effects 2.0): an animated shader background (aurora, plasma, waves, nebula or your own GLSL) run through a post-processing chain — bloom, vignette,
- `<usa-sheet>` (motionary/components/widgets): 6.3: a side sheet from the right, left, top or bottom with a blurred backdrop; the bottom sheet can be dragged down to dismiss and springs back otherwise. Nativ
- `<usa-shimmer-text>` (motionary/components/text): A light sweep across gradient-filled text. CSS only; colours and speed via attributes or custom properties.
- `<usa-shortcut>` (motionary/components/widgets): 7.9: keyboard-shortcut hints as keycaps (⌘ on Apple, Ctrl elsewhere); press the combination anywhere and the caps press down one after another and usa:trigger f
- `<usa-skeleton>` (motionary/components/feedback): Shimmering placeholders while loading; remove loading and the real content fades in. aria-busy included.
- `<usa-skeleton-reveal>` (motionary/components/widgets): 6.4: the skeleton is generated from the real content — one bar per rendered text line, blocks for images and marked elements — with one synchronized shimmer (wa
- `<usa-sketch-chart>` (motionary/components/widgets): 8.5: a hand-drawn chart — wobbly pencil axes with hatched bars or a sketchy line, sketched in stroke by stroke when it scrolls into view.
- `<usa-slider>` (motionary/components/ui): A form-associated range slider: spring-following thumb, value bubble, full keyboard support (arrows, Page Up/Down, Home/End).
- `<usa-smooth-scroll>` (motionary/components/widgets; requires motionary/runtime/smooth): 10.4: smooth, inertial wheel scrolling for the page or a container (wrapper), anchor links glide (with offset for sticky headers); keyboard / scrollbar / touch 
- `<usa-snap-carousel>` (motionary/components/snap-carousel; requires motionary/runtime/drag-snap): 10.8: drag or swipe with real inertia — a throw keeps gliding, then springs to the nearest slide (a quick flick always moves one); rubber-band edges, arrows, do
- `<usa-sparkline>` (motionary/components/widgets): 7.2: a tiny inline trend — draws itself on first view, a soft area fades in, the last point pulses and new data morphs the line point by point. line | area | ba
- `<usa-spatial-card>` (motionary/components/widgets): 8.8: a spatial-computing window — frosted glass floating in depth, a soft gaze highlight that follows the pointer, layered content and an ornament bar; it eases
- `<usa-spinner>` (motionary/components/feedback): Six indeterminate indicators: the WinUI progress ring, the Windows 10 orbiting dots, ring, typing dots, pulse and bars.
- `<usa-splash>` (motionary/components/page): An app launch screen that leaves (fade, scale, slide-up, circle) once the page has loaded — never sooner than min ms.
- `<usa-split-text>` (motionary/components/text): Splits a headline into letters or words and cascades them in: rise, fade, blur, flip or pop. Words never break.
- `<usa-spotlight>` (motionary/components/interaction): The Windows Fluent “Reveal” effect: a light follows the pointer, lighting the borders of nearby items and the hovered one.
- `<usa-spring>` (motionary/components/physics): bounce-in, pop and drop entrances with true spring timing (CSS linear() easing), plus jelly and rubber-band attention effects on view, hover or click.
- `<usa-stagger>` (motionary/components/reveal): Reveals direct children one after another — lists, grids, feature rows.
- `<usa-star-rating>` (motionary/components/widgets): 6.4: the fill follows the pointer (half stars with step="0.5"), a click pops the chosen star with a sparkle burst while the others ripple; stars or hearts; a ke
- `<usa-stepper>` (motionary/components/widgets): 6.7: the rail fills toward the current step, finished steps pop a drawn check mark and the current step pulses. Horizontal or vertical; next() / prev() / value.
- `<usa-sticky-stack>` (motionary/components/cards): Cards stick while you scroll and the covered ones shrink and dim as the next slides over them.
- `<usa-sticky-wall>` (motionary/components/widgets): 8.5: a wall of sticky notes — each child becomes a pinned paper note with a slight tilt, the notes drop onto the wall one by one, and a tap lifts a note to the 
- `<usa-stories>` (motionary/components/widgets): 6.2: segmented progress bars, auto-advance, tap left / right to step, press and hold to pause, plus a pause button. Under reduced motion it waits for the user i
- `<usa-story>` (motionary/components/effects): 5.4: <usa-story template="compare"> wipes from before to after as you scroll; the handle is draggable and a keyboard slider (←/→, Home/End). Full-page templates
- `<usa-suggestion-chips>` (motionary/components/widgets): 7.8: follow-up prompt chips that slide in one after another; picking one pulses it and (with dismiss) the others fade away. Real buttons, arrow-key navigation.
- `<usa-swipe-deck>` (motionary/components/widgets): 6.8: drag the top card — it rotates with the pointer, LIKE / NOPE stamps fade in and past the threshold (or on a fling) it flies off; otherwise it springs back.
- `<usa-swipeable>` (motionary/components/gesture): Swipe-to-dismiss and swipe actions: content follows the finger, flies out on a fast swipe or past the distance, otherwise springs home with your release velocit
- `<usa-switch>` (motionary/components/widgets): 6.7: four switches — iOS (the thumb stretches while pressed), day / night (sun becomes moon, stars appear), bounce (squash at the end) and liquid (a gooey fill 
- `<usa-tab-bar>` (motionary/components/widgets): 6.2: the indicator stretches from the old tab to the new one (leading edge first) and the panel slides in from the side of travel. Pill, underline, glow or gooe
- `<usa-tabs>` (motionary/components/ui): Accessible tabs whose indicator slides between tabs with a spring; panels slide in from the direction you moved. Line or pill indicator.
- `<usa-terminal>` (motionary/components/widgets): 8.2: a retro terminal window that types its commands after the prompt with a blinking block cursor and prints the output line by line when it scrolls into view 
- `<usa-text-rotate>` (motionary/components/text): Cycles words in place — the box keeps the width of the longest word, so nothing around it reflows.
- `<usa-text-splitter>` (motionary/components/widgets; requires motionary/runtime/text): 10.3: splits its text into characters, words or lines and animates them in with a stagger (rise, fade, blur, flip, wave) when it scrolls into view — accessible,
- `<usa-theme-surface>` (motionary/components/widgets): 8.6: a themeable card that follows the nearest theme — light, dark, neon (pulsing glow edge), glass (frosted backdrop with a sheen) or soft neumorphic relief — 
- `<usa-theme-switcher>` (motionary/components/widgets): 8.6: a segmented switcher for the 8.6 theme system — light, dark, neon, glass and soft (neumorphism); a pill slides under the active option and the page change 
- `<usa-tilt>` (motionary/components/interaction): Tilts toward the pointer in 3D with an optional glare; exposes --usa-tilt-x/y for parallax layers inside.
- `<usa-timeline>` (motionary/components/timeline): Every data-tl child becomes a step in document order. data-at ('-=200', '<', 'label+=100') overlaps or aligns steps; scrub ties progress to scroll; trigger view
- `<usa-tip>` (motionary/components/widgets): 6.6: springs out of its trigger with an arrow, flips to stay inside the viewport and shifts along the edge; hover + keyboard focus (Esc closes) or click popover
- `<usa-toast-stack>` (motionary/components/widgets): 6.3: toasts pile up into a collapsed stack (newest in front, older ones peeking behind), fan out on hover or focus, auto-dismiss (paused while hovered) and swip
- `<usa-toaster>` (motionary/components/feedback): toast("Saved") slides a notification in; it pauses on hover, stacks with FLIP and announces politely (errors assertively).
- `<usa-token-editor>` (motionary/components/widgets): 10.6 (motion design tokens 2.0): edit duration and cubic-bézier easing tokens with a live preview per token, then export W3C Design Tokens (DTCG 2025.10 or the 
- `<usa-typewriter>` (motionary/components/text): Types text, or cycles through phrases with delete and pause. Full text stays available to screen readers.
- `<usa-upload-progress>` (motionary/components/widgets): 7.7: a file row whose bar eases to value with a running shine; at 100 it turns into a check that draws itself, on error it shakes and offers Retry.
- `<usa-video-card>` (motionary/components/widgets): 9.4: a video thumbnail card — hover or focus plays a muted preview with a progress line, a play badge and a duration chip; without a video the poster drifts (Ke
- `<usa-view-switch>` (motionary/components/transitions): One view at a time with direction-aware slide, fade, scale or drill transitions — tabs, wizards, app pages.
- `<usa-voice-button>` (motionary/components/widgets): 7.8: a push-to-talk mic button — while listening a halo breathes and level bars wave; feed it live input levels with level (0–1) and they follow your voice.
- `<usa-volume-knob>` (motionary/components/widgets): 7.1: a rotary knob — drag up / down, scroll or use the keys; the value arc fills, a ring of LED ticks lights up and the pointer springs to the angle. role="slid
- `<usa-water-ripple>` (motionary/components/background): Interactive water ripples on a canvas over the content: move or tap to disturb the surface.
- `<usa-wave-text>` (motionary/components/text): Letters bob in a travelling wave — playful headlines and loading labels.
- `<usa-weather-card>` (motionary/components/widgets): 6.8: sun rays turn, clouds drift, rain and snow fall, a flash-safe bolt glows, fog bands and stars — pick a condition and the scene cross-fades; the temperature
- `<usa-worker-canvas>` (motionary/components/widgets): 9.6: a canvas animation rendered in a Web Worker on an OffscreenCanvas — the main thread stays free for input — with a main-thread fallback; particles, orbits, 
- `<usa-xp-bar>` (motionary/components/widgets): 7.5: an experience bar — add(n) fills it smoothly; overflowing fills to the end, the level badge pops and the bar restarts with the remainder (several levels if