Pricing

GradientMotion handbook

v4.0.1 · @snowui-design-system/components

License: Before reading component documentation, source, or npm usage instructions for the first time, read the full LICENSE. Reuse that review for the same task and version. Public API configuration and internal implementation changes have different license implications. All components use the unified runtime package; source rights remain governed by the license.

Overview

A flowing sweep of color for backgrounds, avatars, or clipped media areas.

When to use it

Use it for decorative animated gradient backgrounds. Prefer theme tokens for ordinary backgrounds. The specialized palette is limited to this graphic and must not become a general UI color source.

  • Choose a palette with variant; adjust playback with paused, speed, and intensity controls.

  • Use stable seed for static identity; decorative is turned on by default. Dynamic color does not replace the theme color system.

Quick start

This example shows the recommended basic composition. See the sections below for more cases and composition limits.

<script lang="ts">	import { GradientMotion } from '@snowui-design-system/components';</script> <section style="position: relative; isolation: isolate; overflow: hidden; width: min(100%, 34rem); min-height: 220px; border-radius: var(--radius-5); background: var(--background-1);">	<GradientMotion variant="azure" speed={0.55} width="100%" height="100%" style="position: absolute; inset: 0; opacity: 0.3;" />	<div style="position: relative; display: flex; flex-direction: column; align-items: flex-start; gap: var(--gap-3); padding: var(--padding-6); max-width: 24rem;">		<p style="font-size: var(--text-14); color: var(--black-40);">SnowUI documentation</p>		<h2 style="font-size: var(--text-24); line-height: var(--leading-24);">Build your next interface with a living visual identity.</h2>		<p>Use GradientMotion as a decorative media surface while content and actions remain readable above it.</p>		<a href="/components/quick-start" target="_top" style="color: var(--black-40);">Read the Quick Start</a>	</div></section>

API

Keyword Type Default Description
variant GradientMotionVariant "prism" Glimm palette. avatar is a slower, continuously filled avatar fallback. Legacy cosmic, matrix, electric, inferno, mystic, cyber, neon, plasma, and neatBlob values map to Glimm palettes.
seed string | number — Seed for the random preset; the same seed selects the same palette.
speed number 1 Dynamic speed magnification
duration number 800 Glimm sweep reference duration, unit ms
size number | string — Set the width and height at the same time
width number | string — Width
height number | string — Height
radius number | string "inherit" Corner radius; inherits the parent by default for Avatar clipping.
intensity number 1 Corresponding to glimm peakAlpha, the range is limited from 0 to 20
paused boolean false Whether to suspend the dynamic effect
decorative boolean true Whether to use as a decorative diagram; output aria-hidden="true" when true
direction GradientMotionDirection "ltr" Direction of the light sweep.
bandTight number 14 Glimm band gaussian tightness, the larger the value, the narrower the sweep band
waveAmount number 1 Strength of the Glimm edge wave and overall avatar wobble, clamped to 0–20.
rippleAmount number 1 Fine ripple strength, range 0–20
brightness number 1 Glimm band RGB brightness magnification, range 0–20
colorSpeed number 1 Custom color time phase speed multiplier, range 0–20; when 0, the color stops flowing
highlightIntensity number 1 Fresnel and mirror highlight intensity magnification, range 0–20; turn off the highlight when 0
colors GradientMotionColors — Four HEX sample colors for the cycle. The component derives a mean, sine term, and cosine term to produce a continuous Glimm palette that changes with time.
loopMotion LoopMotionConfig — Override the Frame loop bridge. paused=true always pauses playback. Shader timing still follows speed, duration, and paused; the default is a linear, infinite loop based on duration.

See the base component documentation for inherited capabilities not redeclared here. This table lists only named public Props declared by this component.

Usage boundaries and details

