npm package: @sublimee/backgrounds
Description: Animated canvas backgrounds with zero-setup API
Author: Sublime Team
Latest version: 0.1.28

# @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](./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

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

<AnimatedBackground type="particle-field" />
```

### Sound Wave

```tsx
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

```tsx
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

```tsx
<AnimatedBackground type="particle-field" />
```

### Contained

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

### Direct renderer

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

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

### Layering

`zIndex` now accepts a normal CSS z-index value:

```tsx
<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