macOS icons fail quietly: a missing @2x pair, an iconutil naming typo, or a Display P3 master that desaturates inside Xcode. For teams shipping a reviewable .iconset and a compiled .icns, here is a format table, the canonical PNG size map, an sRGB checklist, sips/iconutil snippets, and FAQ on corners versus transparent edges. See Tech Insights for PNG color management, ICC metadata & recompress, and iOS App Icon PNG when mobile and desktop ship together.
Table of Contents
Why icon batches break
Three issues recur. Filename contracts: iconutil is strict; wrong pixels under a canonical name fail compile with little design-side context. Color drift: P3 masters beside sRGB UI PNGs split brand yellows across surfaces. Alpha surprises: soft edges read fine on checkerboard but muddy on Dock or Finder. Treat them as blocking; align with OpenClaw PNG QA on remote Mac.
ICNS vs .iconset decision matrix
| Artifact | Best for | Review / diff | Typical consumer |
|---|---|---|---|
.iconset folder |
Source-of-truth PNG set, PR review, partial rerenders | Excellent (per-size Git diffs) | Designers, release managers, Xcode asset workflows |
.icns bundle |
Drop-in binary for tools expecting classic Mac icons | Poor (opaque binary) | Legacy apps, some CI packagers, non-Xcode pipelines |
When in doubt, treat the folder as canonical and regenerate ICNS in CI or a nightly job on an Apple Silicon host so compile flags stay reproducible.
Required .iconset PNG targets
Apple expects a square PNG for each slot below. Keep a 1024×1024 master in sRGB, then derive the grid. This table is the acceptance contract your scripts should assert.
| Filename | Pixels (W×H) |
|---|---|
icon_16x16.png | 16 × 16 |
icon_16x16@2x.png | 32 × 32 |
icon_32x32.png | 32 × 32 |
icon_32x32@2x.png | 64 × 64 |
icon_128x128.png | 128 × 128 |
icon_128x128@2x.png | 256 × 256 |
icon_256x256.png | 256 × 256 |
icon_256x256@2x.png | 512 × 512 |
icon_512x512.png | 512 × 512 |
icon_512x512@2x.png | 1024 × 1024 |
sRGB and ICC acceptance checklist
| Check | Method | Pass criteria |
|---|---|---|
| Color space | Preview inspector or sips -g profile |
Embedded sRGB or documented conversion from P3 masters |
| Bit depth | Export preset audit | Deliver 8-bit PNG per size |
| Alpha policy | Pixel sampler on Dock background | No accidental fringe; opaque icons stay fully solid outside intentional holes |
| Geometry | sips -g pixelWidth -g pixelHeight |
Exact pixels per filename row above |
Pair this table with the deeper rationale in sRGB vs Display P3 for Mac PNG so icon batches inherit the same ICC story as marketing stills.
sips, iconutil and batch steps
Run the following on a remote M4 Mac when laptops should stay cool; loops are short but validation adds up across SKUs.
- Normalize the master to
1024×1024sRGB PNG. - Resize with
sipsinto a folder namedMyIcon.iconset:
MASTER="AppIcon-1024.png"
OUT="MyIcon.iconset"
mkdir -p "$OUT"
sips -z 1024 1024 "$MASTER" --out "$OUT/icon_512x512@2x.png"
sips -z 512 512 "$MASTER" --out "$OUT/icon_512x512.png"
sips -z 512 512 "$MASTER" --out "$OUT/icon_256x256@2x.png"
sips -z 256 256 "$MASTER" --out "$OUT/icon_256x256.png"
sips -z 256 256 "$MASTER" --out "$OUT/icon_128x128@2x.png"
sips -z 128 128 "$MASTER" --out "$OUT/icon_128x128.png"
sips -z 64 64 "$MASTER" --out "$OUT/icon_32x32@2x.png"
sips -z 32 32 "$MASTER" --out "$OUT/icon_32x32.png"
sips -z 32 32 "$MASTER" --out "$OUT/icon_16x16@2x.png"
sips -z 16 16 "$MASTER" --out "$OUT/icon_16x16.png"- Compile with
iconutil -c icns "$OUT" -o MyIcon.icns. - Verify dimensions using a loop over
*.pngas in the iOS icon matrix (samesips -gpattern). - Archive the iconset and ICNS with a manifest row per file for the release ticket.
For heavier PNG pipelines that surround icon work—large canvases, 4K slices—reuse queue habits from batch 4K PNG export on remote Mac M4.
Numbers you can paste into tickets
- 10 PNG files form the standard macOS
.iconsetgrid listed above. - 1024 × 1024 pixels is the largest compiled slot (
icon_512x512@2x.png). - One embedded sRGB profile policy across icon, UI PNG, and marketing reduces brand drift audits.
FAQ: corners, alpha and handoff
Should I bake macOS rounded corners into the PNG? No for production AppKit icons: deliver a full-bleed square; the system applies the mask. Pre-rounded bitmaps often create halos and Dock mismatches. If marketing needs a pre-masked preview, branch that asset outside the iconset.
Why do transparent edges look gray after batch resize? Premultiplied alpha mishandling and non-sRGB workspaces cause fringe on compositing. Keep masters in sRGB, validate on light and dark backgrounds, and tighten padding.
ICNS or PNG folder—which is authoritative? Prefer the .iconset for review; regenerate ICNS whenever PNGs change. Document the rule so CI and design stay aligned.
Summary
Treat the size table and sRGB checklist as non-negotiable acceptance gates, compile with iconutil only after sips outputs validate, and keep square masters without baked corner radii. Offload the loop to a dedicated remote Mac so overnight batches, manifests, and reruns never block your primary workstation.
Next steps
Open the MacPng homepage, compare rental packages and pricing for an M-series node, and read the help center for SSH and VNC setup. Continue in Tech Insights for design-delivery playbooks alongside this icon matrix.
Batch ICNS and PNG iconsets on a remote Mac
Pin macOS versions, run repeatable sips and iconutil jobs, and attach dimension manifests to every release—ideal when desktop and mobile icon drops land in the same week.