Skip to content

macOS DMG: branded window background and icon layout - #131

Merged
echelon merged 1 commit into
storytold:mainfrom
XusBadia:dmg-background
Oct 9, 2026
Merged

echelon merged 1 commit into
storytold:mainfrom
XusBadia:dmg-background

Conversation

@XusBadia

@XusBadia XusBadia commented Oct 8, 2026 •

Copy link
Copy Markdown
Contributor

What

The macOS DMG opened as a plain white Finder window. It now opens like this:

DesignCraft DMG window in Finder

The icon's figure as a cover on the DesignCraft colour field, DesignCraft.app and the Applications link side by side on Paper, and a small DesignCraft-specific touch: the arrow and the mono line under the title come from the app's craft. Ink, Paper and the app colour only; Inter and JetBrains Mono.

How

Same approach as PhotoCraft's and VectorCraft's, which have landed (storytold/photocraft#1201, storytold/vectorcraft#493):

  • packaging/macos/dmg/background.svg: the source. Its text is outlined, so rendering it needs no fonts, and the figure is an <image> of the existing icon in assets/app-icon/.
  • background.tiff: 1x 660×400 + 2x 1320×800 in one HiDPI TIFF (16-colour palette, Deflate, sRGB; 90 KB). No paper grain: noise doesn't compress, and this keeps the binary small.
  • dmg-layout.DS_Store: Finder's view settings (window 660×400 content, icon size 128, DesignCraft.app at (326, 205), Applications at (574, 205), the background). It's named so it isn't mistaken for, or ignored like, a Finder-generated .DS_Store.
  • generate.py: writes both from the SVG on any OS (pip install 'pillow>=12' ds_store==1.3.3 mac_alias==2.2.3, resvg on PATH). The output is byte-for-byte reproducible and carries nothing from the machine that ran it: no paths, users, disk names or volume UUIDs.
  • package.sh copies the TIFF and the layout into the staging folder. The image is still built with hdiutil makehybrid, and nothing extra runs in the signing job.

One behaviour change: the volume name drops the version

.DS_Store points at the background through an alias that includes the volume name. With DesignCraft <version> Finder kept the window and icon positions but lost the background (tested). So the mounted volume is now called DesignCraft; the DMG file name still carries the version.

Tested

  • Built the image with the exact package.sh steps (staging folder, makehybrid, UDZO) around a stub DesignCraft.app with the real icon, mounted it and opened it in Finder on macOS: the screenshot above is that DMG.
  • Finder draws icon labels in black in both light and dark appearance when the window has a background (checked in both), so the label area stays light.
  • Margin check: no artwork within 10 pt of either 128 pt icon box or of the label strips (pixel diff of the background against the same background without artwork).
  • shellcheck clean; cargo xtask assets passes where the repo has it; generate.py reproduces the committed files byte for byte (6 runs).
  • Not run: a full signed and notarized release build (needs the Developer ID secrets).

Across the suite

Matching PRs for every Crafting App, same layout, each with its own figure and colour:

Crafting Apps DMG windows

🤖 Generated with Claude Code

The DMG opened as a plain Finder window. It now shows the app icon's figure on
the DesignCraft colour, with DesignCraft.app and the Applications link side by side.
Same approach as PhotoCraft's and VectorCraft's (storytold/photocraft#1201,
storytold/vectorcraft#493).

- packaging/macos/dmg/: background.svg (source; text outlined, no paper grain,
  the figure an <image> of assets/app-icon), background.tiff (1x + 2x HiDPI,
  16-colour palette, Deflate, sRGB; ~90 KB)
  and dmg-layout.DS_Store (Finder view settings: window, icon size 128,
  positions, background).
- generate.py writes the TIFF and the layout on any OS, byte-for-byte
  reproducible, with nothing from the machine that ran it (no paths, users,
  disk names or volume UUIDs).
- package.sh copies them into the staging folder; the image is still built with
  hdiutil makehybrid. Nothing extra runs in the signing job.
- The volume name drops the version: the layout finds the background through
  an alias that includes the volume name. The DMG file name keeps the version.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@echelon
echelon merged commit 66c7ce7 into storytold:main Oct 9, 2026
@echelon

echelon commented Oct 9, 2026

Copy link
Copy Markdown
Member

Merged — thank you @XusBadia! The branded DMG window looks great, and thanks for doing the whole Crafting Apps suite with each app's own icon and colour.

We'd love to have you in the community Discord if you're not already there: https://discord.gg/artcraft

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants