npm package: @rare-ui/experience
Description: Rare Design System — 56 cinematic visual effects: backgrounds, cursors, text animations
Latest version: 0.1.1

# @rare-ui/experience

56 cinematic visual effects for React — backgrounds, cursors, and text animations. The experience layer of the Rare Design System.

## Install

```bash
npm install @rare-ui/core @rare-ui/experience lucide-react
```

> `@rare-ui/core` is required — experience components use its design tokens for theming.

## Quick Start

```tsx
import '@rare-ui/core/styles.css';
import '@rare-ui/experience/styles.css';
import { ShootingStars, BloomText, CurlyCursor } from '@rare-ui/experience';

function App() {
  return (
    <div>
      {/* Full-page cursor effect */}
      <CurlyCursor />

      {/* Background effect */}
      <div style={{ position: 'relative', height: '100vh' }}>
        <ShootingStars
          starCount={12}
          bgStarCount={80}
          style={{ position: 'absolute', inset: 0, background: '#09090b' }}
        />
        <h1>Welcome</h1>
      </div>

      {/* Text effect */}
      <BloomText text="Rare Design System" />
    </div>
  );
}
```

## What's Included

### Backgrounds (18)

ShootingStars, RetroGrid, FallingLines, SplashyLines, MaskGrid, CircuitBoard, DotWave, Grid3D, LaserFlow, MatrixRain, Sparkles, AnimatedGrain, AnimatedNebula, GradientBackground, MovingGradient, NoiseGradient, BlackHole, ColorWave

### Cursor Effects (6)

CurlyCursor, CursorTrail, BubbleCursor, GhostCursor, ParticleCursor, StickyCursor*

### Text Effects (18)

BloomText, MorphingText, BreathingText, ParticleText, BuildingText, FrameText, SwingText, ScrambleText, VideoText, PerspectiveText, MarqueeText*, TextParallax*, SpinningText*, DisperseText*, TextAnimate*, TextMask*, TextReveal*, TerminalText*

### Effects & Footers (9)

ChromaticMouseTrail, ElectricBorder, LiquidGlass, PhotoParticle, TextStretch, FooterSimulation, RareLabsFooter, FooterLineDistortion, HeroOne

> Components marked with * require optional dependencies (see sub-paths below).

## Sub-path Exports

Heavy dependencies are isolated. Install only what you use:

```tsx
// Main import — zero optional deps needed
import { ShootingStars, BloomText, CurlyCursor } from '@rare-ui/experience';

// Three.js effects — requires: npm install three
import { CardBeam, JellyfishScene } from '@rare-ui/experience/three';

// GSAP effects — requires: npm install gsap
import { StickyCursorProvider } from '@rare-ui/experience/gsap';

// Motion effects — requires: npm install motion
import { MarqueeText, TextAnimate } from '@rare-ui/experience/motion';

// Three.js + GSAP — requires: npm install three gsap
import { MorphicBrandButton } from '@rare-ui/experience/three-gsap';
```

## Dark Mode

Inherits dark mode from `@rare-ui/core`. Set `data-theme="dark"` on `<html>` — all effects adapt automatically.

## Important Notes

- **Always set explicit height** on background effects — they don't have intrinsic height
- **CurlyCursor** renders a full-page canvas overlay — place it once at the root level
- Effects respect `prefers-reduced-motion` where applicable

## Peer Dependencies

| Package | Required |
|---------|----------|
| `react` | >= 18.0.0 |
| `react-dom` | >= 18.0.0 |
| `@rare-ui/core` | >= 0.1.0 |

## License

MIT