gnome-svg-icons
Custom SVG Icons in GNOME Apps
Implement custom artwork through the host application's existing icon helper and packaging conventions. Preserve the supplied SVG geometry and intended palette. A theme-color bug should be fixed in loading or recoloring, not by substituting different artwork.
This guide targets GTK 4/libadwaita with GJS examples and does not assume a particular application or repository layout. Adapt bindings for other languages. Distinguish GTK's native symbolic rendering from explicit SVG recoloring; they have different color and lifecycle behavior.
Choose the Rendering Path
Inspect the existing helper, a call site, SVG files, resource manifest, install rules, and icon tests before editing. Check the supported GTK/librsvg versions when relying on newer SVG symbolic features.
| Requirement | Rendering path |
|---|---|
| Monochrome controls following widget foreground, including suggested/destructive states | Native named symbolic icon through Gtk.IconTheme and Gtk.Image |
| A reproduced platform issue with native SVG recoloring | Use a shared helper to explicitly recolor and rerender on appearance changes |
| Logo or artwork with fixed brand colors | Regular SVG through a file icon or paintable; preserve its colors |
| Mixed fixed accents and theme-dependent foreground | Explicitly recolor only the designated foreground token |
An arbitrary multicolor palette is not equivalent to GTK's semantic success/warning/error palette. Do not force brand artwork through the symbolic pipeline. Inspect the SVG and its intended appearance instead of classifying artwork by filename alone.