app-icons

App Icons

Create, refine, and ship Apple-platform app icons (the launcher icon shown on the Home Screen, Dock, Finder, App Store, and Spotlight), plus generate in-app icon glyphs for asset catalogs. This skill spans the full lifecycle: product strategy → distinct candidates → small-size readability → a polished master → the correct platform asset → App Store conversion testing.

Two distinct deliverables this skill handles — keep them separate:

Deliverable	What it is	Section
App icon (launcher)	The single iconic mark that represents the whole app	"App icon workflow" (default)
In-app glyphs	Small UI symbols inside the app (tab bars, list rows, buttons)	"In-app icon glyphs"

When the user says "icon" without qualification, assume the app icon unless the context is clearly a UI glyph for a control.

---

App icon workflow

1. Understand the product. Read README, app name, screenshots, onboarding, paywall, core screens, target audience, category, competitors, and the target platform (iOS, macOS, or both). The icon is the first thing users see in App Store search — before the title, rating, or screenshots — so design it as a marketing asset, not just an asset-catalog entry.
2. Write a one-line strategy before drawing anything:

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

   For the full briefing method, prompt patterns, and the decision path on what to put on the icon, see references/icon-strategy.md.
3. Generate 3–5 distinct directions with an image model ($imagegen or equivalent) — unless the repo already has a native vector/logo system that should be edited directly. Use separate prompts per direction; never ask for "many options in one image." Each candidate is a square 1024×1024 PNG.
4. Evaluate at real sizes. iOS recognition lives at ~60 px (Home Screen); macOS stress-tests at 64, 32, and 16 px (Dock/Finder). Squint/blur it, convert mentally to grayscale, place it on light AND dark backgrounds, and view it beside real competitor icons. Generate an HTML proof sheet:

   python3 references/scripts/preview_icon_readability.py master-icon.png /tmp/icon-preview --mask ios
   # macOS-style (no rounded mask):
   python3 references/scripts/preview_icon_readability.py master-icon.png /tmp/icon-preview --mask none
   

5. Refine one direction down to a single square 1024×1024 PNG master. Prefer no alpha for shared iOS / App Store assets. Avoid text, screenshots, tiny details, fine gradients, and baked iOS rounded corners (iOS applies its own mask — drawing your own doubles the radius and the icon looks inset).
6. Locate existing assets and preserve configured names before replacing:

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

7. Produce the platform asset (choose a format below).
8. Validate before submitting (classic .appiconset). Catch the white-border / halo bug, missing slots, pixel-dimension mismatches, and alpha on the 1024 — all pass ASC validation yet still look broken:

   references/scripts/check-icons.sh path/to/AppIcon.appiconset
   

   See references/icon-validation.md. For an Icon Composer .icon, the equivalent post-compile check is assetutil --info (references/icon-composer-pipeline.md).
9. Build, run, and inspect the installed icon. Simulator/Home Screen for iOS; the built .app, Dock, Finder, and Info.plist for macOS. If the old icon is cached, reinstall the iOS app or restart Finder/Dock only after confirming the built bundle contains the new icon metadata.

Full design + technical checklist (sizes, asset-catalog slots, common failure modes): references/icon-checklist.md.

---

Ways to ship the app icon

Pick the format that matches the project's deployment target and toolchain. Paths A–C cover the common cases; for a SwiftPM app or a hand-assembled macOS .app whose .icon is not compiled by an Xcode build, see path D (actool compile) in references/icon-composer-pipeline.md.

A. iOS 26 / macOS 26 — Icon Composer .icon bundle (current, recommended)

Xcode 26 ships Icon Composer, Apple's tool for the Liquid Glass icon system. You author layered artwork once and it renders the platform appearance variants automatically:

• Default (light), Dark, Tinted (monochrome over a system-chosen tint), and Clear appearances — built from the same layer stack.
• Output is a single .icon bundle dropped into the asset catalog; Xcode builds every required rendition. No more hand-managed @2x/@3x PNG slots.
• Author with vector layers (SVG / PDF) when possible — Icon Composer composites and applies system blur, specular, and shadow per appearance, so raster layers limit quality.
• Design the light icon first, then derive dark and tinted from it so the set feels coherent beside system apps and widgets.
• Keep critical content mask-safe and centered; the system rounds and masks all variants. Do not bake your own rounded corners or specular highlights — the system adds them.

