English · 中文

macicon — macOS Icon Generator

macicon is a command-line tool for generating and preparing macOS icon assets. It applies a 13/16 design area and a 22% corner radius to square SVG, PNG, or JPEG artwork, producing a single icon PNG, .iconset, .icns, and AppIcon.appiconset resources. It can also validate and organize layered artwork for Apple Icon Composer. Its processing rules follow Apple’s Human Interface Guidelines, App icons, and Apple Design Resources.

Installation

Install with Homebrew:

brew install sundegan/tap/macicon

Features and usage

macicon supports two icon workflows: creating traditional macOS icon resources from a single source image, and validating and organizing layered artwork for Apple Icon Composer.

Command	Output	Use
create	A single flattened macOS icon	Generate a flattened macOS icon from one source image
iconset	.iconset directory	Traditional macOS icon resources and input for iconutil
icns	.icns and .iconset	Traditional macOS app bundle icon
appiconset	AppIcon.appiconset	Legacy Xcode Asset Catalog
validate	Validation report	Check Icon Composer layers
prepare (stage alias)	Layer directory	Organize assets for import into Icon Composer

Create icon resources from one source image

create writes a single icon with transparent margins and rounded corners. Its default geometry uses a 13/16 design area with a corner radius of 22% of that area. It accepts any square input size and scales it to the requested output geometry, the default output canvas is 1024x1024.

macicon create path/to/source.png --output path/to/icon.png

To create an .iconset, .icns, or Xcode AppIcon.appiconset, use the corresponding command:

macicon iconset path/to/source.png --output path/to/AppIcon.iconset
macicon icns path/to/source.png --output path/to/AppIcon.icns
macicon appiconset path/to/source.png \
  --output path/to/AppIcon.appiconset

All static exports are downsampled from the same 1024x1024 master image. Existing output is not overwritten unless --force is supplied. Adjust create geometry with --canvas-size, --content-size, --radius, or the ratio options.

Prepare layers for Apple Icon Composer

For new macOS apps, provide unmasked square layers: one complete, opaque background plus zero or more foreground layers, which may have transparent regions.

macicon validate \
  --background path/to/background.svg \
  --foreground path/to/logo.svg \
  --foreground path/to/accent.png

macicon prepare \
  --background path/to/background.svg \
  --foreground path/to/logo.svg \
  --foreground path/to/accent.png \
  --output path/to/AppIcon.layers

validate --strict --format json treats warnings as failures and emits JSON. prepare retains the source layers in back-to-front order and writes a manifest.json plus import notes. Use --clean to rebuild an existing output directory, or --force to overwrite only generated files with matching names. Import the prepared layers into Apple Icon Composer to configure platform, appearance, and system effects.

Inputs and limitations

• create, iconset, icns, and appiconset accept square SVG, PNG, or JPEG input.
• validate and prepare expect 1024x1024 PNG or SVG layers by default. --expected-canvas-size validates dimensions only. It never resizes input.
• Relative image paths in SVG are resolved from the SVG file’s directory. prepare cannot bundle external dependencies referenced with href.
• validate checks background opacity and warns about SVG text, masks, and external resources.
• macicon targets macOS only. Builds on Windows and Linux fail.

For all options:

macicon --help
macicon create --help
macicon prepare --help

Tests

cargo test
cargo clippy --all-targets --all-features -- -D warnings

References

1. Apple, Human Interface Guidelines
2. Apple, App icons
3. Apple, Apple Design Resources
4. Apple, Creating your app icon using Icon Composer
5. Apple, Configuring your app icon using an asset catalog
6. macOS Compliant Icon Generator