docs: enhance icon generation guide with macOS support (#254)

Co-authored-by: Erick Zhao <erick@hotmail.ca>

Author: 0xlau

guides/create-and-add-icons.md

@@ -8,7 +8,7 @@ description: >-
 
 ## Generating an icon
 
-Generating your icon can be done using various conversion tools found online. It is recommended to start with a 1024x1024px image before converting it to various sizes.
+Generating your icon can be done using various conversion tools found online. It is recommended to start with a 1024x1024px image before converting it to the formats required by each platform.
 
 ### Supporting higher pixel densities
 
@@ -33,19 +33,23 @@ The following suffixes for DPI are also supported:
 
 The recommended file formats and icon sizes for each platform are as follows:
 
-| Operating system | Format  | Size                                           |
-| ---------------- | ------- | ---------------------------------------------- |
-| macOS            | `.icns` | 512x512 pixels (1024x1024 for Retina displays) |
-| Windows          | `.ico`  | 256x256 pixels                                 |
-| Linux            | `.png`  | 512x512 pixels                                 |
+| Operating system | Format                      | Size / notes                                                                                                               |
+| ---------------- | --------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| macOS            | `.icns` (or `.icon`)        | Use a 1024x1024 source image. Keep an `.icns` file for compatibility, and add an Icon Composer `.icon` file for macOS 26+. |
+| Windows          | `.ico`                      | 256x256 pixels                                                                                                             |
+| Linux            | `.png`                      | 512x512 pixels                                                                                                             |
 
 {% hint style="warning" %}
 On Windows, ensure that your `.ico` file is exported from an image editor that supports the format (such as [GIMP](https://www.gimp.org/)). Renaming a `.png` file into `.ico` will result in a `Fatal error: Unable to set icon` error.
 {% endhint %}
 
+{% hint style="info" %}
+`@electron/packager` supports macOS Icon Composer files as of [`@electron/packager` v18.4.0](https://github.com/electron/packager/releases/tag/v18.4.0). To support both macOS 26+ and earlier releases, provide both an `.icns` file and a `.icon` file.
+{% endhint %}
+
 ## Setting the app icon
 
-### Windows and macOS
+### Windows
 
 Configuring the path to your icon can be done in your Forge configuration.
 
@@ -62,7 +66,52 @@ module.exports = {
 {% endcode %}
 
 {% hint style="success" %}
-Forge will automatically add the correct extension for each platform, so appending `.ico` or `.icns` to the path is not required.
+When you provide a single icon path, Electron Packager will automatically add the correct platform extension, so appending `.ico` here is not required.
+{% endhint %}
+
+After the config has been updated, build your project to generate your executable with the Make command.
+
+### macOS
+
+If you only need the traditional macOS icon format, you can continue to provide a single `icon` path in `packagerConfig`:
+
+{% code title="forge.config.js" %}
+```javascript
+module.exports = {
+  // ...
+  packagerConfig: {
+    icon: '/path/to/icon' // .icns will be inferred
+  }
+  // ...
+};
+```
+{% endcode %}
+
+If you need one configuration that supports both macOS 26+ and earlier macOS releases, provide both an `.icns` file and an `.icon` file:
+
+{% code title="forge.config.js" %}
+```javascript
+module.exports = {
+  // ...
+  packagerConfig: {
+    icon: [
+      '/path/to/icon.icns',
+      '/path/to/icon.icon'
+    ]
+  }
+  // ...
+};
+```
+{% endcode %}
+
+Electron Packager will use the `.icns` file on macOS versions earlier than 26, and the `.icon` file on macOS 26 and later.
+
+{% hint style="warning" %}
+Packaging an `.icon` file currently requires macOS 26 or later and Xcode 26 or later because Electron Packager uses Apple's `actool` tool to compile the Icon Composer asset.
+{% endhint %}
+
+{% hint style="info" %}
+When you provide multiple macOS icon files, include the file extensions explicitly so Packager can distinguish the `.icns` and `.icon` inputs.
 {% endhint %}
 
 After the config has been updated, build your project to generate your executable with the Make command.