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

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

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:

// 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

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

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

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:

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:

@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:

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