Editable icon layers and a flattened PNG solve different needs. Keep the layers as source, inspect the final silhouette at small sizes and validate the catalog consumed by the app.
- 1Layer sources
- 2Composite preview
- 3Catalog asset
- 4Device inspection
Work through the example
Separate a generated placeholder from a release icon. Review transparency, safe composition and the installed toolchain's accepted format.
Start with a disposable branch and synthetic data. Write the expected outcome before changing the implementation, then keep the first failing result. This prevents a later repair from quietly redefining the task. The procedure below is grounded in the repository reference; its examples must still be checked against your project and installed toolchain.
Implementation reference
The following focused section is adapted from the maintained project guide. It preserves the source’s examples and limitations.
Pattern
Make the layer plan first
Define the app’s recognizable symbol and a single visual idea. Separate the background, supporting shape, primary symbol, and optional accent. Use semantic names and stable ordering. For example, a reading app can use a background fill, a book silhouette, a page mark, and a small bookmark accent; each foreground shape remains editable independently.
Prefer clean vector foregrounds. Use SVG or transparent PNG assets for import, exported on the same canvas so positions remain aligned. Keep text outlined. For raster art, retain transparent backgrounds around foreground artwork. Keep imported background art opaque and full bleed. Do not rasterize all pieces into one image.
A useful project handoff contains:
IconLayers/
01-base.svg
02-symbol.svg
03-accent.svg
manifest.json
README.md
These filenames are a recommended project convention, not an Apple file-format requirement. The CLI’s --xcodegen starter creates editable layers as a starting point; replace their shapes and colors for the actual brand.
Compose and annotate
Launch Icon Composer from Xcode’s developer tools menu or the standalone app. Start a new document, choose the supported platforms, and set its background fill. Import foreground artwork, organize it into no more than four groups, and arrange depth from back to front. Use its material controls for highlights, refraction, translucency, and shadow rather than painting those effects into every asset.
Tune Default, Dark, and Mono appearances. Inspect at small sizes and against different surrounding backgrounds. Keep the silhouette recognizable when decorative detail disappears. Save the native .icon document, reopen it, and check that its layers and appearance settings remain editable.
Integrate with the app
Add the saved icon document to the Xcode project and associate it with the app target’s icon setting. Build with the actual SDK and inspect the installed icon. Use Apple’s asset-catalog image-stack workflow for platforms whose icon format differs, including tvOS and visionOS; do not assume the same Composer workflow applies to every platform.
Export flattened images only for marketing, previews, or compatibility workflows that specifically require them. Retain the editable source and native document alongside those exports.
What an agent must report
List the artwork files, layer ordering, appearance variants checked, native document path if created, and Xcode verification performed. If Icon Composer is unavailable, deliver the SVG/PNG layer pack plus import instructions and explicitly leave native .icon verification pending. Do not invent an undocumented .icon schema or rename a JSON file to make it appear native.
Acceptance and failure review
| Checkpoint | What to inspect | If it does not match |
|---|---|---|
| Layer sources | Confirm the input and environment | Preserve the failure and return to this step |
| Composite preview | Inspect the intermediate artifact | Preserve the failure and return to this step |
| Catalog asset | Run the focused check | Preserve the failure and return to this step |
| Device inspection | Record the observed result | Preserve the failure and return to this step |
Ask the agent to explain the smallest change that resolves the observed mismatch. Keep unrelated refactors out of the repair. A change that makes a warning disappear is not enough if the behavior or ownership contract has changed. Re-run the same acceptance check so the before and after results are comparable.
Evidence and limits
A PNG export is not automatically a native Icon Composer bundle or App Review approval.
This is an educational guide. Its presence in the series does not certify a completed client-specific lab. The series evidence record separates executed checks from exercises and blocked environments.
Inspect the source used in this lesson.
Related reading
- Generate light and dark asset catalogs without a paid design tool
Turn explicit color tokens into Assets.xcassets, then inspect the result in your app.
- How can design tokens generate light, dark and high-contrast color assets?
Generate a real xcassets catalog from explicit color tokens, inspect its four variants, and compile it with actool.
What to do next
Next: Color systems that survive dark mode and high contrast, generated from tokens