deckhearth/GRADIENT_BORDERS_GUIDE.md

Gradient Border System with Mouse-Tracking Glow

🌈 Overview

TCG Vault now features stunning gradient borders that replace the old solid borders with dynamic, multi-colored gradients that respond to mouse movement with localized glow effects.

---

✨ Gradient Border Features

Multi-Layer Gradient Design

• Dual-background technique: Uses CSS padding-box and border-box to create clean content areas with gradient borders
• Progressive intensity: Higher rarity cards get more complex, multi-stop gradients
• Color harmony: Each rarity uses a carefully crafted color palette that transitions smoothly

Rarity-Specific Gradients

Rarity	Gradient Colors	Effect Intensity
Common	Gray (#6B7280 → #9CA3AF → #6B7280)	Subtle 2-stop gradient
Uncommon	Green (#22C55E → #4ADE80 → #22C55E)	Medium 2-stop gradient
Rare	Blue (#3B82F6 → #6366F1 → #3B82F6)	Bright 2-stop gradient
Super Rare	Purple (#9333EA → #A855F7 → #C4B5FD → #A855F7 → #9333EA)	Complex 5-stop gradient
Legendary	Gold (#F59E0B → #FBBF24 → #FEF08A → #FBBF24 → #F59E0B)	Intense 5-stop gradient
Mythic	Red (#EF4444 → #F87171 → #FECACA → #F87171 → #EF4444)	Maximum 5-stop gradient

---

🎯 Mouse-Tracking Glow System

Dynamic Glow Effect

• Real-time tracking: Mouse position is tracked at 60fps with throttling for performance
• Radial glow: 150px radius circular glow that follows the cursor within card boundaries
• Progressive opacity: Glow fades from center to edges with multiple intensity stops
• Blur enhancement: 2px blur filter creates a soft, professional glow effect

Technical Implementation

Custom Hook: useMouseGlow

const { ref, glowStyles, isHovering } = useMouseGlow({
  glowIntensity: 0.8,    // Brightness of the glow (0-1)
  glowRadius: 150,       // Size of the glow circle in pixels
  updateThrottle: 16     // Update frequency (~60fps)
});

CSS Custom Properties

--glow-x: 50%;                    /* Horizontal glow position */
--glow-y: 50%;                    /* Vertical glow position */
--glow-intensity: 0.8;            /* Glow brightness */
--rarity-shadow-color: rgba(...); /* Rarity-specific shadow color */

---

🎨 Visual Enhancement Effects

Hover Animations

• Scale transform: Cards scale up 2-3% on hover based on rarity
• Brightness filter: Enhanced brightness (1.1× - 1.2×) for premium feel
• Saturation boost: Higher rarity cards get increased color saturation
• Pulse animation: Super Rare+ cards get a breathing glow effect

Performance Optimizations

• Hardware acceleration: Uses transform3d() and will-change
• Throttled updates: Mouse tracking limited to 60fps
• Event cleanup: Proper cleanup on component unmount
• CSS-only animations: Smooth 60fps animations without JavaScript

---

🛠️ Component Architecture

GlowingCard Component

<GlowingCard rarity={card.rarity} className="card-container">
  {/* Card content */}
</GlowingCard>

Features:

• Automatic rarity detection and intensity adjustment
• Built-in mouse tracking and glow effects
• Seamless integration with existing card components
• Responsive glow radius and intensity

Rarity-Specific Intensities

• Common: 0.4 intensity - Subtle glow
• Uncommon: 0.5 intensity - Light glow
• Rare: 0.6 intensity - Medium glow
• Super Rare: 0.7 intensity - Strong glow
• Legendary: 0.8 intensity - Intense glow
• Mythic: 0.8 intensity - Maximum glow

---

💫 Advanced Effects

Pulse Animation for Premium Cards

Super Rare, Legendary, and Mythic cards feature a continuous pulse animation:

• Shadow expansion: Box shadow grows and contracts rhythmically
• 2-second cycle: Smooth, non-intrusive breathing effect
• Rarity-specific colors: Each rarity pulses with its signature color
• Hover enhancement: Pulse becomes more pronounced on hover

Multi-Layer Shadow System

box-shadow: 
  0 0 30px var(--rarity-shadow-color),  /* Inner glow */
  0 0 60px var(--rarity-shadow-color);  /* Outer glow */

---

🎮 Interactive Behavior

Mouse Enter/Leave

1. Mouse Enter: Glow effect activates and begins tracking cursor
2. Mouse Move: Glow position updates in real-time following cursor
3. Mouse Leave: Glow fades out and resets to center position

Smooth Transitions

• 0.2s opacity transitions: Glow fades in/out smoothly
• 0.3s transform transitions: Hover scaling with easing
• Continuous tracking: No lag between mouse movement and glow position

---

📱 Responsive Design

Screen Size Adaptations

• Desktop: Full 150px glow radius with maximum intensity
• Tablet: Scaled glow effects for touch interaction
• Mobile: Reduced complexity while maintaining visual appeal

Performance Considerations

• Reduced motion support: Respects prefers-reduced-motion settings
• Battery optimization: Effects pause when not visible
• GPU acceleration: Smooth 60fps on all supported devices

---

🎯 Integration Examples

Card View Mode

// Large cards with prominent gradient borders and mouse tracking
<GlowingCard rarity="Legendary" className="card-large">
  <CardImageDisplay card={card} size="large" />
  {/* Card content */}
</GlowingCard>

Table View Mode

// Table rows with subtle left-border gradient accents
<tr style={{borderLeftColor: getRarityColor(card.rarity)}}>
  {/* Table content */}
</tr>

---

🚀 Future Enhancements

Planned Features

• Gesture support: Touch-based glow interactions for mobile
• Particle effects: Floating sparkles for Mythic+ cards
• Color animation: Shifting gradient hues over time
• 3D depth: Layered glow effects with perspective

Performance Improvements

• WebGL acceleration: GPU-based glow rendering
• Intersection observer: Only animate visible cards
• Worker threads: Offload calculations from main thread

---

🎨 Design Philosophy

Visual Hierarchy: Gradient intensity reflects card rarity and importance

Performance First: All effects maintain 60fps with hardware acceleration

Accessibility Aware: Respects motion preferences and maintains readability

Progressive Enhancement: Works gracefully across all device capabilities

This gradient border system elevates the visual experience while maintaining the clean, professional aesthetic that makes TCG Vault feel premium and modern! ✨🌈🎮