deckhearth/VISUAL_EFFECTS_GUIDE.md

# Visual Effects & 3D Card System

## 🎨 **Overview**

TCG Vault now features stunning visual effects that bring your trading cards to life with premium 3D interactions, foil shimmer effects, and rarity-based visual flair.

---

## ✨ **3D Card Tilt Effects**

### **Interactive Mouse Tracking**
- **Real-time 3D rotation** based on cursor position within card areas
- **Perspective-correct transforms** that create realistic depth
- **Smooth animations** with customizable easing curves
- **Performance optimized** with `will-change` and `transform3d` acceleration

### **Configuration**
```typescript
// Configurable tilt settings with smooth expansion
{
  maxTilt: 15,        // Maximum rotation degrees
  perspective: 1000,   // 3D perspective depth
  scale: 1.06,        // Hover scale factor (increased for premium feel)
  speed: 700,         // Animation speed in ms (slower for elegance)
  reset: true,        // Auto-reset on mouse leave
  easing: 'cubic-bezier(0.25, 0.46, 0.45, 0.94)' // Smooth organic easing
}
```

### **Size-Responsive Behavior**
- **Large cards**: 15° max tilt, 1.06× scale
- **Medium cards**: 10° max tilt, 1.03× scale  
- **Small cards**: 10° max tilt, 1.03× scale

### **Smooth Expansion System**
- **Organic Timing**: 0.6s → 0.8s gradual expansion with elegant easing curves
- **Premium Rarities**: Ultra-smooth 0.8s → 1.2s expansion for Legendary/Mythic cards
- **Mythic Enhancement**: Special 1.4s breathe-like expansion for maximum premium feel
- **Layered Animation**: Different card elements animate with subtle 0.05s delays

---

## 🌟 **Foil & Shimmer Effects**

### **Foil Cards**
Applied to: **Super Rare**, **Legendary**, and **Mythic** cards
- **Sweep shimmer**: Elegant light sweep on hover
- **Semi-transparent overlay**: Maintains card visibility
- **Performance optimized**: CSS-only animations

### **Holographic Effect**
Applied to: **Legendary** and **Mythic** cards only
- **Rainbow gradient animation**: Continuously shifting spectrum
- **Multi-layer composition**: Background holo with content preservation
- **Subtle transparency**: Maintains readability while adding premium feel

### **Foil Types by Rarity**
- **Super Rare**: Basic foil shimmer
- **Legendary**: Holographic rainbow + foil shimmer  
- **Mythic**: Holographic rainbow + foil shimmer

---

## 🌈 **Rarity Border System**

### **Color-Coded Glows**
Each rarity gets a distinctive border color and glow effect:

| Rarity | Border Color | Glow Effect | Usage |
|--------|--------------|-------------|-------|
| **Common** | Gray (`#6B7280`) | Subtle glow | Everyday cards |
| **Uncommon** | Green (`#22C55E`) | Medium glow | Notable cards |
| **Rare** | Blue (`#3B82F6`) | Bright glow | Special cards |
| **Super Rare** | Purple (`#9333EA`) | Strong glow + foil | Premium cards |
| **Legendary** | Gold (`#F59E0B`) | Intense glow + holo | Ultra-rare cards |
| **Mythic** | Red (`#EF4444`) | Max glow + holo | Legendary cards |

### **Progressive Enhancement**
- **Static**: Subtle border with light glow
- **Hover**: Enhanced glow and border brightness  
- **Animation**: Breathing glow effect for premium rarities

### **Contextual Application**
- **Card View**: Full border glow on card containers
- **Table View**: Subtle left-border accent in rows
- **Image Placeholders**: Integrated with game-themed gradients

---

## 🎮 **Interactive Behavior**

### **Mouse Events**
1. **Mouse Enter**: Activate 3D tilt tracking
2. **Mouse Move**: Update tilt angles in real-time
3. **Mouse Leave**: Smooth reset to neutral position
4. **Hover**: Enhance border glow and trigger foil effects

### **Touch Support**
- **Mobile optimized**: Reduced tilt angles for touch devices
- **Performance aware**: Smooth 60fps animations on mobile
- **Fallback graceful**: Standard hover effects where 3D isn't supported

---

## 🛠️ **Technical Implementation**

### **Custom Hook: `use3DTilt`**
```typescript
const { ref, tiltStyles, tiltState } = use3DTilt({
  maxTilt: 15,
  scale: 1.05,
  speed: 300
});
```

### **CSS Classes**
```css
/* 3D Effects */
.card-3d              // 3D container setup
.card-3d-inner        // Inner element transforms
.card-transition      // Smooth transitions

/* Foil Effects */  
.foil-card           // Basic shimmer sweep
.foil-rainbow        // Rainbow gradient animation
.holographic         // Full holographic effect

/* Rarity Borders */
.rarity-border-{rarity}    // Color-specific borders
.rarity-border-glow        // Breathing glow animation
```

### **Performance Features**
- **Hardware acceleration**: Uses `transform3d()` and `will-change`
- **Optimized animations**: 60fps with CSS transitions
- **Memory efficient**: Event cleanup on unmount
- **Battery friendly**: Animation only during interaction

---

## 🎯 **Visual Hierarchy**

### **Information Priority**
1. **3D Tilt**: Primary interaction feedback
2. **Rarity Borders**: Secondary visual classification  
3. **Foil Effects**: Premium card enhancement
4. **Holographic**: Ultra-rare card distinction

### **Accessibility**
- **Reduced motion support**: Respects `prefers-reduced-motion`
- **High contrast**: All effects maintain text readability
- **Focus indicators**: Clear keyboard navigation support
- **Screen reader**: Effects don't interfere with content

---

## 🚀 **Card Collection Experience**

### **Card View Mode**
- **Large 3D cards** with prominent tilt effects
- **Rarity glow borders** surrounding each card container
- **Foil shimmer** on premium cards during hover
- **Holographic animation** for legendary/mythic cards

### **Table View Mode**
- **Small thumbnails** with subtle 3D tilt
- **Border accent** on table rows matching rarity
- **Consistent effects** scaled appropriately for compact view

### **Placeholder Cards**
- **Game-themed gradients** as fallback for missing images
- **Full effect integration** - borders, foil, and 3D work on placeholders
- **Rarity-appropriate styling** even without card images

---

## 📊 **Effect Combinations**

### **Common Cards**
- ✅ 3D Tilt Effect
- ✅ Gray Border Glow
- ❌ No Foil Effects

### **Rare Cards** 
- ✅ 3D Tilt Effect
- ✅ Blue Border Glow
- ❌ No Foil Effects

### **Super Rare Cards**
- ✅ 3D Tilt Effect  
- ✅ Purple Border Glow
- ✅ Foil Shimmer Effect

### **Legendary Cards**
- ✅ 3D Tilt Effect
- ✅ Gold Border Glow
- ✅ Foil Shimmer Effect
- ✅ Holographic Animation

### **Mythic Cards**
- ✅ 3D Tilt Effect
- ✅ Red Border Glow  
- ✅ Foil Shimmer Effect
- ✅ Holographic Animation

---

## 🎨 **Design Philosophy**

**Progressive Enhancement**: Effects enhance the experience without overwhelming content

**Performance First**: All animations target 60fps with hardware acceleration

**Accessibility Aware**: Visual effects complement rather than replace core functionality  

**Mobile Optimized**: Reduced complexity on touch devices while maintaining premium feel

**Contextually Appropriate**: Effect intensity matches card rarity and importance

This visual effects system transforms TCG Vault from a simple database into a premium, interactive collection experience that honors the beauty and rarity of your trading cards! ✨🃏