# SDS Motion Forge **Every class that worked in v3/v4 works identically in v5 — machine-verified against the published tarball on every build.** **600+ production-ready CSS animations. One class name. Zero required JavaScript.** [![npm version](https://img.shields.io/npm/v/@salkomdesignstudio/sds-motion-forge.svg?style=flat-square)](https://www.npmjs.com/package/@salkomdesignstudio/sds-motion-forge) [![Bundle size](https://img.shields.io/bundlephobia/minzip/@salkomdesignstudio/sds-motion-forge?style=flat-square)](https://bundlephobia.com/package/@salkomdesignstudio/sds-motion-forge) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](LICENSE) [![CI](https://github.com/salkomdesignstudio/SDS-Motion-Forge/actions/workflows/ci.yml/badge.svg)](https://github.com/salkomdesignstudio/SDS-Motion-Forge/actions/workflows/ci.yml) A production-grade motion system for modern UI — framework-agnostic, accessible, and backward-compatible. Add a class and your element animates. That is the entire API. > **Live demo:** [sds-motion-forge.netlify.app](https://sds-motion-forge.netlify.app) — every effect with six copy-paste code tabs (HTML, JS, React, Angular, Tailwind, Bootstrap), each one machine-verified against the packed npm tarball before it can ship. > **Custom bundle builder:** [/builder.html](https://sds-motion-forge.netlify.app/builder.html) — pick effects, download exactly their CSS (+ tokens, reduced-motion, keyframes), live size estimate. > **Motion specification:** [SPEC.md](SPEC.md) — principles, token scale, duration/easing selection matrix, choreography rules. > **For AI tools:** [llms.txt](https://sds-motion-forge.netlify.app/llms.txt) · [registry.json](https://sds-motion-forge.netlify.app/registry.json) — the full machine-readable effect registry. --- ## Table of Contents - [What's in v5](#whats-in-v5) - [Quick Start](#quick-start) - [Installation](#installation) - [npm / yarn / pnpm](#npm--yarn--pnpm) - [CDN (no build step)](#cdn-no-build-step) - [Framework Integrations](#framework-integrations) - [How It Works](#how-it-works) - [Animation Reference](#animation-reference) - [Text — 104 classes](#text--104-classes) - [Buttons — 100 classes](#buttons--100-classes) - [Inputs — 100 classes](#inputs--100-classes) - [Cards — 100 classes](#cards--100-classes) - [Loaders — 100 classes](#loaders--100-classes) - [Scroll — 100 classes](#scroll--100-classes) - [Interactive Animations (JS engine)](#interactive-animations-js-engine) - [Modifiers](#modifiers) - [Stagger & Children Animations](#stagger--children-animations) - [Theming](#theming) - [TypeScript & Autocomplete](#typescript--autocomplete) - [Accessibility](#accessibility) - [Browser Support](#browser-support) - [Project Structure](#project-structure) - [Build from Source](#build-from-source) - [Contributing](#contributing) - [Backward Compatibility](#backward-compatibility) - [License](#license) --- ## What's in v5 - **104 text animations** — 50 originals + 5 physics per-character animations + 49 new motion families - **100 button animations** — ambient, hover, entrance, and kinetic effects for interactive elements - **100 input animations** — focus, validation, ambient, and reveal states for form fields - **100 card animations** — entry, ambient, hover, 3D, and choreography effects for containers - **100 loader animations** — self-contained spinners, progress indicators, and motion loaders - **100 scroll animations** — viewport-triggered entrance effects across 15+ motion families - **`sds-scroll.min.js`** — 1.28 KB scroll-gate engine. Elements stay hidden until they enter the viewport, with optional replay and delay. - **`motion-interactive.min.js`** — 6.98 KB cursor-reactive engine. Magnetic pull, repulsion field, shockwave click, scatter return, spring kerning, word morph, jelly hover. Zero config. - **Full backward compatibility** — every v3.x class name still works identically --- ## Quick Start ```html

Hello World

