ios-icon-composer

Files (2)

• SKILL.md
• openai.yaml · agents/

SKILL.md (first lines)

# iOS Icon Composer

Build the app icon as a native Apple asset, not a web logo exported into an appiconset. The source of truth is the Icon Composer `.icon` package when the project can compile it.

## 1. Ground The Icon

Inspect the product and current asset wiring before drawing.

Use `rg`/`find` to locate:

- `*.xcassets`, `*.appiconset`, existing `.icon` packages
- `Info.plist`, `ASSETCATALOG_COMPILER_APPICON_NAME`, target resources
- design docs, screenshots, mockups, or brand notes

Read current Apple docs when the user asks for "latest" support, when Xcode/Icon Composer behavior differs from memory, or when adopting a new Xcode beta. Prefer official Apple docs:

- `https://developer.apple.com/documentation/Xcode/creating-your-app-icon-using-icon-composer`
- `https://developer.apple.com/documentation/uikit/creating-custom-symbol-images-for-your-app`

Completion criterion: the current icon source, target setting, and product visual direction are known.

## 2. Design Native Layers

Prefer a bold symbol that reads at small sizes. For local/chat/radio products, a custom SF Symbols-derived path can work better than stacking existing symbols: make the shapes synthesize one idea, not sit beside each other.

Rules:

- Use Icon Composer layers, fills, blend modes, shadows, translucency, and Liquid Glass effects for final styling.
- Use SF Symbols app exports or deterministic path scripts for custom symbol geometry when needed.
- Avoid image generation unless the user explicitly asks for generated bitmap artwork.
- Do not bake rounded corners into the artwork; iOS masks the icon.
- Do not make the final app icon transparent.
- Do not keep a stale PNG fallback once the `.icon` package compiles.
- Avoid generic chat bubbles, debug/network-tool diagrams, security cliches, and web-logo composition.

For Home Screen styles, configure appearance specializations in Icon Composer rather than separate raster hacks. Check Default/Light, Dark, Tinted/Mono/Clear as exposed by the installed Icon Composer version.

Completion criterion: the selected direction has a simple mark, layer separation that Icon Composer can tune, and small-size previews that still read.

## 3. Create The `.icon` Package

An Icon Composer document is a package directory ending in `.icon` with `icon.json` and assets. Keep it in repo as design source, usually under `docs/design/app-icon-composer/<Name>.icon/`.

Use stable layer names such as:

- `01-chat-outline.svg`
- `02-inner-signal-band.svg`
- `03-outer-signal-bands.svg`

Make `icon.json` explicit about:

- root fill or automatic fill
- groups and layer image names
- appearance-specific fill or blend-mode specializations
- Liquid Glass, shadow, translucency, blur/material, and scale
- supported platforms

If scripting the package, preserve user edits made in Icon Composer. Once the user tweaks the GUI, treat the saved `.icon` as source of truth and diff before regenerating.

Completion criterion: Icon Composer opens the package and shows the expected layer stack.

## 4. Wire Xcode To The `.icon`

Xcode's asset compiler accepts Icon Composer packages as `folder.iconcomposer.icon`. Wire the package as a resource input and point the app icon setting at the package base name.

In the Xcode project:

- Add a `PBXFileReference` with `lastKnownFileType = folder.iconcomposer.icon`.
- Add the `.icon` file reference to the app target group.
- Add a `PBXBuildFile` for the `.icon`.
- Add that build file to the app target `PBXResourcesBuildPhase`.
- Set `ASSETCATALOG_COMPILER_APPICON_NAME = <IconPackageBaseName>` for Debug and Release.
- Keep `Assets.xcassets` for other assets such as `AccentColor`, but remove obsolete `AppIcon.appiconset` fallback files when the `.icon` source compiles.

Completion criterion: `xcodebuild` invokes `actool` with both the asset catalog and the `.icon` package, and with `--app-icon <IconPackageBaseName>`.

## 5. Verify The Build

Build for simulator first:

```zsh
xcodebuild \
  -project <App.xcodeproj> \
  -scheme <Scheme> \
  -destination 'generic/platform=iOS Simulator' \
  -derivedDataPath .build/XcodeDerivedData \
  CODE_SIGNING_ALLOWED=NO \
  build
```

Confirm the output shows `CompileAssetCatalog` or `GenerateAssetSymbols` receiving the `.icon` path. Then inspect the built app:

```zsh
plutil -p .build/XcodeDerivedData/Build/Products/Debug-iphonesimulator/<App>.app/Info.plist | rg 'CFBundleIcon|CFBundleIcons'
find .build/XcodeDerivedData/Build/Products/Debug-iphonesimulator/<App>.app -maxdepth 1 -type f \( -name '*Icon*.png' -o -name '<IconName>*.png' \) -print
```

Completion criterion: build succeeds, `CFBundleIconName` is the Icon Composer package base name, and generated icon renditions exist in the built app.

## 6. Verify In Simulator

Use XcodeBuildMCP for simulator build/run when available. Call `session_show_defaults` first, set missing defaults, then run or launch.

If using `simctl`, simulator commands may need elevated access because CoreSimulator writes outside the workspace. Launch directly after install:

```zsh
xcrun simctl install <simulator-udid> .build/XcodeDerivedData/Build/Products/Debug-iphonesimulator/<App>.app
xcrun simctl launch <simulator-udid> <bundle-id>
```

If the icon does not update on the Home Screen, treat it as a simulator cache issue before changing assets: uninstall the app, reboot the simulator, or restart Simulator/CoreSimulator, then reinstall. Do not reintroduce fallback PNGs to appease the cache.

Capture screenshots for remote review:

- Home Screen icon visible after install
- app foreground after launch
- Icon Composer window if visual tuning happened in the GUI

Completion criterion: the app launches in simulator, the Home Screen shows the expected icon, and the user gets screenshot evidence when they are remote.

From thuringia/dotfiles, MIT.

More from thuringia/dotfiles