# Adding New Icons to CTT Design System

## 📋 **Complete Workflow for Adding New Icons**

This guide ensures new icons are properly added to both the main design system and Storybook documentation without issues.

## 🎨 **Step 1: Prepare Icon in IcoMoon**

1. **Open your IcoMoon project**
   - Go to [IcoMoon.io](https://icomoon.io/app/)
   - Import your existing `selection.json` file (if you have one)

2. **Add new icon**
   - Upload your new SVG icon
   - Ensure it's selected (yellow highlight)
   - Give it a meaningful name

3. **Configure preferences**
   - Click ⚙️ **Preferences**
   - ✅ **Enable "Keep Codes"** (critical!)
   - Set font name to: `ctt-icons`
   - Set class prefix to: `ctt-icon-`

4. **Assign/verify codepoint**
   - Note the assigned Unicode codepoint (e.g., `e9ad`)
   - Or manually assign if needed
   - **Write down the codepoint** - you'll need it for Storybook

5. **Generate and download**
   - Click **Generate Font**
   - Download the ZIP file
   - **Save `selection.json`** for future use

## 📁 **Step 2: Update Font Files (BOTH Locations)**

### Main Assets Directory

Replace files in: `src/assets/fonts/ctt-icons/`

```
✅ ctt-icon-font.eot
✅ ctt-icon-font.ttf
✅ ctt-icon-font.woff
```

### Storybook Public Directory

Replace files in: `src/storybook/public/fonts/ctt-icons/`

```
✅ ctt-icon-font.eot
✅ ctt-icon-font.ttf
✅ ctt-icon-font.woff
```

**PowerShell command to sync:**

```powershell
Copy-Item -Path "src/assets/fonts/ctt-icons/*" -Destination "src/storybook/public/fonts/ctt-icons/" -Force
```

## 🔄 **Step 3: Cache Bust Font Loading**

### Update Storybook Fonts CSS

Edit: `src/storybook/.storybook/storybook-fonts.css`

**Increment version number:**

```css
@font-face {
  font-family: 'ctt-icons';
  src: url('/fonts/ctt-icons/ctt-icon-font.eot?v=8'); /* ← Bump version */
  src:
    url('/fonts/ctt-icons/ctt-icon-font.eot?v=8#iefix') format('embedded-opentype'),
    url('/fonts/ctt-icons/ctt-icon-font.woff?v=8') format('woff'),
    url('/fonts/ctt-icons/ctt-icon-font.ttf?v=8') format('truetype');
  /* ... */
}
```

### Update Main Assets CSS (Optional)

Edit: `src/assets/styles/icons.css`

```css
@font-face {
  font-family: 'ctt-icons';
  src: url('../fonts/ctt-icons/ctt-icon-font.eot?v=8'); /* ← Bump version */
  /* ... */
}
```

## 📚 **Step 4: Add Icon to Storybook Documentation**

### Update Icon Stories

Edit: `src/storybook/stories/DesignSystem/Icons.stories.ts`

**Add to appropriate category:**

```typescript
const iconCategories = {
  // Choose the right category:
  communication: {
    // ... existing icons
    'your-new-icon': '\\e9ad' // ← Use the codepoint from IcoMoon
  },
  actions: {
    // ... or add to actions, interface, etc.
  }
};
```

**Category Guidelines:**

- **`actions`** - User interactions (edit, delete, save, etc.)
- **`communication`** - Messaging, notifications, email, etc.
- **`interface`** - UI elements, navigation, controls
- **`ctt`** - Company/service specific icons
- **`finance`** - Money, payments, banking
- **`social`** - User profiles, social features

## 🔍 **Step 5: Generate CSS Classes (If Using)**

### Update Icons Classes CSS

If you use `icons-classes.css`, add:

```css
.ctt-icon-your-new-icon::before {
  content: '\\e9ad'; /* ← Your codepoint */
}
```

## ✅ **Step 6: Test & Verify**

### In Storybook

1. Start Storybook: `npm run storybook`
2. Navigate to: **Design System → Icons**
3. Find your icon in the appropriate category
4. Verify it displays correctly (not a blank box)
5. Test the copy button works

### Debug if Icon Shows as Blank Box

1. Go to **Design System → Icons → SmokeTest**
2. Check browser DevTools → Network → Filter by Font
3. Verify `ctt-icon-font.woff?v=X` loads with **200 OK**
4. If 404: Check file paths and copy step
5. If font loads but icon blank: Check codepoint in IcoMoon

### In Your Application

Test the icon in a real component:

```html
<i class="ctt-icon ctt-icon-your-new-icon"></i>
```

## 🚨 **Common Pitfalls to Avoid**

1. **❌ Forgetting to enable "Keep Codes"** → Icons get reassigned different codepoints
2. **❌ Only updating one font location** → Works in app but not Storybook (or vice versa)
3. **❌ Not cache busting** → Browser loads old cached font without new icon
4. **❌ Wrong category in stories** → Icon doesn't appear in expected section
5. **❌ Typo in codepoint** → `\\e9ad` vs `\\e9ad` (backslashes matter)
6. **❌ Not saving selection.json** → Can't maintain codepoints for future icons

## 📁 **File Locations Quick Reference**

```
src/
├── assets/fonts/ctt-icons/          ← Main font files
│   ├── ctt-icon-font.eot
│   ├── ctt-icon-font.ttf
│   └── ctt-icon-font.woff
├── assets/styles/
│   ├── icons.css                    ← Main font-face definition
│   └── icons-classes.css            ← CSS icon classes (optional)
└── storybook/
    ├── public/fonts/ctt-icons/      ← Storybook font files (COPY!)
    │   ├── ctt-icon-font.eot
    │   ├── ctt-icon-font.ttf
    │   └── ctt-icon-font.woff
    ├── .storybook/storybook-fonts.css  ← Cache busting versions
    └── stories/DesignSystem/Icons.stories.ts  ← Icon documentation data
```

## 🔄 **Quick Copy-Paste Checklist**

- [ ] Export from IcoMoon with "Keep Codes" enabled
- [ ] Note down the codepoint (e.g., `e9ad`)
- [ ] Replace fonts in: `src/assets/fonts/ctt-icons/`
- [ ] Replace fonts in: `src/storybook/public/fonts/ctt-icons/`
- [ ] Bump version in: `storybook-fonts.css`
- [ ] Add icon data to: `Icons.stories.ts`
- [ ] Test in Storybook → All Icons & SmokeTest
- [ ] Save `selection.json` for future use

**Happy icon adding! 🎉**