Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

fix(desktop): match the macOS app icon size to other apps (#281)

Yiru Dongd786e41c4339
diff --git a/changelog/unreleased/2026-08-14-macos-app-icon-size.md b/changelog/unreleased/2026-08-14-macos-app-icon-size.md
new file mode 100644
index 00000000..d7358329
--- /dev/null
+++ b/changelog/unreleased/2026-08-14-macos-app-icon-size.md
@@ -0,0 +1,5 @@
+# Match the macOS app icon size
+
+PenguinHarness now uses a dedicated macOS icon master with the brand artwork centred inside the platform's safe area, matching the visual size of neighbouring apps in the Dock and Launchpad.
+
+The Windows icon master and Linux icon set remain unchanged.
diff --git a/changelog/unreleased/README.md b/changelog/unreleased/README.md
index 79e701b8..78977f4b 100644
--- a/changelog/unreleased/README.md
+++ b/changelog/unreleased/README.md
@@ -1 +1,3 @@
# Unreleased
+
+- [2026-08-14] Match the macOS app icon's visual size to neighbouring apps. ([details](2026-08-14-macos-app-icon-size.md))
diff --git a/packages/desktop/build/icon-mac.png b/packages/desktop/build/icon-mac.png
new file mode 100644
index 00000000..b1ea11a2
Binary files /dev/null and b/packages/desktop/build/icon-mac.png differ
diff --git a/packages/desktop/electron-builder.yml b/packages/desktop/electron-builder.yml
index 679adc6e..e435a2b4 100644
--- a/packages/desktop/electron-builder.yml
+++ b/packages/desktop/electron-builder.yml
@@ -34,10 +34,10 @@ nodeGypRebuild: false
mac:
category: public.app-category.developer-tools
- # Brand icon (rendered from packages/web/public/penguin-logo.svg by
- # scripts/render-icon.mjs, committed): electron-builder converts the 1024px PNG to
- # icns itself (app-builder-lib iconConverter; >=512px required).
- icon: build/icon.png
+ # macOS-specific 1024px master: scripts/render-icon.mjs centres the brand artwork in
+ # Apple's 824px safe area so it has the same optical size as neighbouring Dock and
+ # Launchpad icons. electron-builder converts the committed PNG to icns.
+ icon: build/icon-mac.png
hardenedRuntime: true
entitlements: build/entitlements.mac.plist
entitlementsInherit: build/entitlements.mac.inherit.plist
diff --git a/packages/desktop/scripts/render-icon.mjs b/packages/desktop/scripts/render-icon.mjs
index d51a0ac9..e98fa2ba 100644
--- a/packages/desktop/scripts/render-icon.mjs
+++ b/packages/desktop/scripts/render-icon.mjs
@@ -6,6 +6,9 @@
* - build/icon.png 1024×1024. electron-builder converts it to icns (mac,
* >=512px required) and ico (win, >=256px) at pack time;
* also the runtime BrowserWindow icon (see src/app-icon.ts).
+ * - build/icon-mac.png 1024×1024 macOS master. The 824px artwork is centred on
+ * the transparent canvas so Finder, Launchpad and the Dock
+ * give it the same optical size as native macOS app icons.
* - build/icons/<N>x<N>.png 128/256/512 freedesktop set for the Linux targets
* (used as-is, no conversion).
*
@@ -34,26 +37,37 @@ const { chromium } = requireLanding("@playwright/test");
const svgDataUrl = `data:image/svg+xml;base64,${readFileSync(SVG_PATH).toString("base64")}`;
-/** [size, output path]; icon.png is the 1024 master, the rest form the Linux icon set. */
+/**
+ * Apple's 1024px app-icon template keeps the full rounded-square artwork inside an
+ * 824×824 safe area. Unlike iOS, macOS does not add this margin for third-party icons:
+ * handing electron-builder edge-to-edge artwork makes the icon visibly larger than its
+ * neighbours in the Dock and Launchpad.
+ */
+const MAC_ARTWORK_RATIO = 824 / 1024;
+
+/** icon.png is the Windows master; icon-mac.png is the padded macOS master. */
const targets = [
- [1024, path.join(BUILD_DIR, "icon.png")],
- [512, path.join(ICON_SET_DIR, "512x512.png")],
- [256, path.join(ICON_SET_DIR, "256x256.png")],
- [128, path.join(ICON_SET_DIR, "128x128.png")],
+ { size: 1024, outPath: path.join(BUILD_DIR, "icon.png"), artworkRatio: 1 },
+ { size: 1024, outPath: path.join(BUILD_DIR, "icon-mac.png"), artworkRatio: MAC_ARTWORK_RATIO },
+ { size: 512, outPath: path.join(ICON_SET_DIR, "512x512.png"), artworkRatio: 1 },
+ { size: 256, outPath: path.join(ICON_SET_DIR, "256x256.png"), artworkRatio: 1 },
+ { size: 128, outPath: path.join(ICON_SET_DIR, "128x128.png"), artworkRatio: 1 },
];
mkdirSync(ICON_SET_DIR, { recursive: true });
const browser = await chromium.launch();
try {
- for (const [size, outPath] of targets) {
+ for (const { size, outPath, artworkRatio } of targets) {
+ const artworkSize = size * artworkRatio;
const page = await browser.newPage({
viewport: { width: size, height: size },
deviceScaleFactor: 1,
});
await page.setContent(
- `<style>html,body{margin:0;padding:0;background:transparent}` +
- `img{display:block;width:${size}px;height:${size}px}</style>` +
+ `<style>html,body{margin:0;padding:0;width:100%;height:100%;background:transparent}` +
+ `body{display:flex;align-items:center;justify-content:center}` +
+ `img{display:block;width:${artworkSize}px;height:${artworkSize}px}</style>` +
`<img src="${svgDataUrl}">`,
);
await page.evaluate(() => document.querySelector("img").decode());
diff --git a/packages/desktop/test/app-icon.test.ts b/packages/desktop/test/app-icon.test.ts
index 86d36944..d1431078 100644
--- a/packages/desktop/test/app-icon.test.ts
+++ b/packages/desktop/test/app-icon.test.ts
@@ -35,3 +35,13 @@ describe("resolveWindowIcon", () => {
expect(resolveWindowIcon(pkgDir, "linux")).toBe(path.join(pkgDir, "build", "icon.png"));
});
});
+
+describe("packaged app icons", () => {
+ const pkgDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+ it("keeps a dedicated macOS master with the platform safe-area margin", () => {
+ const builderConfig = fs.readFileSync(path.join(pkgDir, "electron-builder.yml"), "utf8");
+ expect(builderConfig).toMatch(/mac:[\s\S]*?icon: build\/icon-mac\.png/);
+ expect(fs.existsSync(path.join(pkgDir, "build", "icon-mac.png"))).toBe(true);
+ });
+});