app-icon-generator

# App Icon Generator Generate an app icon programmatically with a CoreGraphics Swift script, resize it to every required size, and install it into the Xcode asset catalog — with appearance variants (light/dark/tinted). ## Read first — the Liquid Glass era (iOS 26 / macOS 26) > **Apple icon standards verified as of July 2026** — Icon Composer, Xcode 26, macOS Tahoe 26.4+. This guidance is static (the skill does no per-run web lookup); if that date is well in the past or the OS has moved on, re-verify against the [HIG · App icons](https://developer.apple.com/design/human-interface-guidelines/app-icons) before trusting the specifics below. Apple's shippable icon format changed. On iOS 26 / macOS 26 the modern app icon is a **layered, light-responsive Liquid Glass icon** authored in **Icon Composer** (free; ships with Xcode 26, needs macOS Tahoe 26.4+). You supply *flat* artwork in up to **four depth groups** (background → foreground); the **system renders the glass** — specular highlights, refraction, translucency, shadows — and masks the rounded-rect shape. One `.icon` file adapts across iPhone, iPad, Mac, and Apple Watch and across **Default / Dark / Mono (tinted)** appearances. **So this skill does NOT produce the final iOS 26 icon.** Icon Composer is GUI-first; no script can author a true layered `.icon`. Its two honest roles are: 1. **Placeholder** — a fast flat 1024 PNG so early builds, TestFlight, and screenshots feel real before you invest in the real icon. 2. **Layered source art** — flat background / midground / foreground PNGs (or SVGs), effect-free, ready to drag into Icon Composer, where you assemble depth and export the `.icon`. **What changed vs. the classic flow:** - **Do not bake in lighting.** No pre-painted specular highlights, drop shadows, or gradients-used-as-lighting — the system owns those now, and baking them in double-exposes against the system glass. (The `drawShine`/`drawShadow` blocks below are **legacy-only**, off by default for iOS 26+ targets.) - **Do not round the corners.** Icon Composer / the system apply the shape mask — fill a full square canvas. - **SVG for shapes, PNG for effects** — vector where you can, raster only where you must. - **Provide appearance variants** — light (default), dark, and tinted/mono. A single flat PNG only fills the light slot and won't adapt on iOS 18+. **Detect the target first:** read the deployment target (`IPHONEOS_DEPLOYMENT_TARGET` / `MACOSX_DEPLOYMENT_TARGET` in the pbxproj, or `.planning/APP.md`). iOS 26+ / macOS 26+ → lead with the Icon Composer handoff and treat the flat PNG as a placeholder. Older targets → the classic flat + appearances path is fine to ship. **If the deployment target is newer than the "verified as of" date above, flag it to the user and re-verify the icon rules against the current HIG before generating** — the skill won't know about anything Apple shipped after that date. ## When This Skill Activates Use this skill when the user: - Asks to "generate an app icon" or "create an icon" - Wants a "placeholder icon" or "app icon design" - Mentions "icon for my app" or "need an app icon" - Asks to "update the app icon" ## Pre-Generation Checks ### 1. Project Context Detection ``` Glob: **/Assets.xcassets/AppIcon.appiconset/Contents.json ``` - Identify platform: macOS, iOS, or universal - Check for existing icon files (warn before overwriting) - Read `Contents.json` to understand required sizes ### 2. App Context Detection Gather app information to customize the icon: ``` Read: .planning/APP.md (if exists — app definition) Read: .planning/CODEBASE.md (if exists — app description) Grep: "CFBundleName" or app name in project files ``` If no planning files exist, ask the user. ## Configuration Questions Ask via AskUserQuestion: ### Question 1: App Category "What category best describes your app?" - **Productivity** — Clean geometric shapes, blues/teals - **Creative/Media** — Vibrant colors, camera/brush/music motifs - **Developer Tools** — Dark backgrounds, terminal/code symbols - **Utilities** — Functional shapes, neutral/system colors ### Question 2: Visual Style "What visual style do you prefer?" - **Bold Symbol** — Single prominent shape/icon centered (like the record button) - **Contained Scene** — A scene inside a shape (like a monitor with elements) - **Abstract Mark** — Geometric/abstract design (like viewfinder brackets) - **Gradient Glyph** — SF Symbol-style glyph on gradient background ### Question 3: Color Palette "What color palette fits your app?" - **Deep Blue/Indigo** — Professional, trustworthy (navy #0f0c29 to indigo #302b63) - **Teal/Cyan** — Fresh, modern (dark teal #0a1628 to blue #1a4a6b) - **Purple/Violet** — Creative, premium (midnight #1a0533 to violet #4a1a8a) - **Warm/Orange** — Energetic, friendly (dark red #2d1117 to orange #c0392b) ### Question 4: Accent Color "What accent color for the focal element?" - **Red** — Attention, recording, alerts (#ff453a to #d63031) - **Blue** — Trust, communication (#007aff to #0056b3) - **Green** — Success, nature, health (#34c759 to #248a3d) - **Gold/Yellow** — Premium, energy (#ffd60a to #c7a600) ## Apple HIG Icon Guidelines **Read `apple-hig-icons.md` before generating.** **Timeless rules (all eras):** 1. **No text** in the icon — must be universally recognizable 2. **Single focal point** — one clear element the eye is drawn to 3. **Simple shapes** — legible at 16×16 (macOS menu bar) and at Home-screen size 4. **Fill a full square canvas** — never bake in rounded corners; the system / Icon Composer apply the shape mask 5. **Front-facing** — no 3D tilts or dramatic angles 6. **Ensure contrast** — the focal element must stand out from the background 7. **Platform-appropriate detail** — macOS can be more detailed (displays larger); iOS simpler **Liquid Glass era rules (iOS 26 / macOS 26):** 8. **The system owns lighting.** No baked specular, drop shadows, or gradients-as-lighting — Icon Composer / the system add depth, refraction, and highlights. Keep artwork flat. 9. **Provide appearance variants** — light (default), dark, and tinted/mono. Make sure the mark reads on all three (tinted renders as a monochrome silhouette on a system-tinted background). 10. **Layer, don't flatten (final icon)** — organize art into ≤4 depth groups for Icon Composer; SVG for shapes, PNG only for texture. ## Designing the Icon (Apple's Rules) Design-layer guidance from Apple's icon sessions (WWDC25) plus evergreen craft tests. The numbered rules above are the hard constraints; this is how to make the artwork good. ### Composition - **One 1024×1024 canvas** drives every platform — except **watchOS, which uses 1088×1088**, deliberately overshooting the circular mask so edge-to-edge art survives the crop. Either way the system applies the mask. - **Frontal, flat illustration** beats realistic 3D/perspective rendering — the glass material supplies the dimensionality, so pre-rendered depth fights it. - **Fewer, rounder layers beat dense detail.** Avoid sharp edges and thin lines: rounder corners carry the glass lighting; bolder weights survive small sizes. - **Soft gradients over flat fills.** For backgrounds, prefer the built-in **System Light / System Dark gradients** to pure white or black. - **Colored backgrounds keep light, dark, and tinted modes distinct** — a neutral field collapses across appearances. - **Translucency and blur are encouraged**, not risky: clear mode shows the wallpaper *through* the glass, so translucent layers are rewarded. ### Appearance modes Author **three** variants — default, dark, mono — and the system derives **six** renders: default, dark, clear light/dark, tinted light/dark. Preview all six before shipping. ### Icon Composer craft details 1. Export artwork **flat and opaque**, each color region split into its own layer; SVG for flat graphics (**convert text to outlines** first), PNG for gradients and raster; export at canvas size. 2. Prefix layer filenames with a **Z-order number** so stacking imports deterministically. 3. Glass is applied **per layer** — if a narrow shape turns "pillowy", toggle that layer's specular off. 4. Tune per appearance: swap any fill that vanishes against black in dark mode; in mono keep **one prominent white element** and step the rest down to grays. 5. Choose **neutral vs chromatic shadows** per layer — chromatic tints the shadow with the layer's color, better for colorful art on light backgrounds. 6. Test on real wallpapers, with the grid overlay, and at small sizes — then ship the exported `.icon` into Xcode. ### Classic tests (evergreen) - **One identifiable metaphor** — if you can't name the single thing the icon depicts, users can't either. - **Squint test inside a folder**: still distinguishable among its neighbors? - Check the **Settings-list render**, not only the Home Screen (Step 4.6) — it's the smallest surface users see daily. - **Align key shapes to the icon grid** for optical balance (a guide, not a straitjacket). - An icon is **identity with lineage** — refine it release over release; don't redesign from scratch every update. ## Generation Process ### Step 1: Determine Icon Design Based on the user's answers (or app context), select: - **Background**: Gradient direction, colors, optional radial glow - **Primary Element**: The main shape/symbol - **Secondary Elements**: Optional ring, glow, accent shapes - **Style Modifiers**: stroke weight (⚠️ skip Shine/shadow for iOS 26+ targets — the system applies Liquid Glass specular and shadow; baking them in double-exposes) ### Step 2: Generate Swift Script Create a self-contained Swift script at `scripts/generate-icon.swift` that: - Uses `import AppKit` and `CoreGraphics` (no dependencies) - Generates **3 variants** at 1024x1024 - Saves to `icon-variants/` directory - Uses the design parameters from Step 1 **Script structure:** ```swift #!/usr/bin/env swift import AppKit import CoreGraphics let size: CGFloat = 1024 // ... helper functions (gradients, glows, shapes) // ... variant generation functions // ... save and output ``` **Design building blocks** (combine these based on category/style): | Building Block | Function | Use For | |---------------|----------|---------| | `drawGradientBackground` | Linear gradient fill | All icons | | `drawRadialGlow` | Soft colored glow behind focal element | Adding depth | | `drawCircle` | Filled/stroked circle | Record buttons, dots, orbs | | `drawRoundedRect` | Rounded rectangle | Screens, cards, containers | | `drawRing` | Circle outline | Borders, focus rings | | `drawBrackets` | Corner bracket marks | Viewfinders, capture | | `drawMonitor` | Screen + stand shape | Screen/display apps | | `drawShield` | Shield outline | Security/privacy apps | | `drawGear` | Gear/cog shape | Settings/utility apps | | `drawWaveform` | Audio waveform bars | Audio/music apps | | `drawDocument` | Page with fold corner | Document/writing apps | | `drawShine` | Elliptical specular highlight | ⚠️ Legacy only — off for iOS 26+ (system paints its own specular) | | `drawShadow` | Drop shadow beneath element | ⚠️ Legacy only — off for iOS 26+ (system casts its own shadow) | ### Step 3: Run Script and Present Variants ```bash swift scripts/generate-icon.swift ``` Show all 3 variants to the user using the Read tool (Claude can view images). Ask the user to pick one, or request adjustments. ### Step 4: Resize and Install Once the user picks a variant: 1. **Resize** using `sips` (built into macOS): For **macOS** (10 sizes): ```bash sips -z 16 16 master.png --out icon_16x16.png sips -z 32 32 master.png --out icon_16x16@2x.png sips -z 32 32 master.png --out icon_32x32.png sips -z 64 64 master.png --out icon_32x32@2x.png sips -z 128 128 master.png --out icon_128x128.png sips -z 256 256 master.png --out icon_128x128@2x.png sips -z 256 256 master.png --out icon_256x256.png sips -z 512 512 master.png --out icon_256x256@2x.png sips -z 512 512 master.png --out icon_512x512.png sips -z 1024 1024 master.png --out icon_512x512@2x.png ``` For **iOS** (single 1024x1024): ```bash cp master.png icon_1024x1024.png ``` 2. **Write Contents.json** for the asset catalog For **macOS**: ```json { "images": [ { "filename": "icon_16x16.png", "idiom": "mac", "scale": "1x", "size": "16x16" }, { "filename": "icon_16x16@2x.png", "idiom": "mac", "scale": "2x", "size": "16x16" }, { "filename": "icon_32x32.png", "idiom": "mac", "scale": "1x", "size": "32x32" }, { "filename": "icon_32x32@2x.png", "idiom": "mac", "scale": "2x", "size": "32x32" }, { "filename": "icon_128x128.png", "idiom": "mac", "scale": "1x", "size": "128x128" }, { "filename": "icon_128x128@2x.png", "idiom": "mac", "scale": "2x", "size": "128x128" }, { "filename": "icon_256x256.png", "idiom": "mac", "scale": "1x", "size": "256x256" }, { "filename": "icon_256x256@2x.png", "idiom": "mac", "scale": "2x", "size": "256x256" }, { "filename": "icon_512x512.png", "idiom": "mac", "scale": "1x", "size": "512x512" }, { "filename": "icon_512x512@2x.png", "idiom": "mac", "scale": "2x", "size": "512x512" } ], "info": { "author": "xcode", "version": 1 } } ``` For **iOS** (single size, system generates others): ```json { "images": [ { "filename": "icon_1024x1024.png", "idiom": "universal", "platform": "ios", "size": "1024x1024" } ], "info": { "author": "xcode", "version": 1 } } ``` 3. **Copy files** into the asset catalog directory 4. **Build** to verify: `xcodebuild build -scheme <scheme> -destination 'platform=<platform>' -quiet` ### Step 4.5: Appearance variants & Icon Composer handoff **Appearance variants (iOS 18+, scriptable).** For the flat path, generate three 1024 PNGs — light (default), dark, and a monochrome/tinted mark — and declare them so the icon adapts to the user's Home screen: ```json { "images": [ { "filename": "icon_light.png", "idiom": "universal", "platform": "ios", "size": "1024x1024" }, { "filename": "icon_dark.png", "idiom": "universal", "platform": "ios", "size": "1024x1024", "appearances": [ { "appearance": "luminosity", "value": "dark" } ] },