---
name: ios-icon-gen
description: Create PNG image sets for Xcode asset catalogs from SF Symbols or Iconify. Use it to find icons, match an iOS or macOS project style, replace test icons, or make 1x, 2x, and 3x assets.
origin: community
---

# iOS Icon Generator

> Community skill. Full credit goes to the original open-source author and project.

Create Xcode PNG image sets from two icon sources:

- SF Symbols for an Apple look
- Iconify for a wide range of open-source icons

This skill makes image sets for use inside an app. It does not make the main home screen app icon.

## When to Use This Skill

Use this skill when you need to:

- Add an icon to an iOS or macOS project
- Find an icon for a clear idea or task
- Make 1x, 2x, and 3x PNG files
- Replace a test icon
- Match icons already used in a project

## Pick a Source

| Source | Needs | Best for |
|---|---|---|
| Iconify | Internet access | More styles and open-source sets |
| SF Symbols | macOS and Apple tools | Icons that match Apple screens |

Use SF Symbols when the icon should feel like part of iOS.

Use Iconify when SF Symbols has no good match or the project uses another icon style.

Check the icon license before shipping an Iconify icon. Each set may have its own rules.

## Check the Project First

Before you make an icon:

1. Find a similar icon in the project.
2. Check its pixel size.
3. Check its color.
4. Check if it is filled or drawn with lines.
5. Check how much empty space it has.
6. Use the same style for the new icon.

Check a PNG size on macOS:

```bash
sips -g pixelWidth -g pixelHeight path/to/existing@2x.png
```

If the project uses named colors, use the matching color value. Do not guess.

## Output

Both tools make this folder:

```text
<output-dir>/<asset-name>.imageset/
  Contents.json
  <asset-name>.png
  <asset-name>@2x.png
  <asset-name>@3x.png
```

The default point size is 68:

- 1x is 68 by 68 pixels
- 2x is 136 by 136 pixels
- 3x is 204 by 204 pixels

Do not replace an image set with the same name unless the user wants that change.

Use a safe asset name. Use letters, numbers, and underscores. Do not use `/`, `:`, or spaces.

## Find an Icon

### Iconify

Search all sets:

```bash
$SKILL_DIR/scripts/iconify_gen.sh search "receipt"
```

Search one set:

```bash
$SKILL_DIR/scripts/iconify_gen.sh search "business card" --prefix mdi
```

List sets:

```bash
$SKILL_DIR/scripts/iconify_gen.sh collections
```

Preview an icon:

```bash
$SKILL_DIR/scripts/iconify_gen.sh preview mdi:receipt-text-outline
```

A valid Iconify name has this form:

```text
set:icon-name
```

If search gives no result, try a shorter word or a close word. For example, try `bill`, `invoice`, or `document` instead of `expense report`.

If the network fails, stop and report the error. Do not make up an icon name.

### SF Symbols

Use the SF Symbols app when it is present. You may also try a known symbol name.

| Need | Symbol names |
|---|---|
| Document | `doc.text`, `doc.fill` |
| Receipt | `doc.text.below.ecg`, `receipt` |
| Person | `person.crop.rectangle`, `person.text.rectangle` |
| Camera | `camera`, `camera.fill` |
| Scan | `doc.viewfinder`, `qrcode.viewfinder` |
| Settings | `gearshape`, `slider.horizontal.3` |

Symbol names and support can change by OS version. Make sure the target OS can use the chosen symbol.

If a symbol name is not found, stop and pick another real symbol. Do not ship a blank image.

## Make the Image Set

### Iconify

Basic use:

```bash
$SKILL_DIR/scripts/iconify_gen.sh mdi:receipt-text-outline editTool_expenseReport
```

Set the color and output folder:

```bash
$SKILL_DIR/scripts/iconify_gen.sh mdi:receipt-text-outline expenseReceipt \
  --color 007AFF \
  --output ./MyApp/Assets.xcassets/Icons
```

Options:

- `--size <pt>`: Point size. Default is `68`.
- `--color <hex>`: Six-digit hex color. Default is `8E8E93`.
- `--output <dir>`: Output folder. Default is `/tmp/icons`.

