App Icons Guide

Every Forge app needs an icon for bundling. This guide covers icon requirements, CLI tools, and platform-specific details.

Requirements

Your app icon must meet these specifications:

Requirement	Value
Format	PNG with transparency (RGBA)
Recommended Size	1024x1024 pixels
Minimum Size	512x512 pixels
Aspect Ratio	Square (1:1) - Required

Recommended location: assets/icon.png

Quick Start

# Create a placeholder icon
forge icon create my-app/assets/icon.png

# Validate your icon
forge icon validate my-app

CLI Commands

forge icon create

Creates a placeholder icon at the specified path.

forge icon create <path>

Arguments:

<path> - Output path for the icon file

Example:

forge icon create my-app/assets/icon.png

Output:

Creating placeholder icon at my-app/assets/icon.png

Placeholder icon created!
  Path: my-app/assets/icon.png
  Size: 1024x1024 pixels

IMPORTANT: Replace this placeholder with your actual app icon before release.

Icon Requirements:
  - Format: PNG with transparency (RGBA)
  - Size: 1024x1024 pixels (minimum 512x512)
  - Shape: Square (1:1 aspect ratio)

Notes:

The command fails if the file already exists
Parent directories are created automatically
The placeholder is a blue-purple gradient with circular mask

forge icon validate

Validates an app’s icon against requirements.

forge icon validate <app-dir>

Arguments:

<app-dir> - Path to app directory (default: current directory)

Example:

forge icon validate my-app

Output (valid icon):

Validating icon for app at my-app

Searching for icon...
  ✓ found my-app/assets/icon.png
  ✗ not found my-app/assets/icon.icns
  ✗ not found my-app/assets/icon.ico
  ✗ not found my-app/icon.png

Validating: my-app/assets/icon.png

Icon Properties:
  Size: 1024x1024 pixels
  Square: Yes ✓
  Meets minimum (512x512): Yes ✓
  Meets recommended (1024x1024): Yes ✓
  Has transparency: Yes ✓

✓ Icon validation passed!

Output (invalid icon):

Icon Properties:
  Size: 800x600 pixels
  Square: No ✗
  Meets minimum (512x512): Yes ✓
  Meets recommended (1024x1024): No
  Has transparency: Yes ✓

Errors:
  ✗ Icon must be square. Current size: 800x600 (aspect ratio: 1.33:1)

Icon validation failed with 1 error(s). Please fix the issues above.

Manifest Configuration

Specify a custom icon path in manifest.app.toml:

[bundle]
icon = "assets/icon"  # Without extension

The bundler searches for files with .png, .icns, or .ico extensions.

Search paths (in order):

{icon_base}.png
{icon_base}.icns
{icon_base}.ico
{icon_base}/icon.png
{icon_base}/1024x1024.png

Default search (no icon specified):

assets/icon.png
assets/icon.icns
assets/icon.ico
icon.png

Platform-Specific Icons

Forge automatically generates platform-specific icon formats during bundling.

macOS (.icns)

The .icns format is generated using Apple’s iconutil command. Forge creates all required sizes:

Size	Filename	Retina
16x16	icon_16x16.png	No
32x32	icon_16x16@2x.png	Yes
32x32	icon_32x32.png	No
64x64	icon_32x32@2x.png	Yes
128x128	icon_128x128.png	No
256x256	icon_128x128@2x.png	Yes
256x256	icon_256x256.png	No
512x512	icon_256x256@2x.png	Yes
512x512	icon_512x512.png	No
1024x1024	icon_512x512@2x.png	Yes

Bundle location: Contents/Resources/AppIcon.icns

Windows (MSIX Icons)

MSIX packages require multiple icon sizes for different display contexts:

Square icons (app list, taskbar):

Base Size	Scales	Used For
44x44	100%, 125%, 150%, 200%, 400%	Taskbar, Start menu
150x150	100%, 125%, 150%, 200%, 400%	Start menu tile

