veza/apps/web/docs/HOVER_EFFECTS_AUDIT.md

# Hover Effects Audit - Action 11.4.1.1

**Date**: 2025-01-27  
**Scope**: All `hover:` usage across the codebase  
**Total Instances**: 887 matches across 239 files

## Summary

Hover effects are used extensively throughout the application. This audit categorizes usage to identify opportunities for refinement and applying "Surgical Minimalism" principles.

## Categories

### 1. Necessary Hover Effects (✅ Keep)
**Purpose**: Essential interactive feedback for buttons, links, and clickable elements  
**Count**: ~400 instances (estimated 45%)

**Patterns**:
- `hover:bg-white/5` - Subtle background for interactive elements
- `hover:bg-accent` - Background change for buttons/links
- `hover:text-white` - Text color change for navigation
- `hover:opacity-100` - Icon visibility on hover
- `hover:border-*` - Border color changes for interactive elements
- `hover:underline` - Link underline on hover

**Examples**:
- Button variants (primary, secondary, outline, ghost)
- Navigation links and menu items
- Clickable cards and list items
- Icon buttons
- Form inputs and selects

**Files**:
- `apps/web/src/components/ui/button.tsx` - Button variants
- `apps/web/src/components/layout/Sidebar.tsx` - Navigation items
- `apps/web/src/components/layout/Navbar.tsx` - Nav links
- `apps/web/src/components/ui/select.tsx` - Select options
- `apps/web/src/components/data/List.tsx` - List items

### 2. Excessive/Decorative Hover Effects (⚠️ Review/Remove)
**Purpose**: Decorative animations, scale transforms, multiple simultaneous effects  
**Count**: ~200 instances (estimated 23%)

**Patterns**:
- `hover:scale-[1.02]` or `hover:scale-110` - Scale transforms
- `hover:shadow-*` - Shadow effects (especially neon/glow)
- `hover:rotate-*` - Rotation transforms
- `hover:translate-*` - Translation transforms
- Multiple simultaneous effects (scale + shadow + color)

**Examples**:
- Card scale on hover: `hover:scale-[1.02]`
- Image zoom on hover: `group-hover:scale-110`
- Shadow glow effects: `hover:shadow-neon-cyan/20`
- Button scale: `hover:scale-110`

**Files**:
- `apps/web/src/components/marketplace/ProductCard.tsx` - Card scale + shadow
- `apps/web/src/components/education/CourseCard.tsx` - Card scale
- `apps/web/src/components/social/PostCard.tsx` - Multiple effects
- `apps/web/src/features/tracks/components/TrackCard.tsx` - Scale transform
- `apps/web/src/components/ui/button.tsx` - Some button variants with scale

### 3. Group Hover Effects (⚠️ Review Context)
**Purpose**: Effects triggered by parent hover (e.g., card hover shows child elements)  
**Count**: ~150 instances (estimated 17%)

**Patterns**:
- `group-hover:opacity-100` - Show elements on parent hover
- `group-hover:scale-*` - Scale child on parent hover
- `group-hover:bg-*` - Background change on parent hover

**Examples**:
- Card hover reveals play button overlay
- Image zoom on card hover
- Show action buttons on row hover

**Files**:
- `apps/web/src/components/marketplace/ProductCard.tsx` - Play button overlay
- `apps/web/src/components/player/FullPlayer.tsx` - Overlay on hover
- `apps/web/src/components/views/DiscoverView.tsx` - Play icon on hover

### 4. Transition/Animation Effects (⚠️ Review)
**Purpose**: Smooth transitions for hover state changes  
**Count**: ~100 instances (estimated 11%)

**Patterns**:
- `transition-all` - All properties transition
- `transition-colors` - Color transitions
- `transition-opacity` - Opacity transitions
- `transition-transform` - Transform transitions
- `duration-*` - Transition duration

**Examples**:
- `transition-all duration-200` - Smooth hover transitions
- `transition-opacity` - Fade in/out effects

**Files**:
- Most components with hover effects include transitions

### 5. Opacity-Based Hover (✅ Keep - Subtle)
**Purpose**: Subtle visibility changes for icons and overlays  
**Count**: ~37 instances (estimated 4%)

**Patterns**:
- `hover:opacity-100` - Full opacity on hover
- `opacity-0 hover:opacity-100` - Show on hover
- `opacity-70 hover:opacity-100` - Increase opacity

**Examples**:
- Icon buttons that become fully visible on hover
- Overlay elements that appear on hover
- Close buttons in modals

**Files**:
- `apps/web/src/components/ui/alert.tsx` - Close button
- `apps/web/src/components/player/FullPlayer.tsx` - Overlay elements
- `apps/web/src/components/ui/ErrorDisplay.tsx` - Action buttons

## Detailed Analysis

### Scale Transforms (Excessive)
**Count**: ~50 instances

**Examples**:
```tsx
// ProductCard.tsx
className="... hover:scale-[1.02] ..."

// TrackCard.tsx  
className="... hover:scale-[1.02] ..."

// Button play overlay
className="... hover:scale-110 ..."
```

