veza/apps/web/docs/BUTTON_VARIANT_USAGE_AUDIT.md

# Button Variant Usage Audit

**Date**: 2025-01-27  
**Action**: 9.3.1.1 - Audit button variant usage  
**Purpose**: Identify usage count for each button variant to determine which variants can be removed

## Summary

- **Design System Button Location**: `apps/web/src/components/ui/button.tsx`
- **Legacy Button Location**: `apps/web/src/components/base/Button.tsx` (different API)
- **Total Variants in Design System**: 9 variants
- **Variants Actually Used**: 5 variants
- **Variants Unused**: 4 variants

## Design System Button Variants

### Available Variants (9 total)

1. **default** - Primary button with cyan background
2. **destructive** - Red variant for destructive actions
3. **outline** - Outlined button
4. **secondary** - Secondary button with steel background
5. **ghost** - Minimal button with hover effect
6. **link** - Link-style button
7. **neon** - Neon effect button
8. **glass** - Glass morphism effect
9. **premium** - Premium gradient button

## Usage Statistics

### Variants in Use

| Variant | Usage Count | Percentage | Status |
|---------|-------------|------------|--------|
| **ghost** | 71 | 54.2% | ✅ Most popular |
| **outline** | 36 | 27.5% | ✅ Common |
| **secondary** | 13 | 9.9% | ✅ Used |
| **default** | 4 | 3.1% | ✅ Used (default variant) |
| **destructive** | 4 | 3.1% | ✅ Used |
| **TOTAL USED** | **128** | **97.7%** | |

### Variants Unused

| Variant | Usage Count | Status |
|---------|-------------|--------|
| **neon** | 0 | ❌ Unused - Can be removed |
| **glass** | 0 | ❌ Unused - Can be removed |
| **premium** | 0 | ❌ Unused - Can be removed |
| **link** | 0 | ❌ Unused - Can be removed |

### Legacy Button Variant Usage

| Variant | Usage Count | Notes |
|---------|-------------|-------|
| **primary** | 28 | ⚠️ Legacy Button component variant (not design system) |

**Note**: The `variant="primary"` usage (28 instances) refers to the legacy Button component in `components/base/Button.tsx`, which has a different API. These should be migrated to the design system Button with `variant="default"`.

## Analysis

### Most Popular Variants
1. **ghost** (71 uses) - Most common, used for icon buttons, close buttons, and subtle actions
2. **outline** (36 uses) - Common for secondary actions and form buttons
3. **secondary** (13 uses) - Used for less prominent actions

### Least Used Variants
- **default** (4 uses) - Despite being the default, it's rarely explicitly specified
- **destructive** (4 uses) - Used for delete/destructive actions

### Unused Variants
- **neon**, **glass**, **premium**, **link** - Zero usage across the codebase
- These variants can be safely removed without breaking changes

## Recommendations

### High Priority: Remove Unused Variants
The following variants have **zero usage** and can be removed:
1. **neon** - No usage found
2. **glass** - No usage found
3. **premium** - No usage found
4. **link** - No usage found

**Impact**: No breaking changes (zero usage)

### Medium Priority: Keep Core Variants
Based on usage patterns, the following variants should be kept:
1. **default** - Default variant (even if rarely explicit)
2. **outline** - 36 uses (27.5%)
3. **ghost** - 71 uses (54.2%)
4. **destructive** - 4 uses (needed for delete actions)
5. **secondary** - 13 uses (9.9%)

**Note**: The task specifies keeping only `default`, `outline`, and `ghost`. However, `destructive` and `secondary` are also in use. This should be reviewed.

### Low Priority: Migrate Legacy Buttons
- 28 instances using `variant="primary"` from legacy Button component
- Should be migrated to design system Button with `variant="default"`

## Migration Strategy

### Phase 1: Remove Unused Variants (Action 9.3.1.2)
- Remove: `neon`, `glass`, `premium`, `link`
- **Risk**: LOW (zero usage)
- **Breaking Changes**: None

### Phase 2: Review Secondary and Destructive
- **secondary**: 13 uses - Consider if these can be replaced with `outline`
- **destructive**: 4 uses - Consider if these can be replaced with `default` + red styling
- **Decision needed**: Keep or remove these variants

### Phase 3: Simplify Remaining Variants (Action 9.3.1.4)
- Remove excessive glows from `default` variant
- Simplify shadow effects

## Files to Review

### Files Using Unused Variants
- None (all unused variants have zero usage)

### Files Using Secondary Variant (13 uses)
- Review if these can be replaced with `outline`

### Files Using Destructive Variant (4 uses)
- Review if these can be replaced with `default` + custom styling

## Next Steps

1. ✅ Audit complete (Action 9.3.1.1)
2. ⏳ Remove unused variants: neon, glass, premium, link (Action 9.3.1.2)
3. ⏳ Decide on secondary and destructive variants
4. ⏳ Replace removed variants with default/outline/ghost (Action 9.3.1.3)
5. ⏳ Remove excessive glows from remaining variants (Action 9.3.1.4)

## Notes

- The design system Button has 9 variants, but only 5 are actually used
- 4 variants (neon, glass, premium, link) have zero usage and can be safely removed
- The most popular variant is `ghost` (54.2% of all variant usage)
- Legacy Button component still has 28 uses with `variant="primary"` - these should be migrated separately