| name | app-icons |
| description | Design, generate, evaluate, and ship Apple-platform APP ICONS — from a conversion-optimized 1024×1024 master to an iOS 26 Icon Composer .icon bundle (light/dark/tinted/clear variants), AppIcon.appiconset, or macOS .icns — plus IN-APP icon glyphs (SF Symbols / Iconify imagesets). Covers small-size readability and App Store tap-through (TTR) A/B testing. Use when asked for: "app icon", "icon design", "generate app icon", "AppIcon.appiconset", ".icns", "Icon Composer", "liquid glass icon", ".icon package", "ictool", "actool icon", "dark/tinted icon variant", "icon A/B test", "validate app icon", "icon white border", "missing icon size", "SF Symbol to SVG", "menu bar icon", "imageset". |
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
- 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.
- 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.
- 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.
- 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
python3 references/scripts/preview_icon_readability.py master-icon.png /tmp/icon-preview --mask none
- 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).
- 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'
- Produce the platform asset (choose a format below).
- 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).
- 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):
python3 references/scripts/generate_appiconset.py master-icon.png path/to/AppIcon.appiconset --platform ios --replace
python3 references/scripts/generate_appiconset.py master-icon.png path/to/AppIcon.appiconset --platform macos --replace
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 |
swift references/scripts/generate_icons.swift doc.text.below.ecg expenseReport \
--color 007AFF --weight regular --output ./Assets.xcassets/icons
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/existing@2x.png)
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