Feature overview

  • 6 kinds of palette with built-in glimm: prism, berry, lagoon, citrus, azure, ember

  • The six selectable palettes match the six swatches at the bottom of the glimm.dev screenshot; select one with variant.

  • WebGL shader restores the cosine palette formula of glimm: color(t)=a+b*cos(2π*(c*t+d))

  • Restore the default parameters of glimm sweep band: bandTight=14, waveAmount=1, rippleAmount=1, brightness=1, duration=800

  • Support variant="random", which can stabilize a random glimm palette according to seed

  • variant="avatar" selects the avatar fallback: seed stabilizes its palette, motion runs at 0.2 times the normal sweep speed, and the color band stays on the canvas while its wave and colors sway slowly without flashing white.

  • as="avatar-image" also activates the slow, continuously filled avatar mode, so Avatar fallback={GradientMotion} does not flash white.

  • Support direction="ltr|rtl|ttb|btt" to control the scanning direction

  • Support speed, size / width / height / radius, paused

  • Legacy preset names remain as compatibility aliases, but their appearance maps to the six Glimm palettes.

  • Support external cropping: round, rounded, square, arbitrary parent container overflow: hidden or clip-path

  • Support as role transmission; recommend as="avatar-image" in Avatar

Layout model

Main layout model: internal atomic layout.

  • The root node of GradientMotion only outputs a visual surface determined by the size, rounded corners and shader algorithm.

  • The component does not manage the sub-content arrangement and does not access the Leading / Content / Trailing three slots.

  • As a child, it hugs its content. As a background, give it a size such as class="w-full h-full" or an explicit outer style.

  • as transmits the host role; as="avatar-image" will also enable the continuous filling avatar mode without changing the internal layout of the component.

API reference

Keyword Type Default Description
as string - Frame role statement; Avatar scene recommendation as="avatar-image"

as="avatar-image" will automatically enable the continuous filling logic dedicated to the avatar; if you need to use the component directly, you can also explicitly pass variant="avatar".

Specialized art color exception

The built-in Glimm cosine palettes, CSS fallback palettes when WebGL is unavailable, and four six-digit HEX samples in colors are registered as specialized art color exceptions in StyleSpec §2.1.3 (specs/maintainers/StyleSpec.md). The shader converts them to numeric vectors and generates continuous color ranges. They represent generated imagery, not button, text, state, or surface semantics, so they do not need SnowUI semantic token mappings.

This exception covers only GradientMotion palettes. colors is not a general color Prop, and other components must still use resolveSnowUIColor(). Root sizing, radius, external class and style, accessibility, outer motion, and reduced-motion behavior still follow their specifications. Register any new palette type or use of these colors for UI semantics first.

Usage examples

