zsxink/skills-hub/macos-dmg-packaging

macOS DMG Packaging

Use this skill when a user asks to create, improve, debug, or release a macOS .dmg installer. It covers Tauri/create-dmg based installers and general Finder layout issues.

Core model

A DMG has two separate concerns:

1. The payload: the .app, /Applications symlink, and .background/<file>.
2. Finder presentation: .DS_Store records controlling the window, icon positions, icon size, arrangement, and background image alias.

Do not assume that a background file being present means Finder will display it. For a picture background, the final .DS_Store must contain an icvp record with a valid backgroundImageAlias and a picture backgroundType (normally 2). backgroundType=0 is a color/plain background. A nonzero type without a valid alias is still insufficient.

Required workflow

1. Inspect the project’s packaging configuration, current branch/worktree state, and existing DMG scripts before editing.
2. Keep the design source separate from the packaged raster. Prefer an SVG source plus a generated PNG.
3. Make the background exactly match the configured Finder content-area size in points/pixels. Keep all artwork away from the two icon-and-label safety zones.
4. Build the DMG first, then post-process the final artifact. Do not rely only on Tauri’s bundle.macOS.dmg fields for icon size or arrangement; Tauri’s schema does not expose every Finder setting and create-dmg AppleScript behavior varies by macOS version.
5. Rewrite or generate .DS_Store after the bundle step. The reliable picture-background shape is:

• backgroundType=2
• backgroundImageAlias pointing to .background/<file> on the same mounted volume
• arrangeBy=none
• configured iconSize, textSize, and Iloc coordinates
• configured bwsp.WindowBounds

1. Verify the mounted final DMG, not just the build log. Confirm the background file bytes, alias, background type, arrangement, icon records, and window size.
2. If the project exposes a normal tauri build command, hook the post-processing into that command so users cannot accidentally produce an unstyled DMG. Keep an explicit build:dmg command too when useful.

Background design guidance

• Use the app’s existing brand colors and icon geometry.
• Keep the central drag arrow visually aligned with the two icon centers.
• Use low-contrast decoration outside the icon safety zones; Finder labels are rendered on top of the background.
• Keep copy short and test both light/dark Finder appearance if the OS or asset supports it.
• Do not place important text under the window toolbar or near the icon labels.
• A 1× source matching the configured window dimensions is the safest default for Finder background images; validate on a Retina screenshot because the window may appear at 2×.

Debugging checklist

When the window is white or icons are default-sized:

• Confirm the opened DMG is the newly built artifact and eject older volumes with the same name.
• Mount the final DMG read-only and inspect .background/ and .DS_Store.
• backgroundType=0 means the picture was not selected.
• Missing backgroundImageAlias means Finder has no image target.
• An alias whose volume/path points to a temporary build mount may fail after the DMG is remounted; generate it from a stable standard /Volumes/<volume> attachment when possible, or use a native alias-aware DS_Store writer.
• arrangeBy=name or another non-none value makes Finder ignore Iloc coordinates.
• Icon size 48 is Finder’s common default; compare it with the intended configured size.
• Reopen the DMG after ejecting the old volume; Finder may retain a window for the previous mount.

For the detailed record layout and validation fields, read references/ds-store-and-validation.md.