``` That's it. No JavaScript. No configuration. No build step. --- ## Installation ### npm / yarn / pnpm ```bash npm install @salkomdesignstudio/sds-motion-forge # or yarn add @salkomdesignstudio/sds-motion-forge # or pnpm add @salkomdesignstudio/sds-motion-forge ``` ### Category bundles (v5) — import only what you use Each category ships as a self-sufficient bundle (its animations + their keyframes + core: tokens, modifiers, reduced-motion, scroll gate). One import, no other setup: ```js // Only the loaders — nothing else ships import '@salkomdesignstudio/sds-motion-forge/categories/loaders'; ``` ```html ``` | Bundle | Import | Minified | Gzip | |---|---|---|---| | text | `@salkomdesignstudio/sds-motion-forge/categories/text` | 45.5 KB | 8.4 KB | | buttons | `@salkomdesignstudio/sds-motion-forge/categories/buttons` | 49.1 KB | 8.6 KB | | inputs | `@salkomdesignstudio/sds-motion-forge/categories/inputs` | 47.0 KB | 8.4 KB | | cards | `@salkomdesignstudio/sds-motion-forge/categories/cards` | 39.6 KB | 7.5 KB | | loaders | `@salkomdesignstudio/sds-motion-forge/categories/loaders` | 49.1 KB | 8.1 KB | | scroll | `@salkomdesignstudio/sds-motion-forge/categories/scroll` | 33.6 KB | 5.8 KB | | core only | `@salkomdesignstudio/sds-motion-forge/categories/core` | 3.3 KB | 1.0 KB | | **everything** | `@salkomdesignstudio/sds-motion-forge` | **241.7 KB** | **38.4 KB** | Core is intentionally **inlined** into every category bundle so each one works standalone via npm or a single CDN `` — no peer imports to forget, no broken styles when a pipeline strips `@import`. Core costs ~3 KB minified (~1 KB gzip); if you combine **two or more** categories, import the full `dist/motion.css` instead — it ships exactly one copy of core and every class. ### CDN (no build step) ```html ``` ### Framework packages (v5) First-class wrappers, generated from the motion registry — typed effect unions for all 350+ animations, zero runtime dependencies: | Package | What you get | |---|---| | [`@salkomdesignstudio/motion-forge-tailwind`](packages/tailwind) | `animate-sds-*` utilities for Tailwind v4 (CSS-first, tree-shaken) + v3 preset | | [`@salkomdesignstudio/motion-forge-react`](packages/react) | ``, SSR-safe ``, `useSdsInView` | | [`@salkomdesignstudio/motion-forge-angular`](packages/angular) | standalone `sdsMotion` / `sdsText` / `sdsInView` directives (signal inputs, zoneless-ready) | | [`@salkomdesignstudio/motion-forge-elements`](packages/elements) | framework-free `` / `` Web Components | The core package stays 100 % framework-agnostic — wrappers are optional sugar. ### Framework Integrations #### React / Next.js ```jsx // Import once in _app.js, layout.js, or main.jsx import '@salkomdesignstudio/sds-motion-forge/dist/motion.min.css'; export default function Hero() { return

Hello React

; } ``` **Next.js App Router** — add to `app/layout.tsx`: ```tsx import '@salkomdesignstudio/sds-motion-forge/dist/motion.min.css'; ``` #### Vue ```js // main.js / main.ts import '@salkomdesignstudio/sds-motion-forge/dist/motion.min.css'; ``` ```html ``` #### Angular Add to `styles.scss` or list in `angular.json` under `architect.build.options.styles`: ```scss @import '@salkomdesignstudio/sds-motion-forge/dist/motion.min.css'; ``` ```html

Hello Angular

``` #### Svelte / SvelteKit ```html

Hello Svelte

``` #### Tailwind CSS Motion Forge layers cleanly alongside Tailwind. Classes never conflict because all SDS classes are prefixed `sds-`: ```html
Card with ambient float
``` #### Bootstrap ```html
Holographic card
``` #### PostCSS (use the source) The source file is published so you can process it through your own PostCSS pipeline: ```js // postcss.config.js module.exports = { plugins: [ require('postcss-import'), require('autoprefixer'), ], }; ``` ```css /* your-styles.css */ @import '@salkomdesignstudio/sds-motion-forge/src/motion.css'; ``` #### Flutter Web ```html ``` --- ## How It Works The library has three independent layers. Use only what you need. ### Layer 1 — CSS Core (always, no JS) The entire `motion.min.css` file. Add a class → animation plays. Works in any environment, including static HTML, SSR, and email-safe HTML. ```html Animates immediately on load ``` ### Layer 2 — Scroll Gate (`sds-scroll.min.js`, optional) Load once. The engine observes `[data-sds]` elements via `IntersectionObserver` and adds `sds-play` when they enter the viewport. ```html

Appears when scrolled into view

Replays on re-entry

200ms delay
``` **Attributes:** | Attribute | Required | Effect | |---|---|---| | `data-sds` | Yes | Gates the animation until viewport entry | | `data-sds-repeat` | No | Remove `sds-play` on exit so the element replays on re-entry | | `data-sds-delay="N"` | No | Wait N milliseconds after viewport entry before starting | ### Layer 3 — Interactive Engine (`motion-interactive.min.js`, optional) Load once. Zero JavaScript from you — just add a class. The engine auto-wires all event listeners, physics loops, and MutationObserver cleanup. ```html

Cursor attracts each character

