💖 Romantic Animated Demo

A beautiful, interactive romantic demonstration featuring Matrix rain effects, particle systems, elegant typography, and audio integration. Created with love and modern web technologies.

✨ Features

🎭 Visual Effects

Matrix Rain Effect: Customizable falling code characters with color transitions
Particle Systems: Hearts, stars, and fireworks with physics-based animations
Text Reveal: Elegant typography with staggered animations
Shape Formations: Dynamic particle arrangements forming romantic shapes

🎵 Audio Integration

Background Music: Seamless audio playback with fade in/out effects
Lyrics Display: Synchronized text display with color transitions
Audio Controls: Volume control, play/pause, and seeking capabilities

🎨 Design & Animation

Responsive Design: Optimized for desktop, tablet, and mobile devices
Custom Animations: Framer Motion powered smooth transitions
Color Themes: Romantic pink, gold, and purple gradients
Typography: Dancing Script and Playfair Display fonts

🛠️ Technology Stack

Frontend

Next.js 15: React framework with App Router
TypeScript: Type-safe development
Tailwind CSS: Utility-first styling with custom animations
Framer Motion: Professional animation library

Libraries

Howler.js: Web audio management
Lucide React: Beautiful icons
clsx: Conditional className utility

🚀 Getting Started

Prerequisites

Node.js 18.0.0 or higher
npm, yarn, or pnpm

Installation

Clone the repository

git clone <repository-url>
cd kaysa-romantic-demo

Install dependencies

npm install
# or
yarn install
# or
pnpm install

Add background music (optional)
- Place an MP3 file in public/audio/
- Rename it to background-music.mp3
- Ensure you have proper licensing for any music files

Start development server

npm run dev
# or
yarn dev
# or
pnpm dev

Open in browser Navigate to http://localhost:3000

📁 Project Structure

kaysa-romantic-demo/
├── public/
│   ├── audio/                 # Audio files
│   └── ...                   # Static assets
├── src/
│   ├── app/                  # Next.js App Router
│   │   ├── globals.css       # Global styles
│   │   ├── layout.tsx        # Root layout
│   │   └── page.tsx          # Main page
│   ├── components/           # React components
│   │   ├── ui/              # Reusable UI components
│   │   ├── AudioController.tsx
│   │   ├── LyricsDisplay.tsx
│   │   ├── MatrixEffect.tsx
│   │   ├── ShapeFormation.tsx
│   │   └── TextReveal.tsx
│   ├── hooks/               # Custom React hooks
│   │   ├── useAnimationSequence.ts
│   │   ├── useAudio.ts
│   │   └── useParticles.ts
│   ├── types/               # TypeScript type definitions
│   │   ├── animation.ts
│   │   ├── audio.ts
│   │   └── particles.ts
│   ├── utils/               # Utility functions and classes
│   │   ├── animationHelpers.ts
│   │   ├── audioUtils.ts
│   │   └── particleSystem.ts
│   ├── data/                # Static data
│   │   ├── lyrics.ts
│   │   └── quotes.ts
│   └── lib/                 # Constants and configuration
│       └── constants.ts
├── tailwind.config.ts       # Tailwind CSS configuration
├── tsconfig.json           # TypeScript configuration
└── package.json            # Project dependencies

🎨 Customization

Colors

Edit tailwind.config.ts to customize the color palette:

colors: {
  romantic: { /* pink variations */ },
  gold: { /* gold variations */ },
  magic: { /* purple variations */ },
  matrix: '#00ff41'
}

Animation Durations

Modify timing in src/lib/constants.ts:

export const ANIMATION_DURATIONS = {
  MATRIX_EFFECT: 5000,
  SHAPE_FORMATION: 3000,
  TEXT_REVEAL: 4000,
  TRANSITION: 1000
};

Text Content

Update quotes and lyrics in:

src/data/quotes.ts - Romantic quotes and dedication message
src/data/lyrics.ts - Synchronized lyrics with timestamps

Particle Effects

Configure particle systems in src/lib/constants.ts:

export const PARTICLE_CONFIGS = {
  HEART: { count: 30, speed: { min: 0.5, max: 2 }, /* ... */ },
  STAR: { count: 25, /* ... */ },
  FIREWORKS: { count: 80, /* ... */ }
};

🎵 Audio Setup

Supported Formats: MP3 (recommended for compatibility)
File Location: public/audio/background-music.mp3
Licensing: Ensure proper licensing for any music files
Fallback: The app gracefully handles missing audio files

📱 Responsive Design

The application is optimized for:

Desktop (1200px+): Full experience with high particle counts
Tablet (768px-1199px): Reduced particles, touch-friendly controls
Mobile (<768px): Essential animations, vertical layout

🔧 Development

Available Scripts

npm run dev - Start development server
npm run build - Build for production
npm run start - Start production server
npm run lint - Run ESLint

Code Quality

TypeScript: Strict type checking enabled
ESLint: Code linting with Next.js configuration
Prettier: Code formatting (install extension recommended)

Architecture Principles

Clean Code: Modular, readable, and maintainable code
DRY (Don't Repeat Yourself): Reusable components and utilities
KISS (Keep It Simple, Stupid): Simple, focused solutions
OOP: Object-oriented particle systems and audio management

🚀 Deployment

Vercel (Recommended)

Connect repository to Vercel
Configure build settings (automatic with Next.js)
Deploy with zero configuration

Other Platforms

Netlify: Drag and drop build folder
GitHub Pages: Static export with next export
Custom Server: Use npm run start after npm run build

🐛 Troubleshooting

Common Issues

Audio not playing:

Check if background-music.mp3 exists in public/audio/
Verify file format is MP3
Check browser's autoplay policy

Performance issues:

Reduce particle counts in src/lib/constants.ts
Check hardware acceleration in browser
Monitor CPU usage with DevTools

Build errors:

Ensure all dependencies are installed
Check TypeScript errors with npm run build
Verify ESLint configuration

📄 License

This project is for personal and educational use. Ensure proper licensing for any music or media files used.

💝 Dedication

Created with love for Kaysa ✨

Note: This is a demonstration project showcasing modern web development techniques for creating romantic, interactive experiences. Feel free to customize and adapt it for your own romantic gestures!

Nerurora

Install / Use

README