iOS and iPadOS can display an app icon in three appearances: Light, Dark, and Tinted. The tedious approach is to create three files manually, drag each one into Xcode, and hope the asset catalog metadata stays correct. A better workflow is to let Codex for macOS generate the variants, write them directly into Assets.xcassets/AppIcon.appiconset, update Contents.json, and verify the result.
This guide shows a repository-first workflow: no Finder-to-Xcode dragging and no repetitive copy and paste. Codex works on the project files in place, so every change appears in Xcode automatically.
What Apple expects
Apple’s current guidance describes Light, Dark, and Tinted app-icon appearances for iOS and iPadOS. For the asset-catalog route, the Tinted artwork should be grayscale, while the Dark version can use transparency so the system background can show through. Xcode can also generate a treatment automatically when you provide only the primary icon, but custom variants give you control over contrast, hierarchy, and brand character. See Apple’s guides to configuring app icons in an asset catalog and the App Icons Human Interface Guidelines.
Before you ask Codex to edit the catalog
- Open the folder containing your Xcode project in Codex for macOS.
- Make sure the project builds before changing artwork.
- Commit your current work or create a Git checkpoint.
- Locate
Assets.xcassets/AppIcon.appiconset. - Keep the master icon or design reference in the repository so Codex can use it consistently.
OpenAI’s official Codex use cases include building and debugging iOS projects. The same local-project workflow is ideal for asset-catalog maintenance because Codex can inspect the existing structure, edit files, and report a diff for review.
The prompt: generate and install all three icons
Start with a prompt that gives Codex clear authority, constraints, filenames, and validation requirements:
Inspect this Xcode project and find the active iOS app icon set.
Use the existing master icon as the visual reference. Create three coordinated 1024 Ă— 1024 PNG variants:
- AppIcon-Light.png: the standard full-color icon for Light appearance.
- AppIcon-Dark.png: a dark-appearance version with strong contrast and a transparent background where appropriate.
- AppIcon-Tinted.png: a clean grayscale/monochrome version designed for the system tint treatment.
Write the files directly into Assets.xcassets/AppIcon.appiconset. Update Contents.json so the variants map to the default, dark, and tinted luminosity appearances. Do not rename the asset set or change unrelated assets.
Before editing, back up the current Contents.json. After editing, validate the JSON, inspect image dimensions and alpha channels, run the project’s safest available build check, and show me the final diff.If your master artwork is outside the repository, place it in a temporary project folder first. Once Codex can see that file, it can create the variants and install them without sending you through a manual drag-and-drop loop.
What Codex changes inside AppIcon.appiconset
The result is a small, reviewable set of files:
Assets.xcassets/
└── AppIcon.appiconset/
├── AppIcon-Light.png
├── AppIcon-Dark.png
├── AppIcon-Tinted.png
└── Contents.jsonA typical single-size iOS mapping looks like this:
{
"images" : [
{
"filename" : "AppIcon-Light.png",
"idiom" : "universal",
"platform" : "ios",
"size" : "1024x1024"
},
{
"appearances" : [
{ "appearance" : "luminosity", "value" : "dark" }
],
"filename" : "AppIcon-Dark.png",
"idiom" : "universal",
"platform" : "ios",
"size" : "1024x1024"
},
{
"appearances" : [
{ "appearance" : "luminosity", "value" : "tinted" }
],
"filename" : "AppIcon-Tinted.png",
"idiom" : "universal",
"platform" : "ios",
"size" : "1024x1024"
}
],
"info" : {
"author" : "xcode",
"version" : 1
}
}Treat that JSON as an example, not a blind replacement. Existing projects can include additional platforms, legacy slots, or Xcode-generated metadata. Codex should merge the three iOS entries into the structure it actually finds.
A safer two-pass workflow
Pass 1: inspect and propose
Inspect the current AppIcon.appiconset without changing files. Report its platforms, sizes, appearance entries, filenames, and any risks. Then propose the exact files and Contents.json edits needed for Light, Dark, and Tinted iOS icons.Pass 2: implement and verify
Implement the approved plan. Preserve unrelated entries. Validate every PNG as 1024 × 1024, confirm the tinted asset is grayscale, check the dark asset’s alpha channel, validate Contents.json, and run an Xcode build or asset-catalog compilation check. Stop and report if any validation fails.How to preview the three appearances
- Open
Assets.xcassetsin Xcode. - Select
AppIconand confirm the Any, Dark, and Tinted wells are populated. - Build and run on a recent iOS Simulator.
- Long-press the Home Screen, choose the customization controls, and switch among Light, Dark, and Tinted appearances.
- Test several tint colors. A tinted icon that looks good only in blue is not finished.
Pro tips
- Design Tinted as a mask, not a desaturated poster. Remove tiny color-dependent details and preserve a strong silhouette.
- Do not simply invert Light for Dark. Rebalance highlights, shadows, and edge contrast.
- Ask Codex to preserve geometry. The symbol, padding, and optical center should remain consistent across all three variants.
- Keep generated intermediates out of the asset set. Only final PNGs and valid catalog metadata belong in
AppIcon.appiconset. - Review the diff. A three-icon task should not modify unrelated Swift files, build settings, or other assets.
- Prefer Icon Composer for the newest layered workflow. Apple now offers Icon Composer for platform and appearance variants, but the asset-catalog method remains useful for existing projects and explicit PNG control.
The payoff
The real improvement is not just generating three pictures. It is giving Codex responsibility for the complete, verifiable change: create the artwork, name the files, place them inside xcassets, update the appearance metadata, validate the catalog, and show the diff. Xcode sees the result immediately, and you stay focused on design decisions instead of moving files between windows.
