blueprint

Turn your app icon into a blueprint version, like Xcode's icon, for your debug builds.

Works with Icon Composer .icon files and classic .appiconset folders.

Install

With Homebrew, from MustafaNatur/homebrew-tap:

brew install mustafanatur/tap/blueprint

Or from source:

git clone https://github.com/MustafaNatur/blueprint.git
cd blueprint
make install

This puts blueprint in ~/.local/bin. Make sure that folder is on your PATH.

Requires macOS 14+ and Xcode 26+.

Use

Pass the path to your icon:

blueprint path/to/AppIcon.icon
blueprint path/to/Assets.xcassets/AppIcon.appiconset

The blueprint is saved in the same format:

.icon: AppIconDebug.icon in the folder you ran the command from, opened in Icon Composer.
.appiconset: AppIconDebug.appiconset next to the original, in the same asset catalog, shown in Finder.

Then set it as the app icon of your Debug configuration in Xcode: Primary App Icon Set Name (ASSETCATALOG_COMPILER_APPICON_NAME).

Options

Option	Default
`-o`, `--output`	see above	Where to save the blueprint.
`--color`	`#0AC2FC,#10A3FA,#1A6FFB`	Background colors, top to bottom.
`--line-width`	`9`	Outline width.
`--badge`		Text in a badge in the bottom right corner, such as `DEV` or `BETA`. Long text wraps onto more lines.
`--no-grid`		Leaves out the grid lines.
`--no-open`		Doesn't open the result.

Badges

Tell builds for different environments apart with a badge. It takes the last --color, so each environment can have its own colors too. Long text wraps, and the badge grows upward line by line:

blueprint AppIcon.icon --badge DEV -o AppIconDev.icon
blueprint AppIcon.icon --badge BETA --color "#FFB74D,#FB8C00,#E65100" -o AppIconBeta.icon
blueprint AppIcon.icon --badge "RC 2.4.1" --color "#A78BFA,#8B5CF6,#6D28D9" -o AppIconRC.icon

Good to know

How a flat .appiconset icon is traced. A flat image has no layers, so blueprint separates what's in front from the background with Vision's subject lifting, the same as "Lift Subject" in Photos, and outlines it as one shape.
Every slot is kept. Dark and tinted variants, and every size of a macOS icon set, get the blueprint too, so it looks the same everywhere.
Running blueprint again replaces the blueprint it drew before. It never overwrites any other icon.

License

MIT. See LICENSE.