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

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

const { ref, tiltStyles, tiltState } = use3DTilt({
  maxTilt: 15,
  scale: 1.05,
  speed: 300
});

CSS Classes

/* 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! ✨🃏