``` --- ## Animation Reference ### Text — 104 classes Apply to any element containing text. #### Original 50 | Class | Effect | Type | |---|---|---| | `sds-velvet-drop` | Weighted drop-in with blur and bounce | entrance | | `sds-liquid-rise` | Fluid upward reveal with skew | entrance | | `sds-phantom-blur` | Bright blur crystallises to sharp | entrance | | `sds-gravity-drop` | Accelerated fall with elastic overshoot | entrance | | `sds-elastic-stamp` | Scales from zero with elastic rotation | entrance | | `sds-slice-reveal` | Horizontal clip-path wipe | entrance | | `sds-char-orbit` | Orbits in from above with rotation | entrance | | `sds-ink-bleed` | Letter-spacing collapses as blur resolves | entrance | | `sds-focus-pull` | Camera-focus blur → sharp | entrance | | `sds-depth-warp` | Flies in from deep Z-space | entrance | | `sds-typewriter-pro` | Classic typewriter with blinking caret | entrance | | `sds-highlight-burn` | Highlight marker swipe | entrance | | `sds-shatter-in` | Explodes in from massive scale with blur | entrance | | `sds-weight-drop` | Extreme-easing gravity overshoot | entrance | | `sds-smoke-reveal` | Smoke-field blur resolves to text | entrance | | `sds-depth-charge` | Deep Z-space warp with delay | entrance | | `sds-film-burn` | Sepia focus-pull entrance | entrance | | `sds-streak-in` | High-speed streak from left | entrance | | `sds-elastic-bounce` | Spring overshoot bounce-in | entrance | | `sds-cipher-reveal` | Brightness and blur decode | entrance | | `sds-word-blur-in` | Blur resolves to sharp with scale | entrance | | `sds-split-reveal` | Polygon clip-path splits from center | entrance | | `sds-bounce-in-up` | Multi-step elastic bounce from below | entrance | | `sds-cinema-title` | Letter-spacing collapse with blur | entrance | | `sds-unfurl` | clip-path + scaleX unfurls left→right | entrance | | `sds-refract` | Chromatic RGB split | loop | | `sds-static-burst` | Glitch-static corruption | loop | | `sds-neon-flare` | Pulsing neon glow | loop | | `sds-scramble-decode` | Blur + skew decoding | loop | | `sds-kinetic-wave` | Per-child translateY wave (needs `.sds-char` children) | loop | | `sds-perspective-swing` | rotateY swing with perspective | entrance | | `sds-gradient-sweep` | Moving brand gradient mask | loop | | `sds-prism-split` | Full-spectrum chromatic aberration | loop | | `sds-arc-orbit` | Per-child stagger orbit (needs `.sds-char` children) | entrance | | `sds-signal-wave` | Wider stagger wave (needs `.sds-char` children) | loop | | `sds-glitch-flicker` | Analog glitch flickering | loop | | `sds-velocity-blur-text` | Motion-blur streak from left | entrance | | `sds-neon-pulse-text` | Breathing neon glow | loop | | `sds-morph-word` | scaleX + skewX + letter-spacing morph | loop | | `sds-levitate` | Gentle float with subtle rotation | loop | | `sds-hologram-text` | Holographic hue-rotate flicker | loop | | `sds-aurora-text` | Six-colour gradient sweep | loop | | `sds-oscillate` | Sine-wave Y + rotate + scaleX | loop | | `sds-flicker-on` | Stepped opacity neon power-on | loop | | `sds-magnetic-drift` | Circular XY drift | loop | | `sds-data-stream` | clip-path + brightness data-decode | entrance | | `sds-chromatic-shift` | Slow hue-rotate colour cycle | loop | | `sds-ripple-text` | letter-spacing + scale + blur ripple | loop | | `sds-stagger-chars` | Per-child skewY stagger (needs `.sds-char` children) | entrance | | `sds-heat-shimmer` | Subtle heat-distortion skewX | loop | #### Physics per-character (requires `.sds-char` spans) These animate each character individually using the `--i` CSS variable as a stagger index. ```html

H e l l o

