native-theme-gtk

Resolve the user's effective GTK 4 theme into a versioned JSON snapshot.

This crate asks GTK to resolve the theme, including its normal lookup rules and user CSS overrides. It does not attempt to implement a second GTK CSS parser. On GTK 4.20 and newer, the desktop's explicit interface color scheme is applied before sampling so dark and light variants produce their effective colors. An explicit GTK_THEME environment override remains authoritative.

$ native-theme-gtk > gtk-theme.json

The snapshot currently contains:

• GTK theme, display backend, font, icon, and cursor settings
• animation, scrolling, input, color-scheme, contrast, reduced-motion, and dark-variant preferences (when supported by the GTK runtime)
• GTK and libadwaita symbolic colors recognized by the active theme
• a toolkit-neutral semantic palette derived from those symbolic colors
• preferred sizes and foreground colors for representative widgets across normal, hovered, pressed, focused, checked, selected, disabled, and inactive states

Process model

probe() initializes GTK and must be called from the main thread. A GPUI, iced, or other non-GTK application should normally execute the CLI in a subprocess and deserialize its output. This keeps the two GUI event loops and global toolkit state isolated.

GPUI integration

Enable the optional bridge to the existing native-theme-gpui crate:

native-theme-gtk = { version = "0.1", features = ["gpui"] }

Keep the probe in a subprocess, deserialize its snapshot, and build a complete gpui-component theme:

let snapshot: native_theme_gtk::ThemeSnapshot =
    serde_json::from_slice(&probe_output.stdout)?;
let theme: gpui_component::theme::Theme = snapshot.to_gpui_theme()?;

// During GPUI application setup, after gpui_component::init(cx):
cx.set_global(theme);

resolve_native_theme() exposes the intermediate native_theme::ResolvedTheme when an application needs it. The GTK values are merged over native-theme's Adwaita preset, which supplies fields GTK does not expose through its public theme API. Call snapshot.validate() after deserializing snapshots received from any source other than this crate's probe.

GTK 3 and deeper GTK 4 render-node extraction are intentionally left for later backends. The schema is versioned so those additions can remain compatible.

Development

nix develop
cargo test
cargo run

Display-independent tests run with cargo test. To include the GTK integration matrix against the current display:

NATIVE_THEME_RUN_LIVE_TESTS=1 cargo test --test cli

./scripts/check is the same format, test, strict Clippy, and rustdoc gate used by CI. CI runs the live matrix under a virtual X11 display.