FreeDesktop icon names

freedesktop-icons provides the standard icon names from the FreeDesktop Icon Naming Specification as typed Kotlin constants. Linux icon themes resolve icons by name: instead of shipping info.png, you reference dialog-information and the active theme renders its own version. Other Nucleus Linux modules accept these constants wherever they take an icon.

Add the dependency

dependencies {
    implementation("dev.nucleusframework:nucleus.freedesktop-icons:2.0.7")
}

Reference an icon

Each icon is a value of the sealed interface FreedesktopIcon. Pick a constant from the category enum that matches the icon's context:

import dev.nucleusframework.freedesktop.icons.FreedesktopIcon

val info = FreedesktopIcon.Status.DIALOG_INFORMATION
val open = FreedesktopIcon.Action.DOCUMENT_OPEN
val printer = FreedesktopIcon.Device.PRINTER

For names outside the spec, a file path, or a file:// URI, use FreedesktopIcon.Custom:

val named = FreedesktopIcon.Custom("my-app-icon")           // theme lookup by name
val path = FreedesktopIcon.Custom("/home/user/icon.png")    // absolute path
val uri = FreedesktopIcon.Custom("file:///home/user/icon.png")

FreedesktopIcon.flag builds a country flag name from an ISO 3166-1 alpha-2 code:

val flag = FreedesktopIcon.flag("fr")   // FreedesktopIcon.Custom("flag-fr")

How it works

Every constant carries a value string that holds its spec name — DIALOG_INFORMATION resolves to "dialog-information". Custom and flag wrap arbitrary strings in the same type, so any FreedesktopIcon is ultimately a name that a theme can look up.

When you hand a FreedesktopIcon to a Linux module — notifications, launcher quicklists — the value is sent over D-Bus or written into a .desktop file as plain text. The system's active icon theme turns that name into a concrete image at render time, so the app follows the user's theme without shipping any bitmaps.

The constants are plain strings, so they compile on any platform. Off Linux they resolve to nothing visible, since no FreeDesktop theme is present.

API reference

Categories

FreedesktopIcon is a sealed interface. Each category is an enum whose entries map to spec names; Custom is a value class for everything else.

Build a custom icon

FreedesktopIcon.Custom(value: String) is an inline value class. Its value is used verbatim, whether it is a theme name, an absolute path, or a file:// URI.

Build a country flag

FreedesktopIcon.flag(countryCode: String) lowercases the code and returns Custom("flag-<code>"):

FreedesktopIcon.flag("us")   // Custom("flag-us")
FreedesktopIcon.flag("jp")   // Custom("flag-jp")

Notes

• Not every theme implements every icon name. Sticking to the canonical FreeDesktop set gives the highest chance of a match.
• Flag icons are not part of the FreeDesktop spec and depend on the theme shipping flag-<code> names.

What's next

• Linux notifications — pass a FreedesktopIcon as the notification icon.
• Linux launcher — reuse the same constants in .desktop actions.
• System tray — set a per-theme tray icon by name.