Use this path for apps targeting iOS 26 / macOS 26 (Tahoe). It is the modern Apple-recommended workflow and the only way to get Dark/Tinted/Clear variants that match the system.

For the on-disk .icon package format, the hand-editable icon.json schema (the only way to script per-appearance layer opacity), ictool previews, actool compile (SwiftPM / hand-built bundles), and assetutil verification: references/icon-composer-pipeline.md.

B. Classic AppIcon.appiconset (single 1024 master)

For projects not yet on the .icon workflow, modern Xcode accepts a single 1024×1024 marketing image and synthesizes the rest. For older projects / deployment targets that still expect the full slot set, generate every PNG from one master with the bundled script (no Pillow / third-party deps — uses only macOS sips):

# iOS asset catalog (full classic slot set)
python3 references/scripts/generate_appiconset.py master-icon.png path/to/AppIcon.appiconset --platform ios --replace

# macOS asset catalog
python3 references/scripts/generate_appiconset.py master-icon.png path/to/AppIcon.appiconset --platform macos --replace

# Both platforms (universal)
python3 references/scripts/generate_appiconset.py master-icon.png path/to/AppIcon.appiconset --platform universal --replace

Add --strict to FAIL (instead of warn) on an undersized source or on iOS-with-alpha. Prefer the single-1024 modern set when the deployment target allows it; reach for the full set only for legacy compatibility.

C. macOS .icns bundle (manually packaged apps)

python3 references/scripts/generate_appiconset.py master-icon.png path/to/AppIcon.icns --platform macos --format icns --replace

Then wire it up: put the .icns under Contents/Resources, set CFBundleIconFile (icon name, no path; .icns extension optional), and rebuild/relaunch — Finder and Dock cache old icons.

---

Design rules (the non-negotiables)

• One memorable metaphor over a feature collage. If it needs explanation, reject it. Aim for "describable in 3–5 words" — ✅ "bold orange flame", ❌ "abstract colorful shapes."
• Simplicity at small size. Max ~2 elements. No text (illegible at 60×60, and Apple discourages it) unless it's a single brand glyph still readable at 40–60 px.
• Strong shape contrast first, color contrast second. The silhouette carries the idea — verify grayscale and blurred readability.
• High contrast on BOTH light and dark App Store backgrounds. Avoid pure white icons (vanish in light mode) and very dark icons (vanish in dark mode); a subtle background or border helps.
• Differentiate from the category. Look at your top ~20 competitors, then design to be immediately distinguishable. If it fits ten competitors unchanged, it's too generic.
• No baked rounded corners for iOS, no screenshots, no tiny details, no fine gradients / waveform lines (they disappear at small sizes).
• Human faces/profiles need unmistakable cues (forehead, nose, mouth/chin, neck) — avoid ambiguous bean/kidney silhouettes.
• Watch for accidental meanings (body organs, flags, political/medical cues).

Scoring rubric for choosing among candidates (recognition at small size, memory, category fit, differentiation, shelf appeal, brand fit, technical readiness): see the rubric and audit in references/aso-conversion.md.

---

App Store conversion: optimize and A/B test the icon

The icon is your single most impactful App Store asset — a compelling one can lift tap-through rate (TTR) by 20–40% with no other changes. Once you have a strong candidate, validate it with a live test instead of guessing.

