---
description: Rules for migrating icons from old blocks icons to blocks-icons library
globs:
  - libs/blocks/**
  - apps/**
alwaysApply: true
---

# Icon Migration Rules - Blocks Icons Library

## Overview

This MDC provides comprehensive rules for migrating Svg icons from the old blocks icon system to the new `@chainlink/blocks-icons` library. This migration is required when upgrading to blocks v.2 and can be used across the entire repository.

## Migration Process

### Step 1: Identify Old Icon Imports

Search for old icon import patterns:

```bash
# Find old icon imports (relative paths)
grep -r "import.*Svg.*from.*\.\./.*icons" libs/blocks/
grep -r "import.*Svg.*from.*icons" libs/blocks/

# Find old icon imports (absolute paths)
grep -r "import.*Svg.*from.*@chainlink/blocks.*icons" libs/blocks/
```

### Step 2: Find Available Icons in New Library

Check available icons in the new blocks-icons library:

```bash
# Search for specific icon names in blocks-icons
grep -r "export.*SvgIconName" libs/blocks-icons/
```

### Step 3: Apply Icon Mappings

Use the established mappings below to replace old icon names with new ones.

**⚠️ IMPORTANT: Only use confirmed mappings. If an icon is not found in the new library, DO NOT make up names. Instead, report missing icons to the user for manual investigation.**

### Step 4: Update Import Statements

Replace old import statements with new ones:

```tsx
// OLD
import { SvgIconName } from '../../icons'
import { SvgIconName } from '@chainlink/blocks'

// NEW
import { SvgNewIconName } from '@chainlink/blocks-icons'
```

### Step 5: Update Icon Usage

Update all icon usages in components:

```tsx
// OLD
<SvgOldIconName />

// NEW
<SvgNewIconName />
```

## Icon Mappings

- `SvgArrowLeft1` → `SvgLineArrowLeft1`
- `SvgArrowRight1` → `SvgLineArrowRight1`
- `SvgArrowDown1` → `SvgLineArrowDown1`
- `SvgArrowUp1` → `SvgLineArrowUp1`
- `SvgTaillessArrowDown` → `SvgTaillessLineArrowDown1`
- `SvgTaillessArrowRight` → `SvgTaillessLineArrowRight1`
- `SvgTaillessArrowLeft` → `SvgTaillessLineArrowLeft1`
- `SvgTaillessArrowUp` → `SvgTaillessLineArrowUp1`
- `SvgArrowDiagonalUpperRight` → `SvgDiagonalLineArrowUpperRight`
- `SvgArrowDiagonalUpperLeft` → `SvgDiagonalLineArrowUpperLeft`
- `SvgArrowDiagonalBottomRight` → `SvgDiagonalLineArrowBottomRight`
- `SvgArrowDiagonalBottomLeft` → `SvgDiagonalLineArrowBottomLeft`
- `SvgInformationCircle` → `SvgInformationCircle` (same name)
- `SvgCog2` → `SvgCog2` (same name)
- `SvgDashboard` → `SvgDashboard1`
- `SvgHome` → `SvgHome3`
- `SvgRocket` → `SvgRocket` (same name)
- `SvgCopy` → `SvgCopy` (same name)
- `SvgTick` → `SvgCheck`
- `SvgTickCircle` → `SvgCheckCircle`
- `SvgAdd` → `SvgAdd1`
- `SvgAdd1` → `SvgAdd1` (same name)
- `SvgDelete1` → `SvgDelete1` (same name)
- `SvgEyeOptic` → `SvgVisible`
- `SvgInvisible` → `SvgInvisible1`
- `SvgInvisible1` → `SvgInvisible1` (same name)
- `SvgSettings` → `SvgCog`
- `SvgBrowserWebsite` → `SvgBrowserWebsite1`
- `SvgLogout` → `SvgLogout1`
- `SvgFileCode` → `SvgFileCode1`
- `SvgTools` → `SvgWrench`
- `SvgCoinsStack2` → `SvgCoinsStack`
- `SvgPasswordBlock` → `SvgPasswordBlock` (same name)
- `SvgUserCircleSingle` → `SvgUserCircleSingle` (same name)
- `SvgLinkShare2` → `SvgLinkShare2` (same name)
- `SvgPiSymbol` → `SvgPiSymbol` (same name)
- `IconSheet` → `IconSheet` (same name)
- `SvgXCircle` → `SvgDeleteCircle`
- `SvgWarningCircle` → `SvgWarningCircle` (same name)
- `SvgTimeLapse` → `SvgTimeLapse` (same name)
- `SvgX` → `SvgDelete1`
- `SvgClose` → `SvgDelete1`
- `SvgSearch` → `SvgMagnifyingGlass`
- `SvgHamburgerMenu` → `SvgHamburgerMenu1`

## Migration Commands

### Find All Old Icon Imports

```bash
# Find relative imports
grep -r "import.*Svg.*from.*\.\./.*icons" libs/blocks/ apps/

# Find absolute imports to old blocks
grep -r "import.*Svg.*from.*@chainlink/blocks.*icons" libs/blocks/ apps/
```

### Verify New Icons Exist

```bash
# Check if icon exists in new library
grep -r "export.*SvgIconName" libs/blocks-icons/
```

### Find Icon Usage

```bash
# Find where icons are used
grep -r "SvgIconName" libs/blocks/ apps/
```

## Migration Patterns

### Pattern 1: Same Name Icons

For icons that keep the same name, only update the import:

```tsx
// OLD
import { SvgInformationCircle } from '../../icons'

// NEW
import { SvgInformationCircle } from '@chainlink/blocks-icons'
```

### Pattern 2: Renamed Icons

For icons with new names, update both import and usage:

```tsx
// OLD
import { SvgArrowLeft1 } from '../../icons'
;<SvgArrowLeft1 />

// NEW
import { SvgLineArrowLeft1 } from '@chainlink/blocks-icons'
;<SvgLineArrowLeft1 />
```

### Pattern 3: Missing Icons - Conservative Approach

**❌ DO NOT make up icon names. If an icon is not found in the new library:**

1. **Check for name + "1" pattern** - Look for the same name with "1" suffix
2. **Leave assumption note** - Mark as assumption for user confirmation
3. **If no "1" variant found** - Leave note for manual user search

```tsx
// ✅ ASSUMPTION - Check if this is correct
// Old: SvgAdd -> New: SvgAdd1 (ASSUMPTION - user must confirm)
import { SvgAdd1 } from '@chainlink/blocks-icons'

// ❌ NO ICON FOUND - User must search manually
// Missing icon: SvgOldIconName - no equivalent found, user must search manually
```

## Validation Steps

### 1. Check Import Sources

Ensure all Svg icons are imported from `@chainlink/blocks-icons`:

```bash
grep -r "import.*Svg.*from.*@chainlink/blocks-icons" libs/blocks/ apps/
```

### 2. Verify No Old Imports Remain

Ensure no old icon imports remain:

```bash
grep -r "import.*Svg.*from.*\.\./.*icons" libs/blocks/ apps/
grep -r "import.*Svg.*from.*@chainlink/blocks.*icons" libs/blocks/ apps/
```

### 3. Check for Linting Errors

Run linting to ensure no errors were introduced:

```bash
# Check specific files
npx eslint libs/blocks/src/components/ComponentName.tsx
```

## File-Specific Migration Examples

### Component Files

```tsx
// Before
import { SvgArrowLeft1, SvgArrowRight1 } from '../../icons'

// After
import { SvgLineArrowLeft1, SvgLineArrowRight1 } from '@chainlink/blocks-icons'
```

### Story Files

```tsx
// Before
import { SvgInformationCircle } from '../../icons'

// After
import { SvgInformationCircle } from '@chainlink/blocks-icons'
```

### Documentation Files

```tsx
// Before
import { SvgArrowDiagonalUpperRight } from '../../icons'

// After
import { SvgDiagonalLineArrowUpperRight } from '@chainlink/blocks-icons'
```

## Specific Use Case Mappings

### Dropdown Menu Icons

```tsx
// Before - DropdownMenu uses down arrow
import { SvgTaillessLineArrowDown1 } from '@chainlink/blocks-icons'

// After - DropdownMenu uses right arrow
import { SvgTaillessLineArrowRight1 } from '@chainlink/blocks-icons'
```

### Password Visibility Icons

```tsx
// Before - Eye icon for password visibility
import { SvgEyeOptic } from '@chainlink/blocks-icons'

// After - Visible icon for password visibility
import { SvgVisible } from '@chainlink/blocks-icons'
```

### Home Navigation Icons

```tsx
// Before - Home icon
import { SvgHome } from '../../icons'

// After - Home3 icon
import { SvgHome3 } from '@chainlink/blocks-icons'
```

### Success State Icons

```tsx
// Before - Tick icon for success
import { SvgTick } from '../../icons'

// After - Check icon for success
import { SvgCheck } from '@chainlink/blocks-icons'

// Before - TickCircle icon for success
import { SvgTickCircle } from '../../icons'

// After - CheckCircle icon for success
import { SvgCheckCircle } from '@chainlink/blocks-icons'
```

### Add Button Icons

```tsx
// Before - Add icon
import { SvgAdd } from '../../icons'

// After - Add1 icon
import { SvgAdd1 } from '@chainlink/blocks-icons'
```

### Password Visibility Icons

```tsx
// Before - Eye and Invisible icons
import { SvgEyeOptic, SvgInvisible } from '../../icons'

// After - Visible and Invisible1 icons
import { SvgVisible, SvgInvisible1 } from '@chainlink/blocks-icons'
```

### Navigation & Interface Icons

```tsx
// Before - Settings icon
import { SvgSettings } from '../../icons'

// After - Cog icon
import { SvgCog } from '@chainlink/blocks-icons'

// Before - BrowserWebsite icon
import { SvgBrowserWebsite } from '../../icons'

// After - BrowserWebsite1 icon
import { SvgBrowserWebsite1 } from '@chainlink/blocks-icons'

// Before - Logout icon
import { SvgLogout } from '../../icons'

// After - Logout1 icon
import { SvgLogout1 } from '@chainlink/blocks-icons'
```

### File & Tool Icons

```tsx
// Before - FileCode icon
import { SvgFileCode } from '../../icons'

// After - FileCode1 icon
import { SvgFileCode1 } from '@chainlink/blocks-icons'

// Before - Tools icon
import { SvgTools } from '../../icons'

// After - Wrench icon
import { SvgWrench } from '@chainlink/blocks-icons'

// Before - CoinsStack2 icon
import { SvgCoinsStack2 } from '../../icons'

// After - CoinsStack icon
import { SvgCoinsStack } from '@chainlink/blocks-icons'
```

## Troubleshooting

### Icon Not Found in New Library

**🚨 CRITICAL: Never make up icon names. Follow this EXACT process:**

1. **Check for "Name1" pattern ONLY** - Look for the same name with "1" suffix
2. **If found, mark as ASSUMPTION** - User must confirm this is correct
3. **If not found, leave manual search note** - User must search manually
4. **DO NOT look for semantic equivalents** - Only direct name matches
5. **DO NOT look for Home2, Home3, etc.** - Only check for "1" variant

### Import Errors

1. Verify the icon exists in blocks-icons
2. Check the exact export name
3. Ensure the import path is correct: `@chainlink/blocks-icons`

### Usage Errors

1. Update all icon usages to match the new name
2. Check for any props that might have changed
3. Verify the icon renders correctly

## Future Considerations

### For Blocks v.2 Release

This migration tool will help users upgrade from blocks v.1 to v.2 by providing:

- Clear mapping documentation
- Automated migration scripts
- Validation tools
- Rollback procedures

### Adding New Mappings

When new icon mappings are discovered:

1. Add them to the mappings section above
2. Update the migration patterns
3. Test the new mappings
4. Document any special cases

## Automation Scripts

### Find and Replace Script

```bash
# Example script for automated migration
find libs/blocks/ apps/ -name "*.tsx" -o -name "*.ts" | xargs sed -i 's/import { SvgArrowLeft1 } from.*icons/import { SvgLineArrowLeft1 } from "@chainlink\/blocks-icons"/g'
```

### Validation Script

```bash
# Check for remaining old imports
if grep -r "import.*Svg.*from.*\.\./.*icons" libs/blocks/ apps/; then
  echo "❌ Old icon imports still exist"
  exit 1
else
  echo "✅ All icons migrated successfully"
fi
```

## Handling Missing Icons

### When an Icon is Not Found

**Step 1: Check for "Name1" Pattern ONLY**

```bash
# Check if there's a "1" variant of the same name
grep -r "export.*SvgIconName1" libs/blocks-icons/
```

**Step 2A: If "Name1" Found - Mark as Assumption**

```tsx
// ASSUMPTION: Old SvgIconName -> New SvgIconName1 (user must confirm)
import { SvgIconName1 } from '@chainlink/blocks-icons'
```

**Step 2B: If "Name1" NOT Found - Leave Manual Search Note**

```tsx
// MANUAL SEARCH REQUIRED: SvgOldIconName not found
// User must search blocks-icons library manually
// No "Name1" variant found
```

**Step 3: User Confirmation Required**

- User must verify the assumption is correct
- User must search manually if no "Name1" found
- User must update mappings when confirmed

## Best Practices

1. **Never guess icon names** - Always verify icons exist in blocks-icons
2. **Report missing icons** - Let users know what needs manual investigation
3. **Document new mappings** - Add confirmed mappings to the rules
4. **Test after migration** - Ensure icons render correctly
5. **Maintain consistency** - Use the same icon for the same functionality across the app
6. **Validate imports** - Ensure all imports are from the correct library

## Common Pitfalls

1. **❌ Making up icon names** - Never guess or invent icon names
2. **Case sensitivity** - Icon names are case-sensitive
3. **Import paths** - Always use `@chainlink/blocks-icons`
4. **Missing icons** - Report missing icons instead of guessing
5. **Props changes** - Some icons might have different prop interfaces
6. **Bundle size** - Import only the icons you need

---

_This document should be updated as new icon mappings are discovered and tested._