``` **Tip:** Load `motion-interactive.min.js` — it automatically splits text into `.sds-char` spans for any element using these classes. | Class | Effect | |---|---| | `sds-gravity-bounce` | Falls from above, inelastic floor bounce | | `sds-drop-settle` | Staggered fall with spring settle | | `sds-wave-cascade` | translateY wave propagates char-to-char (loop) | | `sds-center-burst` | Chars start at center, fan out to reading position | | `sds-explode-formation` | Scattered start (`--dx`, `--dy`, `--dr`), springs into place | For `sds-explode-formation`, set per-character displacement variables: ```html S D S ``` #### New motion families (45 classes) | Class | Effect | Type | |---|---|---| | `sds-fold-down` | 3D fold from above (top-origin hinge) | entrance | | `sds-fold-up` | 3D fold from below (bottom-origin hinge) | entrance | | `sds-flip-x` | 180° horizontal axis flip | entrance | | `sds-flip-y` | 180° vertical axis flip | entrance | | `sds-door-open` | rotateY from left edge like a door swinging open | entrance | | `sds-zoom-punch` | scale 0.2 → 1.12 → 1 punch | entrance | | `sds-zoom-far` | scale 2.2 → 1 with blur, arrives from Z-distance | entrance | | `sds-vapor-rise` | translateY + blur + saturate ghostly rise | entrance | | `sds-light-speed` | translateX + multi-step skewX streak | entrance | | `sds-roll-in` | Rolls in with 360° rotation | entrance | | `sds-swing-in` | Pendular rotateX swing from top origin | entrance | | `sds-skew-slide` | translateX + skewX arrives at an angle | entrance | | `sds-pop-in` | scale 0 → spring overshoot with rotation | entrance | | `sds-tracking-expand` | Letter-spacing compressed → normal | entrance | | `sds-tracking-contract` | Letter-spacing wide → collapses inward | entrance | | `sds-blur-focus` | blur + letter-spacing → sharp focus | entrance | | `sds-wipe-right` | Polygon clip expands left→right | entrance | | `sds-wipe-left` | Polygon clip expands right→left | entrance | | `sds-reveal-up` | Polygon mask slides upward | entrance | | `sds-reveal-down` | Polygon mask slides downward | entrance | | `sds-iris-open` | circle() clip-path opens from center | entrance | | `sds-shimmer-sweep` | Light shimmer over brand gradient | loop | | `sds-color-cycle` | Hue-rotating gradient background-clip text | loop | | `sds-glow-pulse` | text-shadow expands and contracts | loop | | `sds-neon-flicker-in` | Stepped opacity + glow neon power-on | entrance | | `sds-echo-out` | Layered offset text-shadow appear | entrance | | `sds-shadow-lift` | Floats up, layered text-shadow grows | loop | | `sds-spotlight-text` | Cyclic brightness + blur radial | loop | | `sds-pixel-in` | blur + contrast step-based | entrance | | `sds-glitch-slide` | translateX displacement + clip-path | entrance | | `sds-squash-stretch` | scaleY 0.15 → stretch → spring settle | entrance | | `sds-bounce-drop` | Multi-bounce drop from high above | entrance | | `sds-slant-rise` | translateY + rotate + skewX entrance | entrance | | `sds-grand-entrance` | translateY + scale + rotate + blur combo | entrance | | `sds-slide-blur-left` | Enters from left with motion blur | entrance | | `sds-slide-blur-right` | Enters from right with motion blur | entrance | | `sds-wobble` | translateX + rotate oscillating | loop | | `sds-rubber-band` | scaleX + scaleY rapid stretch | loop | | `sds-jello` | skewX + skewY rapid decay | loop | | `sds-tada` | scale + rotate celebratory | loop | | `sds-heartbeat-text` | Double-pulse scale heartbeat | loop | | `sds-typing-caret` | width 0 → 100% typewriter with cursor | entrance | | `sds-float-bob` | Gentle Y float with micro-rotation | loop | | `sds-underline-grow` | `::after` underline draws left→right | entrance | | `sds-strike-through` | `::after` strikeout line draws left→right | entrance | --- ### Buttons — 100 classes Apply directly to ` ``` All 100 button classes: ``` sds-btn-amp sds-btn-aurora sds-btn-border-flow sds-btn-bounce sds-btn-burst sds-btn-charge sds-btn-crystal sds-btn-depth-press sds-btn-dissolve sds-btn-edge sds-btn-energy sds-btn-fire sds-btn-flare sds-btn-float sds-btn-flux sds-btn-glow-core sds-btn-glow-surge sds-btn-gradient-shift sds-btn-gravity sds-btn-gravity-pull sds-btn-heartbeat sds-btn-hologram sds-btn-ice sds-btn-kinetic sds-btn-lift sds-btn-liquid sds-btn-magnetic sds-btn-magnetic-trail sds-btn-momentum sds-btn-morph sds-btn-neon sds-btn-neon-trace sds-btn-outline-grow sds-btn-plasma sds-btn-press sds-btn-pulse-border sds-btn-quantum sds-btn-radar sds-btn-recoil sds-btn-ripple sds-btn-rotate sds-btn-scan sds-btn-shimmer sds-btn-shock sds-btn-split sds-btn-stretch sds-btn-swipe sds-btn-tilt sds-btn-volt sds-btn-warp ``` --- ### Inputs — 100 classes State-based effects for `` and `