Wide icons (tiles, splash):

Base Size	Scales	Used For
310x150	100%, 125%, 150%, 200%	Wide tile
50x50	100%, 125%, 150%, 200%	Store logo
620x300	100%, 125%, 150%, 200%	Splash screen

Wide icons are generated by centering your square icon on a transparent background.

Bundle location: Assets/ directory within MSIX package

Linux (Hicolor Theme)

Linux uses the freedesktop.org icon theme specification. Forge creates icons for the hicolor theme:

Size	Location
16x16	usr/share/icons/hicolor/16x16/apps/{name}.png
32x32	usr/share/icons/hicolor/32x32/apps/{name}.png
48x48	usr/share/icons/hicolor/48x48/apps/{name}.png
64x64	usr/share/icons/hicolor/64x64/apps/{name}.png
128x128	usr/share/icons/hicolor/128x128/apps/{name}.png
256x256	usr/share/icons/hicolor/256x256/apps/{name}.png
512x512	usr/share/icons/hicolor/512x512/apps/{name}.png

A 256x256 icon is also placed at the AppImage root for file managers.

Design Guidelines

General Tips

Start at 1024x1024 - Create your master icon at the highest resolution
Use simple shapes - Fine details are lost at small sizes
Test at multiple sizes - Preview at 16x16, 32x32, 128x128, and 512x512
Include transparency - Use alpha channel for rounded corners or shapes
Avoid text - Text is illegible at small sizes
Consider dark/light modes - Ensure visibility on both backgrounds

Platform Considerations

macOS:

Icons appear in Dock, Finder, and Spotlight
The system may add shadows/gloss effects
Rounded rectangle mask is applied automatically by macOS

Windows:

Icons appear in Start menu, taskbar, and file explorer
Consider how wide tiles look with your icon centered
Test with light and dark themes

Linux:

Icons appear in various desktop environments (GNOME, KDE, etc.)
Some environments apply their own styling
Ensure icon is recognizable in app launchers

Build Integration

Creating a New App

When copying an example to start a new app, create an icon:

Create the assets/ directory if needed
Run forge icon create my-app/assets/icon.png to create a placeholder

During `forge build`

The build command validates your icon and warns about issues:

Building app at ./my-app
  Checking app icon...
  Icon: assets/icon.png (1024x1024) ✓

Or with warnings:

  ⚠ Icon: Icon is 768x768. Recommended size is 1024x1024 for best quality.

Or if missing:

  ⚠ No app icon found!
    Bundling will fail without an icon.
    Run 'forge icon create ./my-app/assets/icon.png' to create a placeholder.
    Or add your own 1024x1024 PNG to ./my-app/assets/icon.png

During `forge bundle`

Bundling requires a valid icon. The process will fail if:

No icon is found
Icon is too small (< 512x512)
Icon is not square

Troubleshooting

”No app icon found!”

Cause: No icon file exists in any search location.

Solutions:

Create a placeholder: forge icon create my-app/assets/icon.png
Add your icon to assets/icon.png
Specify a custom path in manifest:
```
[bundle]
icon = "path/to/icon"
```

“Icon is too small”

Cause: Icon dimensions are less than 512x512 pixels.

Solution: Create a larger icon (1024x1024 recommended). If you only have a smaller source, upscale it in an image editor, but quality will suffer.

”Icon must be square”

Cause: Icon width and height are different.

Solution: Resize your icon to have equal width and height. If your logo is not square:

Create a square canvas (e.g., 1024x1024)
Center your logo on it
Use transparency for the background

”Icon is missing transparency”

Cause: PNG doesn’t have an alpha channel.

Solution: Re-export your icon as PNG-24 with transparency enabled in your image editor.

Note: This is a warning, not an error. Your app will still bundle, but icons may look better with transparency.

”Failed to load icon”

Cause: File is corrupted or not a valid image format.