Use hex with no `#`. For example, use `007AFF`, not `#007AFF`.

### SF Symbols

Basic use:

```bash
swift $SKILL_DIR/scripts/generate_icons.swift \
  doc.text.below.ecg \
  editTool_expenseReport
```

Set the color, line weight, and output folder:

```bash
swift $SKILL_DIR/scripts/generate_icons.swift \
  person.crop.rectangle \
  profileCard \
  --color 007AFF \
  --weight regular \
  --output ./MyApp/Assets.xcassets/Icons
```

Options:

- `--size <pt>`: Point size. Default is `68`.
- `--color <hex>`: Six-digit hex color. Default is `8E8E93`.
- `--weight <name>`: Symbol weight. Default is `thin`.
- `--output <dir>`: Output folder. Default is `/tmp/icons`.

Use a weight that the script and SF Symbols support. If a weight fails, use `regular`.

## Full Example

Goal: Add a blue receipt icon named `expenseReceipt` to an app.

1. Check a current 2x icon:

```bash
sips -g pixelWidth -g pixelHeight \
  ./MyApp/Assets.xcassets/Icons/editIcon.imageset/editIcon@2x.png
```

2. Search for a receipt:

```bash
$SKILL_DIR/scripts/iconify_gen.sh search "receipt" --prefix mdi
```

3. Preview the chosen icon:

```bash
$SKILL_DIR/scripts/iconify_gen.sh preview mdi:receipt-text-outline
```

4. Make the image set:

```bash
$SKILL_DIR/scripts/iconify_gen.sh mdi:receipt-text-outline expenseReceipt \
  --size 68 \
  --color 007AFF \
  --output ./MyApp/Assets.xcassets/Icons
```

5. Open `expenseReceipt@2x.png` and check it.

6. Build the app in Xcode.

7. Confirm the icon is sharp, centered, and not cut off.

## Add a Set Made in `/tmp`

If you did not write to the asset catalog, copy the full image set:

```bash
cp -r \
  /tmp/icons/expenseReceipt.imageset \
  ./MyApp/Assets.xcassets/Icons/
```

Check that the target folder exists first. Check for an image set with the same name before copying.

## Final Checks

Before you finish:

1. Open the 2x PNG.
2. Make sure the icon is centered.
3. Make sure no line or edge is cut off.
4. Make sure all three PNG files exist.
5. Make sure `Contents.json` exists.
6. Make sure file names in `Contents.json` match the PNG files.
7. Make sure the PNG files have the right pixel sizes.
8. Build the project in Xcode.
9. Check the icon on both light and dark screens.
10. Check the Iconify set license if Iconify was used.

If the icon looks too small, do not raise the file size at once. First compare its empty space with nearby icons.

If a one-color icon must change with the app theme, check if the project expects a template image. PNG color alone will not set the Xcode render mode.

## Common Iconify Sets

| Prefix | Set | Style |
|---|---|---|
| `mdi` | Material Design Icons | Filled and line icons |
| `ph` | Phosphor | Many line weights |
| `solar` | Solar | Bold and line icons |
| `tabler` | Tabler Icons | Even line width |
| `lucide` | Lucide | Clean line icons |
| `ri` | Remix Icon | Filled and line icons |
| `carbon` | Carbon | IBM style |
| `heroicons` | Heroicons | Filled and line icons |

## Scripts

| Script | Source |
|---|---|
| `$SKILL_DIR/scripts/iconify_gen.sh` | Iconify |
| `$SKILL_DIR/scripts/generate_icons.swift` | SF Symbols |

Before use, make sure the script file exists. SF Symbols work only on macOS with the needed Apple tools.

## Avoid These Errors

- Do not make an icon before checking the project style.
- Do not use the default gray when the project has its own color.
- Do not guess the size.
- Do not mix filled icons with line icons without a clear reason.
- Do not mix line weights.
- Do not overwrite an old image set by mistake.
- Do not trust a made-up icon or symbol name.
- Do not commit an icon before viewing it.
- Do not use these image sets as the main home screen app icon.
- Do not ship an Iconify icon before checking its license.