# Universal Icon System - Design

## Architecture

```
Icon System
├── Icon Component (centralized wrapper)
│   ├── Size variants: sm, md, lg, xl
│   ├── Color: inherited or explicit
│   └── Accessibility: aria-label, role
├── Icon Registry (mapping names to Phosphor icons)
└── Usage throughout app
    ├── Navigation icons
    ├── Action icons
    ├── Status indicators
    └── Git operation icons
```

## Component Design

### Icon Component

**Props:**
```typescript
interface IconProps {
  name: IconName;
  size?: "sm" | "md" | "lg" | "xl";
  color?: string;
  weight?: "thin" | "light" | "regular" | "bold" | "fill" | "duotone";
  className?: string;
  ariaLabel?: string;
}
```

**Size Mapping:**
- sm: 16px
- md: 20px (default)
- lg: 24px
- xl: 32px

**Color:**
- Default: inherits from parent via `currentColor`
- Explicit: uses CSS variable or direct color value

### Icon Registry

**Categories:**

Navigation:
- `home` - Dashboard
- `projects` - Projects list
- `repositories` - Git repositories
- `settings` - User settings
- `profile` - User profile

Actions:
- `add` - Create new
- `edit` - Edit item
- `delete` - Delete item
- `save` - Save changes
- `cancel` - Cancel action
- `refresh` - Refresh/reload
- `copy` - Copy to clipboard

Status:
- `success` - Checkmark
- `error` - X mark
- `warning` - Warning triangle
- `info` - Information circle
- `loading` - Spinner

Git Operations:
- `branch` - Git branch
- `commit` - Git commit
- `merge` - Merge branches
- `history` - Commit history
- `pull` - Pull changes
- `push` - Push changes

Files:
- `file` - Generic file
- `folder` - Directory
- `code` - Code file
- `document` - Text document

## Migration Plan

### Phase 1: Setup
1. Install `@phosphor-icons/react`
2. Create `Icon` component
3. Create icon registry mapping

### Phase 2: Replace Raw Unicode
Replace all instances of raw Unicode symbols:
- `✓` → `Icon name="check"`
- `✗` → `Icon name="x"`
- `⚠` → `Icon name="warning"`
- `●` → `Icon name="dot"`
- `❓` → `Icon name="question"`
- `↓` → `Icon name="arrow-down"`

### Phase 3: Update Components
Update existing components to use icon system:
- GitToolbar
- GitRepositoriesPage
- FileEditor
- AppShell navigation
- Dialog buttons
- Form validation indicators

### Phase 4: Styling
- Ensure consistent spacing around icons
- Add hover states where applicable
- Maintain alignment with text

## Accessibility

- All icons have meaningful `aria-label`
- Decorative icons use `aria-hidden="true"`
- Focus indicators for interactive icons
- Sufficient color contrast

## Technical Details

**Library:** `@phosphor-icons/react`
**Bundle Impact:** Tree-shakeable, ~2KB per icon used
**Browser Support:** All modern browsers
**Fallback:** None needed - SVG-based, always renders

## CSS Integration

```css
.icon {
  display: inline-flex;
  align-items: center;
  justify-content: center;
  flex-shrink: 0;
}

.icon-sm { width: 16px; height: 16px; }
.icon-md { width: 20px; height: 20px; }
.icon-lg { width: 24px; height: 24px; }
.icon-xl { width: 32px; height: 32px; }

/* Inherit color from parent */
.icon svg {
  fill: currentColor;
}
```