app-icon-studio

name	app-icon-studio
description	Create, generate, evaluate, export, install, or debug iOS and macOS app icons, including AppIcon.appiconset assets and macOS .icns bundle icons.

App Icon Studio

Create Apple-platform app icons from product context, generate polished candidates, test small-size recognition, and install valid iOS or macOS icon assets.

Workflow

1. Inspect product reality: README, app name, screenshots, onboarding, paywall, core screens, audience, competitors if useful, and the target platform.
2. Write the strategy:

   This icon should make <target user> remember <app name> as the app for <core job/emotion>, using <simple visual metaphor>.
   

3. Generate 3-5 distinct directions with $imagegen unless the repo has a native vector/logo system that should be edited directly.
4. Evaluate at practical sizes: about 60 px for iOS home-screen recognition, and 64, 32, and 16 px for macOS Dock/Finder stress checks.
5. Refine one square 1024x1024 PNG master. Prefer no alpha for shared iOS/macOS assets and App Store readiness. Avoid text, screenshots, tiny details, and baked iOS rounded corners.
6. Locate existing assets and preserve configured names:

   rg --files | rg 'Assets\.xcassets|AppIcon\.appiconset|\.icns$|Info\.plist|Contents\.json'
   rg 'ASSETCATALOG_COMPILER_APPICON_NAME|CFBundleIconFile|CFBundleIconName|AppIcon'
   

7. Generate or replace the platform asset:

   # iOS asset catalog
   python3 <skill-dir>/scripts/generate_appiconset.py master-icon.png path/to/AppIcon.appiconset --platform ios --replace
   
   # macOS asset catalog
   python3 <skill-dir>/scripts/generate_appiconset.py master-icon.png path/to/AppIcon.appiconset --platform macos --replace
   
   # macOS bundle icon
   python3 <skill-dir>/scripts/generate_appiconset.py master-icon.png path/to/AppIcon.icns --platform macos --format icns --replace
   

8. Build/run and inspect the installed icon: simulator/home screen for iOS, or the built .app bundle, Dock, Finder, and Info.plist for macOS. Clear icon caches or reinstall when the old icon is cached.

ImageGen Prompt Contract

Use $imagegen for raster artwork. Ask for an Apple-platform app icon, square 1024x1024 master artwork, one main symbol/metaphor, centered composition, strong contrast, 2-4 colors, no text/watermark/UI screenshot/flags/tiny details/baked iOS mask/transparent background unless a macOS transparent icon silhouette is explicitly desired.

Open-ended directions:

• product metaphor;
• user outcome;
• category signal plus distinctive twist;
• abstract brand mark only when literal metaphors are weak;
• character/face only when identity, coaching, communication, or companionship is central.

Platform Notes

• iOS applies the rounded mask; do not draw rounded corners into the artwork.
• macOS icons may use dimensional objects, perspective, and .icns files in Contents/Resources, but the silhouette must still survive at 32 and 16 px.
• Xcode asset catalogs usually reference ASSETCATALOG_COMPILER_APPICON_NAME; manually packaged macOS apps usually need CFBundleIconFile or CFBundleIconName plus a copied resource.
• Preserve the existing icon set name unless the project configuration is being updated in the same change.

Design Rules

• Keep the main symbol large, centered, and mask-safe for the target platform.
• Prefer one memorable metaphor over a feature collage.
• Strong shape contrast first; color contrast second; verify grayscale/blur readability.
• Human faces/profiles need clear forehead, nose, mouth/chin cues; avoid ambiguous bean-like silhouettes.
• Make it ownable and desirable; if it fits ten competitors unchanged, it is too generic.

Selection Rubric

Score recognition at small sizes, memory, category fit, differentiation, shelf appeal beside real icons, brand fit, and technical readiness.

Resources

• scripts/generate_appiconset.py: generate iOS/macOS icon PNGs, Contents.json, or macOS .icns.
• scripts/preview_icon_readability.py: HTML small-size preview on light/dark.
• references/icon-strategy-and-imagegen.md: concept strategy and prompt patterns.
• references/app-icon-checklist.md: detailed design/technical checklist.