**Recommendation**: Remove scale transforms on cards. Keep only for small icon buttons where scale provides clear feedback.

### Shadow/Glow Effects (Excessive)
**Count**: ~30 instances

**Examples**:
```tsx
// ProductCard.tsx
className="... hover:shadow-neon-cyan/20 ..."

// Button variants
className="... hover:shadow-[0_0_15px_rgba(102,252,241,0.3)] ..."
```

**Recommendation**: Remove decorative shadow/glow effects. Keep only subtle shadows for elevation feedback on buttons.

### Multiple Simultaneous Effects (Excessive)
**Count**: ~40 instances

**Examples**:
```tsx
// ProductCard.tsx
className="... hover:border-kodo-cyan/50 hover:shadow-neon-cyan/20 hover:scale-[1.02] ..."

// CourseCard.tsx
className="... hover:bg-white/5 hover:scale-[1.02] hover:shadow-lg ..."
```

**Recommendation**: Limit to one primary hover effect per element. Prefer subtle background or border changes over multiple effects.

### Group Hover Patterns (Review Context)
**Count**: ~150 instances

**Examples**:
```tsx
// ProductCard.tsx - Play button overlay
<div className="opacity-0 group-hover:opacity-100 ...">
  <PlayButton />
</div>

// Image zoom
<img className="... group-hover:scale-110 ..." />
```

**Recommendation**: 
- ✅ Keep: Play button overlays (functional, reveals action)
- ⚠️ Review: Image zoom effects (decorative, could be removed)
- ✅ Keep: Action button reveals on row hover (functional)

## Recommendations

### High Priority (Action 11.4.1.3)
1. **Remove scale transforms from cards**
   - ProductCard, CourseCard, TrackCard, PostCard
   - Replace with subtle background change only

2. **Remove decorative shadow/glow effects**
   - `hover:shadow-neon-cyan/20` on cards
   - Keep only subtle shadows on buttons

3. **Simplify multiple simultaneous effects**
   - Limit to one primary hover effect
   - Prefer `hover:bg-white/5` over scale + shadow + border

### Medium Priority
4. **Review group hover image zoom**
   - Consider removing `group-hover:scale-110` on images
   - Keep functional overlays (play buttons)

5. **Standardize transition durations**
   - Use consistent `duration-200` for all hover effects
   - Avoid `transition-all` (prefer specific properties)

### Low Priority
6. **Maintain necessary hover effects**
   - Keep all button, link, and navigation hover states
   - Keep opacity-based icon visibility
   - Keep border color changes for interactive elements

## Target Distribution (Surgical Minimalism)

**Current**: ~887 hover effects across 239 files  
**Target**: Reduce by ~30-40% (remove excessive decorative effects)

**Breakdown**:
- **Keep** (~60%): Interactive feedback (buttons, links, navigation, clickable elements)
- **Remove** (~30%): Decorative effects (scale, excessive shadows, multiple simultaneous effects)
- **Review** (~10%): Group hover effects (keep functional, remove decorative)

## Files Requiring Changes

### High Impact (Many excessive effects):
1. `apps/web/src/components/marketplace/ProductCard.tsx` - Scale + shadow + border
2. `apps/web/src/components/education/CourseCard.tsx` - Scale + shadow
3. `apps/web/src/components/social/PostCard.tsx` - Multiple effects
4. `apps/web/src/features/tracks/components/TrackCard.tsx` - Scale transform
5. `apps/web/src/components/views/DiscoverView.tsx` - Image zoom on hover
6. `apps/web/src/components/player/FullPlayer.tsx` - Multiple overlay effects

### Medium Impact:
- All card components with scale transforms
- Components with decorative shadow effects
- Components with multiple simultaneous hover effects

## Detailed File-by-File Categorization

### Files with Excessive Hover Effects (Remove)

#### High Priority - Multiple Excessive Effects
1. **`apps/web/src/components/marketplace/ProductCard.tsx`**
   - ❌ `hover:border-kodo-cyan/50` + `hover:shadow-neon-cyan/20` (multiple effects)
   - ❌ `group-hover:scale-110` on image (decorative zoom)
   - ❌ `hover:scale-110` on play button (excessive for button)
   - ✅ `group-hover:opacity-100` on play overlay (keep - functional)

2. **`apps/web/src/components/education/CourseCard.tsx`**
   - ❌ `group-hover:scale-110` on image (decorative zoom)
   - ⚠️ Review: `group-hover:opacity-100` (functional overlay)

3. **`apps/web/src/features/tracks/components/TrackCard.tsx`**
   - ❌ `hover:scale-[1.02]` on card (decorative scale)
   - ❌ `group-hover:scale-105` on image (decorative zoom)
   - ❌ `hover:scale-110` on play button (excessive)
   - ✅ `hover:bg-accent/50` (keep - necessary feedback)

4. **`apps/web/src/components/social/PostCard.tsx`**
   - Multiple excessive effects (needs review)

