|
| 1 | +# App icons |
| 2 | + |
| 3 | +## Source files |
| 4 | + |
| 5 | +- **Original artwork**: `_ignored/designs/app-logo-1024px-x-1024px.png` (1024x1024 PNG, transparent background) |
| 6 | +- **Icon Composer project**: `_ignored/designs/Sequoia.icon` (macOS Tahoe Liquid Glass format) |
| 7 | + |
| 8 | +## What gets bundled |
| 9 | + |
| 10 | +Two icon systems coexist in the final `.app` for backward compatibility: |
| 11 | + |
| 12 | +| File | Location in bundle | Used by | Generated from | |
| 13 | +|------|--------------------|---------|----------------| |
| 14 | +| `icons/icon.icns` + PNGs | `Contents/Resources/icon.icns` | macOS pre-Tahoe (via `CFBundleIconFile`) | `pnpm tauri icon` | |
| 15 | +| `resources/Assets.car` | `Contents/Resources/Assets.car` | macOS Tahoe 26+ (via `CFBundleIconName`) | `actool` from `.icon` file | |
| 16 | +| `icons/icon.ico` + Square PNGs | Windows/Store | Windows | `pnpm tauri icon` | |
| 17 | + |
| 18 | +`Info.plist` has `CFBundleIconName` = `"Sequoia"` which tells Tahoe to look in `Assets.car`. |
| 19 | +Older macOS ignores this and falls back to `CFBundleIconFile` (set automatically by Tauri). |
| 20 | + |
| 21 | +## Regenerating icons |
| 22 | + |
| 23 | +### All platforms (PNGs, .icns, .ico) |
| 24 | + |
| 25 | +```bash |
| 26 | +cd apps/desktop |
| 27 | +pnpm tauri icon ../../_ignored/designs/app-logo-1024px-x-1024px.png |
| 28 | +``` |
| 29 | + |
| 30 | +This overwrites everything in `src-tauri/icons/`. |
| 31 | + |
| 32 | +### macOS Tahoe Liquid Glass icon (Assets.car) |
| 33 | + |
| 34 | +1. Open Icon Composer (bundled with Xcode at `/Applications/Xcode.app/Contents/Applications/Icon Composer.app`) |
| 35 | +2. Import the 1024x1024 PNG, adjust layers/translucency as desired |
| 36 | +3. Export as `.icon` to `_ignored/designs/Sequoia.icon` |
| 37 | +4. Compile: |
| 38 | + |
| 39 | +```bash |
| 40 | +actool _ignored/designs/Sequoia.icon \ |
| 41 | + --compile apps/desktop/src-tauri/resources \ |
| 42 | + --output-format human-readable-text --notices --warnings --errors \ |
| 43 | + --output-partial-info-plist /dev/null \ |
| 44 | + --app-icon Sequoia --include-all-app-icons \ |
| 45 | + --enable-on-demand-resources NO \ |
| 46 | + --target-device mac \ |
| 47 | + --minimum-deployment-target 26.0 \ |
| 48 | + --platform macosx |
| 49 | +``` |
| 50 | + |
| 51 | +This produces `resources/Assets.car` (and a `Sequoia.icns` fallback, not currently used). |
| 52 | + |
| 53 | +### Gotchas |
| 54 | + |
| 55 | +- **`actool` needs Xcode first-launch**: If `actool` fails with a plugin error, run `xcodebuild -runFirstLaunch`. |
| 56 | +- **`--app-icon` name matters**: The name passed to `--app-icon` (here `Sequoia`) must match `CFBundleIconName` |
| 57 | + in `Info.plist`. If you change one, change both. |
| 58 | +- **Tahoe squircle jail**: macOS Tahoe analyzes icon pixels. If the icon doesn't fill the expected squircle area, |
| 59 | + the system shrinks it and adds a dark gray background. The `Assets.car` approach avoids this entirely. |
| 60 | +- **Tauri native support pending**: Tauri has a commit ready to support `.icon` files natively |
| 61 | + ([tauri#14207](https://github.com/tauri-apps/tauri/issues/14207)). Once shipped, the manual `actool` step and |
| 62 | + `bundle.macOS.files` config can be replaced with a path in the `bundle.icon` array. |
0 commit comments