@sublimee/backgrounds

Animated canvas backgrounds for apps that already use shadcn/ui or a similar CSS-variable theme contract.

If you are an AI agent reading the installed npm package directly, start with AI_INDEX.md.

Use This Package When

• you want a full-page animated background without wrapper boilerplate,
• you want a contained animated background for a section or card,
• you already have app theme variables such as --background, --foreground, and --primary.

First Move

import { AnimatedBackground } from "@sublimee/backgrounds";

<AnimatedBackground type="particle-field" />

Sound Wave

import { AnimatedBackground } from "@sublimee/backgrounds";

// Horizontal waves (default)
<AnimatedBackground type="sound-wave" />

// Vertical waves
<AnimatedBackground
  type="sound-wave"
  config={{ orientation: "vertical" }}
/>

// With custom styling
<AnimatedBackground
  type="sound-wave"
  config={{
    orientation: "horizontal",
    waveCount: 5,
    thickness: 3,
    amplitude: 60,
    frequency: 0.03,
    waveColor: "var(--primary)",
  }}
/>

// Multi-colored waves
<AnimatedBackground
  type="sound-wave"
  config={{
    orientation: "horizontal",
    waveCount: 6,
    thickness: 3,
    amplitude: 50,
    frequency: 0.02,
    speed: 0.8,
    waveColors: [
      "#FFD700", // Gold
      "#FFD700", // Gold
      "#000080", // Navy
      "#000080", // Navy
      "#000080", // Navy
      "#000080", // Navy
    ],
    bgColor: "#F5F5F5", // Whitesmoke
  }}
/>

In a standard shadcn/ui app, the default colors already target:

• --background
• --foreground
• --primary

with hardcoded fallbacks when those variables are missing.

Recommended Usage With shadcn/ui

import { AnimatedBackground } from "@sublimee/backgrounds";

export function AppBackground() {
  return (
    <AnimatedBackground
      type="particle-field"
      config={{
        bgColor: "var(--background)",
        particleColor: "var(--foreground)",
        accentColor: "var(--primary)",
        shootingStarStyle: {
          color: "var(--primary)",
        },
      }}
    />
  );
}

Theme Contract

The package is designed around app-owned CSS variables.

Most useful variables in shadcn/ui setups:

• --background
• --foreground
• --primary
• --muted-foreground
• --border
• --ring

The canvas renderer resolves CSS variables on first render and re-resolves them when theme-related attributes change, including:

• .dark
• data-theme="dark"
• system preference changes through prefers-color-scheme

Modern color formats such as oklch(...), hsl(...), rgb(...), and hex values are supported through browser-resolved computed colors.

Current Public Surface

Components

• AnimatedBackground
• ParticleFieldBackground
• SoundWaveBackground

Current background types

• particle-field
• sound-wave

Important Defaults

• AnimatedBackground is full-page by default
• fixed={false} switches to contained mode
• fixed mode uses inline positioning styles, so consumer Tailwind scanning is not required
• default colors follow shadcn/ui variables before falling back to hardcoded values

API Notes

Full-page

<AnimatedBackground type="particle-field" />

Contained

<div className="relative h-64 overflow-hidden rounded-xl">
  <AnimatedBackground type="particle-field" fixed={false} />
</div>

Direct renderer

import { ParticleFieldBackground } from "@sublimee/backgrounds";

<ParticleFieldBackground fixed={false} particleCount={200} />

Layering

zIndex now accepts a normal CSS z-index value:

<AnimatedBackground type="particle-field" zIndex={0} />

High-Value Controls

ParticleField

• particleCount
• particleColor
• accentColor
• particleShape
• particleTrail
• shootingStarStyle
• fps
• fixed

SoundWave

• orientation — "horizontal" | "vertical"
• waveCount — number of waves
• waveColor — wave line color (fallback when waveColors not provided)
• waveColors — array of colors for each wave index (e.g., ["#FFD700", "#000080", "#fff"])
• bgColor — background color
• amplitude — wave height in pixels
• frequency — wave compression
• thickness — line thickness
• speed — animation speed multiplier
• fps
• fixed

License

MIT