/icon-composer-app-icon-workflow

name: icon-composer-app-icon-workflow
description: Design, preview, validate, and integrate Apple app icons with Icon Composer. Use when a task mentions Icon Composer, .icon documents, Liquid Glass app icons, ictool preview exports, app icon design for iOS, iPadOS, macOS, or watchOS, or guided Icon Composer GUI work through Computer Use.

Icon Composer App Icon Workflow

Purpose

Use this skill to help a user learn and operate Apple's Icon Composer workflow for app icons. The skill owns the design-production path from brief to layered source artwork, Icon Composer GUI work, preview export, and Xcode handoff. It does not replace visual judgment, source artwork tools, Xcode execution skills, or product-design iteration.

When To Use

• Use this skill when the user asks for help with Apple's Icon Composer.
• Use this skill when the task mentions `.icon` files, Liquid Glass app icons, Icon Composer documents, app icon appearance modes, or `ictool`.
• Use this skill for app icon workflows targeting iOS, iPadOS, macOS, watchOS, or Xcode app projects.
• Use this skill when the user wants Codex to guide or operate the Icon Composer GUI through Computer Use.
• Use this skill when the task is to export rendered preview PNGs from an Icon Composer document.
• Do not use this skill for generic logo design unless the logo is being prepared as an Apple app icon.
• Do not use this skill for ordinary Xcode build, run, signing, asset-catalog, or project-file work after the app icon handoff is complete.
• Recommend `bootstrap-xcode-workspace` when the Apple product workspace does not exist yet.
• Recommend `xcode-build-run-workflow` when the next step is adding the `.icon` file to an existing Xcode project, choosing it in the Project Editor, building, running, or inspecting project state.
• Recommend `explore-apple-swift-docs` when the user needs a fresh Apple documentation research pass before icon-production work continues.

Apple Documentation Gate

Before making claims about current Icon Composer behavior, Xcode integration, platform requirements, appearance modes, or exported asset expectations, check current Apple documentation.

Use official Apple sources first:

• [Icon Composer](https://developer.apple.com/icon-composer/)
• [Creating your app icon using Icon Composer](https://developer.apple.com/documentation/Xcode/creating-your-app-icon-using-icon-composer)
• [Human Interface Guidelines: App icons](https://developer.apple.com/design/human-interface-guidelines/app-icons/)
• [Create icons with Icon Composer](https://developer.apple.com/videos/play/wwdc2025/361/)
• [Apple Design Resources](https://developer.apple.com/design/resources/)

State the documented behavior being relied on before recommending a design, export, or Xcode integration step. If Apple's docs and the live app disagree, stop and report the conflict.

Current documented anchors to verify against the live docs:

• Icon Composer creates layered app icons from one design for iPhone, iPad, Mac, and Apple Watch.
• The workflow starts in a design tool, exports layers, imports them into Icon Composer, tunes glass properties, previews platforms and rendering modes, saves a `.icon` file, and delivers that file to Xcode.
• Icon Composer can export flattened images for marketing and communication needs, but the `.icon` file is the primary app icon production artifact when Xcode supports it.
• Flat graphics should usually be exported as scalable SVG when possible. Custom gradients, raster images, and non-SVG elements should be exported as PNGs with transparent backgrounds.
• Complex or illustrative icons may still be better delivered to Xcode as individual images when the artwork does not translate well into the layered Liquid Glass model.
• Apple's current Icon Composer page names specular highlights, refraction, translucency, shadows, Default, Dark, and Mono rendering-mode annotation. Verify those names against the live page and local app before coaching a user through exact inspector controls.

Local Tool Check

Before a live workflow, inspect the Mac and report what is available:

1. Locate Icon Composer. Common stable path: `/Applications/Xcode.app/Contents/Applications/Icon Composer.app` 2. Check beta Xcode app paths as needed: `/Applications/Xcode-beta.app/Contents/Applications/Icon Composer.app` `/Applications/Betas/Xcode-beta.app/Contents/Applications/Icon Composer.app` 3. Verify the app is present before promising GUI guidance. 4. Open Icon Composer when the task needs live GUI inspection, document editing, platform preview, or behavior that only the app can show. Do not report that Icon Composer behavior is unverifiable merely because the app was not already open. 5. Locate `ictool`. Common stable path: `/Applications/Xcode.app/Contents/Applications/Icon Composer.app/Contents/Executables/ictool` 6. Check beta `ictool` paths as needed: `/Applications/Xcode-beta.app/Contents/Applications/Icon Composer.app/Contents/Executables/ictool` `/Applications/Betas/Xcode-beta.app/Contents/Applications/Icon Composer.app/Contents/Executables/ictool` 7. Run `ictool --help` or `ictool --version` when preview export is part of the task. 8. Record the local Icon Composer app version when behavior matters. Stable Icon Composer 1.6 reports `short-bundle-version` `1.6` and `bundle-version` `99.1`; a newer Xcode beta may report Icon Composer 2.0 and expose newer options. 9. Identify the target app project shape before promising Xcode integration.

Do not assume Icon Composer exists just because Xcode exists. Older Xcode installs, alternate Xcode locations, or standalone Icon Composer installs can change the path. Do not mix stable and beta behavior. If stable Icon Composer 1.6 and beta Icon Composer 2.0 disagree, say which app bundle was inspected and keep guidance scoped to that version unless the user explicitly asks to compare them.

Brief Intake

Collect a short brief before editing artwork or opening Icon Com