• iOS — App Store Connect → your app → Product Page Optimization → create a test with up to 3 icon treatments; allocate traffic; run ≥7 days or until significance. (App icon variants must also ship in the app binary's asset catalog for PPO icon tests.)
• Android — Play Console → Store listing experiments → upload variants → split traffic → read install conversion rate per variant.
• Test one variable at a time (background color, flat vs illustrated vs 3D, dark vs light, character vs abstract). Need ~1,000+ impressions per variant for a reliable read; use a p < 0.05 / console-confidence threshold.

Full methodology — the category visual-language table, the icon audit rubric, required sizes, the test matrix, and a designer brief template — is in references/aso-conversion.md.

---

In-app icon glyphs (SF Symbols / Iconify imagesets)

This is the OTHER kind of "icon": small UI symbols rendered inside the app (tab bars, list rows, buttons) as .imageset entries in an asset catalog — NOT the launcher icon. Prefer SF Symbols directly in SwiftUI (Image(systemName:)) when possible; only generate PNG imagesets when you need a baked raster (a specific color/weight, an icon not in SF Symbols, or an offline asset).

Two generators are bundled (both emit a complete 1x/2x/3x imageset + Contents.json):

Source	Icons	Requires	Script
SF Symbols	5,000+ Apple-native	macOS	references/scripts/generate_icons.swift
Iconify API	275,000+ from 200+ open-source sets	internet	references/scripts/iconify_gen.sh

# SF Symbols → imageset (Apple-native style)
swift references/scripts/generate_icons.swift doc.text.below.ecg expenseReport \
  --color 007AFF --weight regular --output ./Assets.xcassets/icons

# Iconify → imageset (wide selection); search first, then generate
references/scripts/iconify_gen.sh search "receipt" --prefix mdi
references/scripts/iconify_gen.sh mdi:receipt-text-outline expenseReport \
  --color 007AFF --output ./Assets.xcassets/icons

Always match the project's existing glyph style (check an existing icon's size/color/weight with sips -g pixelWidth -g pixelHeight path/to/[email protected]) and verify the generated @2x PNG visually before committing. Full usage, collection list, and anti-patterns: references/in-app-glyphs.md.

---

Resources

• references/icon-strategy.md — concept strategy, the "what goes on the icon" decision path, $imagegen prompt + refinement patterns, the 2026 image-model ladder/pricing/tuning, negative prompts, and per-category style keywords.
• references/icon-checklist.md — detailed design + technical checklist, asset-catalog slot reference, the Watch dual-entry gotcha, auto-square step, and common failure modes (incl. Liquid-Glass symptom→cause).
• references/icon-composer-pipeline.md — .icon package format, hand-editable icon.json schema, ictool/actool/assetutil, the SwiftPM/hand-built macOS ship path, and the failure-diagnostic table.
• references/icon-validation.md — programmatic pre-submission validation: white-border detection, slot/dimension/alpha checks, cross-size consistency.
• references/aso-conversion.md — TTR optimization, category visual-language table, icon audit rubric, A/B test matrix, required sizes, designer brief.
• references/in-app-glyphs.md — SF Symbols + Iconify imageset generation, tintable vector SVG imagesets, SF Symbol→SVG vector export, menu-bar glyphs.
• references/scripts/generate_appiconset.py — make iOS/macOS app-icon PNG slots, Contents.json, or a macOS .icns from one square PNG (sips/iconutil).
• references/scripts/preview_icon_readability.py — HTML small-size proof sheet on light/dark + a 30-icon shelf test.
• references/scripts/check-icons.sh + sample-rgb.swift — validate a finished .appiconset (white-border, slots, dimensions, alpha) — no Pillow needed.
• references/scripts/export_icon_renditions.py — ictool preview renditions + contact sheet from a .icon package.
• references/scripts/compile_icon_assets.py — actool-compile a .icon into Assets.car + verify with assetutil (SwiftPM / hand-built macOS bundles).
• references/scripts/generate_icons.swift — SF Symbols → asset-catalog imageset.
• references/scripts/sf_symbol_cli.swift + sf-symbol-svg.sh — SF Symbol → scalable vector SVG (private CoreUI API, macOS 14+).
• references/scripts/iconify_gen.sh — Iconify API → asset-catalog imageset.

Official references

• Apple Human Interface Guidelines — App icons: https://developer.apple.com/design/human-interface-guidelines/app-icons
• Apple — Icon Composer (Liquid Glass icons, Xcode 26): https://developer.apple.com/icon-composer/
• App Store Connect Help — Add an app icon: https://developer.apple.com/help/app-store-connect/manage-app-information/add-an-app-icon
• App Store Connect Help — Product Page Optimization (icon A/B testing): https://developer.apple.com/help/app-store-connect/test-a-beta-version/optimize-your-product-page