# How to Switch Between macOS App Icon Options in OpenLogi

> Discover OpenLogi's macOS app icon options, including the default and Prism. Easily switch between them using the Settings UI, TOML file, or Rust API.

- Repository: [Xuan Zhang/OpenLogi](https://github.com/AprilNEA/OpenLogi)
- Tags: how-to-guide
- Published: 2026-09-03

---

**OpenLogi ships with two macOS app icon options—the default OpenLogi (purple-blue gradient) and Prism (high-contrast monochrome)—which can be switched via the Settings UI, by editing the TOML configuration file, or programmatically through the Rust API.**

OpenLogi provides multiple application icon themes to accommodate different accessibility needs and aesthetic preferences on macOS. These macOS app icon options are defined as variants of the `AppIcon` enum in the core configuration module and compiled into the application bundle during the build process.

## Available macOS App Icon Themes in OpenLogi

The available icons are defined in [`crates/openlogi-core/src/config/settings.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-core/src/config/settings.rs) as variants of the `AppIcon` enum.

**Openlogi (Default)**
- **Asset source:** `design/icon/openlogi.icon`
- **Compiled output:** `crates/openlogi-desktop/icon/AppIcon.icns`
- **Visual style:** Purple-blue gradient logo
- **Use case:** Standard branding across all platforms

**Prism**
- **Asset source:** `design/icon/openlogi-prism.icon`
- **Compiled output:** `crates/openlogi-desktop/icon/AppIcon.icns` (overwrites default during build)
- **Visual style:** High-contrast monochrome design
- **Use case:** Optimized for dark mode and accessibility requirements

During compilation, the build script located at [`xtask/src/icon/macos.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/xtask/src/icon/macos.rs) uses Apple’s `actool` to convert the selected `.icon` source file into the `.icns` bundle referenced by the macOS bundle’s `Info.plist` via the `CFBundleIconFile` key.

## How to Change macOS App Icons in OpenLogi

You can switch between icon themes through three methods: the graphical preferences pane, direct configuration file editing, or the Rust API.

### Using the Settings UI

The simplest method uses the native preferences interface implemented in [`crates/openlogi-desktop/src/windows/settings/appearance.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-desktop/src/windows/settings/appearance.rs):

1. Open OpenLogi and navigate to **Settings → Appearance → App Icon**
2. Select either **OpenLogi** or **Prism** from the radio button options
3. The change applies immediately to the dock icon

The UI persists the selection to the user’s `AppSettings` storage, which the application reads on subsequent launches.

### Editing the Configuration File (TOML)

For headless environments or automation, modify the TOML configuration directly at `~/.config/openlogi/config.toml`:

```toml
[app_settings]
app_icon = "Prism"   # Options: "Openlogi" or "Prism"

```

After saving the file, execute `openlogi restart` or fully quit and relaunch the application. The desktop process reads the `app_icon` field from `AppSettings` on startup and applies the specified icon via the helpers in [`crates/openlogi-desktop/src/platform/app_icon.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-desktop/src/platform/app_icon.rs).

### Programmatic Switching (Rust API)

Developers integrating OpenLogi components can change icons at runtime using the core configuration API:

```rust
use openlogi_core::config::{AppIcon, AppSettings};

// Load persisted settings
let mut settings = AppSettings::load()?;

// Switch to the Prism variant
settings.app_icon = AppIcon::Prism;
settings.save()?;

// Apply immediately to dock and tray
openlogi_desktop::platform::app_icon::apply(AppIcon::Prism);
openlogi_agent::tray::set_icon(AppIcon::Prism);

```

The `apply()` function in [`crates/openlogi-desktop/src/platform/app_icon.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-desktop/src/platform/app_icon.rs) handles the platform-specific logic for updating the dock icon, while `openlogi_agent::tray::set_icon()` synchronizes the system tray icon without requiring an application restart.

## How Icon Switching Works Under the Hood

When you select a different macOS app icon option, OpenLogi propagates the change through several architectural layers to ensure UI consistency.

The `AppIcon` enum in [`crates/openlogi-core/src/config/settings.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-core/src/config/settings.rs) defines the available options and derives serialization traits for TOML storage. At runtime, the desktop application references `CFBundleIconFile` in the macOS bundle’s `Info.plist` to locate `AppIcon.icns`, while the background agent process uses [`crates/openlogi-agent/src/tray.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-agent/src/tray.rs) to synchronize the system tray icon with the same `AppIcon` variant selected in the user’s `AppSettings`.

Because both icon variants compile to the single output filename `AppIcon.icns` during the build process defined in [`xtask/src/icon/macos.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/xtask/src/icon/macos.rs), the final application bundle contains only the active icon theme rather than shipping both assets simultaneously. This design minimizes bundle size while ensuring the runtime switching logic only needs to reference a single compiled resource.

## Summary

- OpenLogi provides **two macOS app icon options**: the default purple-blue **OpenLogi** theme and the high-contrast **Prism** variant designed for accessibility
- Icons are defined in the `AppIcon` enum in [`crates/openlogi-core/src/config/settings.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-core/src/config/settings.rs)
- Switch via the **Settings → Appearance → App Icon** UI, by editing `~/.config/openlogi/config.toml`, or using the `AppSettings` Rust API
- The [`xtask/src/icon/macos.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/xtask/src/icon/macos.rs) build script compiles source icons from `design/icon/` into `crates/openlogi-desktop/icon/AppIcon.icns`
- Changes apply to both the dock icon (via [`app_icon.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/app_icon.rs)) and system tray (via [`tray.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/tray.rs)) without rebuilding the application

## Frequently Asked Questions

### Does the icon change persist after restarting my Mac?

Yes. The selection is stored in the `app_icon` field of `~/.config/openlogi/config.toml` within the `AppSettings` struct. OpenLogi reads this configuration on every launch, ensuring your preferred macOS app icon option remains active across system restarts and application updates.

### Will changing the app icon also change the system tray icon?

Yes. When you change icons through the Settings UI or API, OpenLogi synchronizes the change across both the dock application icon and the menu bar tray icon. The `openlogi_agent::tray::set_icon()` function ensures the tray matches the dock icon selected in `AppSettings`.

### Can I use a custom third-party icon instead of OpenLogi or Prism?

Not without modifying the source code. The build system in [`xtask/src/icon/macos.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/xtask/src/icon/macos.rs) only accepts the predefined `Openlogi` or `Prism` variants defined in the `AppIcon` enum. To use a custom icon, you would need to add a new variant to [`crates/openlogi-core/src/config/settings.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-core/src/config/settings.rs) and provide a corresponding `.icon` source file in `design/icon/`.

### Do I need to rebuild OpenLogi to switch between icons?

No for runtime switching, yes for build-time changes. You can switch between the two available macOS app icon options at runtime using the Settings UI or TOML configuration. However, because both variants compile to the single `AppIcon.icns` file, creating a custom build requires running the compilation script in [`xtask/src/icon/macos.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/xtask/src/icon/macos.rs) to generate a new `.icns` bundle.