Motion
Three-tier motion system — lightweight CSS, GSAP scroll, premium effects.
BDS provides a three-tier motion system. Every tier is additive — load only what your design calls for. A subtle blog post needs one CSS file. A premium hero sequence needs the full stack. The tier decision belongs at design time, not implementation time.
Motion answers the same question as tokens: what are the constraints? Without a shared vocabulary, every developer invents their own easing curves, every designer picks their own durations, and no two pages feel like they came from the same studio. The Motion system fixes that.
Audience: primarily websites (Astro; Webflow as a legacy surface). Product surfaces (React) consume the lightweight tier (token-driven CSS animations) but rarely escalate to GSAP or Premium — those are website concerns.
The three-tier philosophy
Lightweight runs on every mockup by default. It is pure CSS: scroll-triggered reveals via .is-visible, hover micro-interactions, stagger patterns. No JavaScript library dependency. Ships immediately, runs in every browser, imposes no load-time cost. If the design audit says nothing specific about motion, you are here.
GSAP enters when the design calls for scroll choreography: pinned sections, scrub-linked animations, horizontal scroll panels, or SplitText letter-by-letter reveals. GSAP requires a CDN import and adds measurable weight — only load it when the design explicitly needs it. Scroll-pinning on a content page that doesn't benefit from it is over-engineering, not craft.
Premium handles atmosphere effects that GSAP alone does not cover: animated film grain, glassmorphism panels, magnetic cursor buttons, hero entrance sequences, and video scrubbing. Premium depends on premium-effects.css and premium-scroll.js, which in turn depend on GSAP. It is the full stack.
The cascade is not about quality — a Lightweight site can be beautifully crafted. It is about necessity. Escalate only when the design audit specifically calls for the effect.
File layout and import order
Load files in this order. Each layer depends on the one before it.
| File | Layer | Required for |
|---|---|---|
tokens/gap-fills.css | Token | All tiers — the semantic durations (--duration-fast / -normal / -slow) and all four --ease-* curves (part of the bds-tokens bundle) |
tokens/figma-tokens.css | Token | All tiers — the numeric duration primitives --duration-100 … --duration-600 the aliases resolve to (auto-generated from Figma) |
tokens/bridge.css | Token | All tiers — --stagger-1 … --stagger-6 (ships in dist/bridge.css, outside the canonical token registry) |
tokens/animations.css | Token | All tiers — named keyframes (bds-fade-in, bds-slide-up, etc.) |
tokens/motion-classes.css | Token | All tiers — composable utility classes (.bds-enter-fade, .bds-anim-pulse, .bds-stagger-1 through .bds-stagger-6) built from the token layer |
css/animations.css | Lightweight | Scroll reveal classes (.animate-fade-up), hover effects, entrance + stagger utilities |
css/premium-effects.css | Premium (CSS) | Grain overlays, glassmorphism, video backgrounds, clip-path reveals, section theming, typography effects, magnetic cursor + spotlight styles |
js/premium-scroll.js | Premium (JS) | IntersectionObserver orchestration + GSAP glue: hero sequences, background morphs, counters, scroll-scrubbed video, scroll-activated tabs |
iOS consumers: build/figma/swift/BDSMotion.swift exports the duration and easing tokens as Swift constants for UIKit / SwiftUI animation use.
Vocabulary
Two locked enums pair the Motion system to the client portal. When a client's animation tier or image mood is captured during onboarding, it carries forward into every mockup variant — the motion worker reads the tier to decide which libraries to load and which effects Claude is allowed to generate.
- Animation Tier —
subtle · moderate · expressive(single-select) - Image Mood — 6 values, multi-select 1–3
Explore
Tiers and Effects cut across each other — a single effect can span tiers, and a single tier carries several effects. They divide by job, so each fact has one home: Tiers pages own when you escalate and what to load; Effects pages own how — every class table, code sample, and live demo. Add an implementation detail to an effect page and cross-link from the tier, never both.
Tiers
Lightweight, GSAP, and Premium — when to use each.
Effects
Hover, scroll reveals, overlays, typography, video — the implementation patterns within each tier.
Vocabulary
Animation Tier and Image Mood — locked enums the portal captures and the motion worker reads.
Related
- Motion tokens — the
--duration-*,--ease-*, and--stagger-*scales, and why the numeric duration suffix is a step index rather than a millisecond value - Theming — the orthogonal theming tenet
- Content System — vocabularies that pair with the motion tier