macos-icon-generator

Generate macOS app icons from a PNG with Apple HIG compliance. Uses SAP Icons when installed, then applies Apple safe zone (824×824) and squircle mask.

Prerequisites

1. SAP Icons

For best results, install SAP Icons:

1. Download from Releases
2. Install Icons.app to /Applications or ~/Applications
3. The icons_cli binary is bundled inside the app

2. macos-icon-gen

# navigate to MacOS-icon-generator folder
# install
uv tool install -e . --force

Usage

From any macOS project directory:

macos-icon-gen path/to/source.png -p .

Options:

• -p, --project DIR — Project directory (default: cwd)
• -o, --output DIR — AppIcon.appiconset path (auto-detected if not set)

The tool finds AppIcon.appiconset in Assets.xcassets or common Xcode layouts.

New project setup

1. Create Assets.xcassets/AppIcon.appiconset in your project (Xcode does this automatically for new apps)
2. Prepare a source PNG (1024×1024 or larger)
3. Run:

cd /path/to/your/project
macos-icon-gen path/to/icon.png -p .

Output: 16, 32, 64, 128, 256, 512, 1024 px icons in AppIcon.appiconset.

Pipeline

SAP path (if Icons.app installed): icons_cli → install.png → Apple HIG mask → sizes

Post-process: Apple HIG safe zone 824×824 (100px inset), squircle mask, radius scaled to content.

Requirements

• macOS (uses sips, swift)
• Optional: SAP Icons.app for best output