<GradientMotion size={80} radius="9999px" />
<GradientMotion variant="berry" class="w-full h-full" radius="24px" speed={0.8} />
<Frame style="width: 44rem; height: 18rem; overflow: hidden; border-radius: 2rem;">    <GradientMotion variant="prism" width="100%" height="100%" radius="2rem" /></Frame>
<Avatar fallback={GradientMotion} data-name="Ada Lovelace" />
<GradientMotion variant="avatar" seed="Ada Lovelace" size={80} radius="9999px" />
<Avatar>    <GradientMotion as="avatar-image" variant="random" seed="profile-42" />    <Badge as="badge" dot /></Avatar>
<script lang="ts">  let motionSpeed = $state(1);  const colors = ["prism", "berry", "lagoon", "citrus", "azure", "ember"] as const;</script> <Slider bind:value={motionSpeed} minValue={0.2} maxValue={2} step={0.1} /> {#each colors as color}  <GradientMotion variant={color} width={200} height={120} radius={20} speed={motionSpeed} />{/each}

GradientMotion style overlay

Read the full LICENSE first; reuse that review for the same task, version, and scope.

First use public component Props to match the desired appearance, preserving the existing look where possible. If changes are necessary, follow the style selection and override order: use your own class (including Tailwind already in the project) or an instance style. The names below are public overrides actually consumed by source; check their scope and do not modify private DOM. Choose the correct SnowUI token family. External apps need not install SnowUI website utilities.

Variable Purpose and default reference
--snowui-gradient-motion-radius-override Rounded corner / crop radius (default inherit)
--snowui-gradient-motion-size-override Overall size (see the component source code for the default value)

Design Guide · Token · Combination Boundary

GradientMotion type and status

Required Props: no named required Props.

Bindable Props: this component declares no named two-way binding; handle state updates through public callbacks or its host.

Inheritance declaration: Omit<FrameProps, "size" | "width" | "height" | "radius">. The inheritance ability is subject to the public document of the base class; the fields in Omit have been excluded and cannot be used as they are according to the base class.

Share Frame API · Return API

The following type declarations are actually referenced by public Props and come from source. A Svelte Snippet denotes a content fragment; ComponentProps denotes the Props of the corresponding component.

GradientMotionVariant

Source: components/src/components/GradientMotion.svelte

export type GradientMotionVariant =        | "prism"        | "berry"        | "lagoon"        | "citrus"        | "azure"        | "ember"        | "avatar"        | "random"        | "cosmic"        | "matrix"        | "electric"        | "inferno"        | "mystic"        | "cyber"        | "neon"        | "plasma"        | "neatBlob";

GradientMotionDirection

Source: components/src/components/GradientMotion.svelte

export type GradientMotionDirection = "ltr" | "rtl" | "ttb" | "btt";

GradientMotionColors

Source: components/src/components/GradientMotion.svelte

export type GradientMotionColors = readonly [string, string, string, string];

LoopMotionConfig

Source: components/src/logic/frame-types.ts

export interface LoopMotionConfig {    /** Default loop preset (animates the entire Frame root) */    preset?: LoopMotionPreset;    /** Loop duration (milliseconds) */    duration?: number;    /** Loop easing function */    easing?: MotionConfig["easing"];    /** Iteration count (infinite by default) */    iterationCount?: number | "infinite" | (string & {});    /** Loop direction (normal by default) */    direction?:        | "normal"        | "reverse"        | "alternate"        | "alternate-reverse";    /** Playback state (running by default) */    playState?: "running" | "paused";}

LoopMotionPreset

Source: components/src/logic/frame-types.ts

export type LoopMotionPreset = "rotateClockwise";

MotionConfig

Source: components/src/logic/motion-config.ts

export interface MotionConfig {    // === Transform properties ===    /** Scale (1 = 100%) */    scale?: number | [number, number];    /** Horizontal offset (px or a CSS length) */    x?: number | string | [number | string, number | string];    /** Vertical offset (px or a CSS length) */    y?: number | string | [number | string, number | string];    /** Rotation (degrees) */    rotate?: number | [number, number];    /** Y-axis rotation (degrees), for front/back flips */    rotateY?: number | [number, number];    /** Opacity (0–1) */    opacity?: number | [number, number];    /** Blur radius (numbers are px) */    blur?: number | string | [number | string, number | string];    /** Height (supports incremental "+20px" syntax) */    height?: number | string;    /** Width */    width?: number | string;    /** Background color */    backgroundColor?: SnowUIColor | string;    /** Foreground color (text/icons), for color transitions */    color?: SnowUIColor | string;     // === Timing parameters ===    /** Delay (milliseconds) */    delay?: number;    /** Duration (milliseconds) */    duration?: number;    /** Easing function */    easing?: EasingFunction;     // === Physics simulation ===    /** Motion type */    type?: 'spring' | 'tween';    /** Spring stiffness (higher is stiffer) */    stiffness?: number;    /** Spring damping (higher stops faster) */    damping?: number;    /** Spring mass */    mass?: number;    /** Spring velocity threshold (stops below this value) */    velocity?: number;     // === Component reference ===    /** Use a custom component as the motion carrier (such as FlowText or Spin) */    component?: any;     // === Orchestration ===    /** Whether to participate in parent orchestration */    orchestrate?: boolean;}

SnowUIColor

Source: components/src/lib/color.ts

export type SnowUIColor = keyof typeof SNOWUI_COLOR_TOKENS;

EasingFunction

Source: components/src/logic/motion-config.ts

export type EasingFunction =    | 'linear'    | 'easeIn' | 'easeOut' | 'easeInOut'    | 'cubicIn' | 'cubicOut' | 'cubicInOut'    | 'quadIn' | 'quadOut' | 'quadInOut'    | 'quartIn' | 'quartOut' | 'quartInOut'    | 'quintIn' | 'quintOut' | 'quintInOut'    | 'sineIn' | 'sineOut' | 'sineInOut'    | 'expoIn' | 'expoOut' | 'expoInOut'    | 'circIn' | 'circOut' | 'circInOut'    | 'backIn' | 'backOut' | 'backInOut'    | 'elasticIn' | 'elasticOut' | 'elasticInOut'    | 'bounceIn' | 'bounceOut' | 'bounceInOut'    | (string & {});