5. **`apps/web/src/components/inventory/EquipmentCard.tsx`**
   - ❌ `hover:shadow-lg` (decorative shadow)
   - ❌ `group-hover:scale-110` on image (decorative zoom)

6. **`apps/web/src/components/views/ProfileView.tsx`**
   - ❌ `group-hover:scale-110` on images (decorative zoom, 3 instances)
   - ❌ `group-hover:scale-105` on images (decorative zoom)

#### Medium Priority - Single Excessive Effect
7. **`apps/web/src/pages/SearchPage.tsx`**
   - ❌ `hover:shadow-lg` on cards (4 instances - decorative)

8. **`apps/web/src/components/player/PlayerControls.tsx`**
   - ❌ `hover:scale-110` on icons (excessive, 2 instances)
   - ❌ `hover:scale-105` + `hover:shadow-[0_0_15px_rgba(255,255,255,0.5)]` (multiple effects)

9. **`apps/web/src/components/ui/card.tsx`**
   - ❌ `hover:shadow-lg` (decorative shadow)
   - ⚠️ `hover-lift` class (needs review - likely scale transform)

10. **`apps/web/src/components/commerce/OrderSummary.tsx`**
    - ❌ `hover:shadow-lg hover:shadow-kodo-cyan/20` (decorative glow)

11. **`apps/web/src/components/views/DiscoverView.tsx`**
    - ❌ `group-hover:scale-105` on images (2 instances - decorative zoom)
    - ❌ `hover:scale-105` on genre cards (decorative)

12. **`apps/web/src/features/playlists/components/PlaylistCard.tsx`**
    - ❌ `hover:shadow-lg` (decorative shadow)

### Files with Necessary Hover Effects (Keep)

#### Interactive Elements
- **`apps/web/src/components/ui/button.tsx`** - All variants (necessary feedback)
- **`apps/web/src/components/layout/Sidebar.tsx`** - Navigation items (necessary)
- **`apps/web/src/components/layout/Navbar.tsx`** - Nav links (necessary)
- **`apps/web/src/components/ui/select.tsx`** - Options (necessary)
- **`apps/web/src/components/data/List.tsx`** - Clickable items (necessary)
- **`apps/web/src/components/ui/dropdown-menu.tsx`** - Menu items (necessary)
- **`apps/web/src/components/ui/table.tsx`** - Sortable headers (necessary)

#### Functional Overlays
- **`apps/web/src/components/marketplace/ProductCard.tsx`** - Play button overlay (functional)
- **`apps/web/src/components/player/FullPlayer.tsx`** - Control overlays (functional)
- **`apps/web/src/components/views/DiscoverView.tsx`** - Play icon on hover (functional)

### Files with Mixed Effects (Selective Removal)

1. **`apps/web/src/components/layout/Sidebar.tsx`**
   - ✅ `hover:bg-white/5` (keep - necessary)
   - ❌ `group-hover:scale-110` on icons (excessive - remove)

2. **`apps/web/src/components/player/PlayerControls.tsx`**
   - ✅ `hover:text-white` (keep - necessary)
   - ❌ `hover:scale-110` (remove - excessive)

3. **`apps/web/src/components/ui/button.tsx`**
   - ✅ All hover states (keep - necessary)
   - ⚠️ `hover:shadow-[0_0_15px_rgba(102,252,241,0.3)]` on default variant (review - could be excessive)

## Categorization Summary

### ✅ Keep (Necessary) - ~400 instances
- Button hover states (all variants)
- Navigation link hover states
- Clickable card/list item hover states
- Form input/select hover states
- Functional overlays (play buttons, action reveals)
- Icon button hover states
- Opacity-based visibility changes

### ❌ Remove (Excessive) - ~200 instances
- Scale transforms on cards (`hover:scale-[1.02]`, `hover:scale-110`)
- Decorative shadow/glow effects (`hover:shadow-neon-cyan/20`, `hover:shadow-lg`)
- Image zoom effects (`group-hover:scale-110`, `group-hover:scale-105`)
- Multiple simultaneous effects (scale + shadow + border)
- Scale on icon buttons (except small icon-only buttons)

### ⚠️ Review (Context-Dependent) - ~150 instances
- Group hover image zooms (remove decorative, keep functional overlays)
- Button shadow effects (keep subtle, remove glow)
- Transition durations (standardize to `duration-200`)

## Next Steps

1. ✅ **Action 11.4.1.1**: Audit complete
2. ✅ **Action 11.4.1.2**: Categorization complete (detailed file-by-file breakdown)
3. ⏭️ **Action 11.4.1.3**: Remove excessive hover effects

## Notes

- This audit is based on pattern matching and may require manual review for context-specific decisions
- Some decorative effects may be intentional for brand consistency
- Interactive feedback (buttons, links) should always have hover states
- Group hover effects that reveal functionality (play buttons) should be kept
- Scale transforms and decorative shadows should be removed for "Surgical Minimalism"