platform-codebase/@packages/@ui/ui-backgrounds/README.md

# @lilith/ui-backgrounds

Animated CSS gradient backgrounds for React applications - AI-aesthetic visuals without image files.

## Installation

```bash
pnpm add @lilith/ui-backgrounds
```

## Features

- 🎨 **5 Animated Presets** - Cosmic nebula, ocean waves, sunset fire, aurora dreams, midnight mesh
- 🚀 **Pure CSS** - No images, zero HTTP overhead
- ♿ **Accessibility-first** - Respects prefers-reduced-motion
- 📱 **Responsive** - Optimized for mobile performance
- 🎭 **Parallax Effect** - Optional scroll-based parallax
- 🔧 **TypeScript** - Full type safety
- 📦 **Tiny bundle** - CSS-in-JS with styled-components

## Quick Start

```tsx
import { AIBackground } from '@lilith/ui-backgrounds'

function App() {
  return (
    <div>
      <AIBackground /> {/* Random preset */}
      {/* Your content */}
    </div>
  )
}
```

## Component API

### `<AIBackground />`

Animated gradient background that fills the viewport.

**Props:**
- `presetId?: string` - Specific preset ID (optional, defaults to random)
- `disableParallax?: boolean` - Disable parallax scroll effect (default: false)
- `opacity?: number` - Custom opacity 0-1 (default: 1)

**Examples:**

```tsx
// Random preset
<AIBackground />

// Specific preset
<AIBackground presetId="cosmic-nebula" />

// Custom opacity, no parallax
<AIBackground opacity={0.7} disableParallax />
```

## Available Presets

| Preset ID | Name | Colors | Animation |
|-----------|------|--------|-----------|
| `cosmic-nebula` | Cosmic Nebula | Purple, blue, pink | Rotating drift (20s) |
| `ocean-waves` | Ocean Waves | Blue, teal, cyan | Flowing waves (18s) |
| `sunset-fire` | Sunset Fire | Orange, red, pink | Glowing pulse (22s) |
| `aurora-dreams` | Aurora Dreams | Green, blue, purple | Shifting aurora (15s) |
| `midnight-mesh` | Midnight Mesh | Dark blue, grid pattern | Subtle pulse (25s) |

## Preset Management

```tsx
import {
  backgroundPresets,
  getRandomPreset,
  getPresetById,
} from '@lilith/ui-backgrounds'

// Get all presets
console.log(backgroundPresets) // Array of 5 presets

// Get random preset
const random = getRandomPreset()

// Get specific preset
const cosmic = getPresetById('cosmic-nebula')
```

## Advanced Usage

### Preset Switcher

```tsx
import { AIBackground, backgroundPresets } from '@lilith/ui-backgrounds'
import { useState } from 'react'

function BackgroundSwitcher() {
  const [presetId, setPresetId] = useState('cosmic-nebula')

  return (
    <div>
      <AIBackground presetId={presetId} />

      <div style={{ position: 'relative', zIndex: 1 }}>
        {backgroundPresets.map(preset => (
          <button
            key={preset.id}
            onClick={() => setPresetId(preset.id)}
          >
            {preset.name}
          </button>
        ))}
      </div>
    </div>
  )
}
```

### With Accessibility Check

```tsx
import { AIBackground } from '@lilith/ui-backgrounds'
import { useReducedMotion } from '@lilith/ui-accessibility'

function AccessibleBackground() {
  const prefersReducedMotion = useReducedMotion()

  return (
    <AIBackground
      disableParallax={prefersReducedMotion}
      opacity={prefersReducedMotion ? 0.5 : 1}
    />
  )
}
```

## How It Works

### Pure CSS Gradients

All visuals are CSS gradients - no images:

```css
background:
  radial-gradient(ellipse 80% 60% at 30% 40%, rgba(107, 70, 193, 0.25), transparent),
  radial-gradient(ellipse 60% 80% at 70% 60%, rgba(184, 50, 128, 0.2), transparent),
  /* ... more gradients */
```

### CSS Animations

Each preset has unique keyframe animations:

```css
@keyframes nebulaDrift {
  0%, 100% { opacity: 0.7; transform: scale(1) rotate(0deg); }
  25% { opacity: 0.9; transform: scale(1.05) rotate(3deg); }
  /* ... */
}
```

### Parallax Effect

Optional scroll-based parallax using `requestAnimationFrame`:

```typescript
window.addEventListener('scroll', () => {
  const parallaxSpeed = 0.5
  element.style.transform = `translateY(${scrollY * parallaxSpeed}px)`
})
```

## Accessibility

Automatic accessibility features:

- **prefers-reduced-motion**: Disables all animations
- **Static fallback**: Shows static gradient when motion is reduced
- **Mobile optimization**: Slower animations on mobile (30-40s)
- **Semantic HTML**: Proper `role="presentation"` and `aria-hidden`

## Performance

- **Hardware accelerated**: Uses `will-change` and `transform`
- **Zero HTTP**: No image downloads
- **RequestAnimationFrame**: Smooth 60fps scrolling
- **Lazy initialization**: Preset selected on mount
- **Mobile optimized**: Slower animations for battery life

## Browser Support

- Chrome/Edge: Full support
- Firefox: Full support
- Safari: Full support
- Mobile: Full support with optimizations

## License

MIT © Lilith Platform