Flatpak Theme Integration#
Flatpak sandboxing prevents apps from directly reading host theme files and DConf settings. Instead, system appearance preferences flow through three standardized layers:
- AdwStyleManager (libadwaita) — the in-process API for controlling and querying an app's color scheme
- XDG Desktop Portal / Settings portal — the IPC bridge that exposes host appearance settings (
org.freedesktop.appearance color-scheme) into the sandbox - Flatpak theme extensions — the packaging model for distributing GTK themes without weakening sandbox permissions
| Layer | Scope | Primary Standard |
|---|---|---|
| AdwStyleManager | Per-app color scheme control | libadwaita API |
| Settings portal | System preference → sandbox | XDG Desktop Portal |
| Theme extensions | GTK theme distribution | Flatpak extension spec |
AdwStyleManager — libadwaita's Color Scheme API#
AdwStyleManager is the canonical API for GNOME apps to manage light/dark appearance. Retrieve the singleton via adw_style_manager_get_default() or per-display via adw_style_manager_get_for_display().
Key methods:
| Method | Purpose |
|---|---|
get_color_scheme() / set_color_scheme() | Get or set the requested AdwColorScheme |
get_dark() | Whether the app is currently rendering dark (computed from scheme + system) |
get_system_supports_color_schemes() | Whether the running system exposes a color-scheme preference |
get_accent_color_rgba() | Current system accent color (libadwaita ≥ 1.6) |
get_system_supports_accent_colors() | Whether accent colors are supported (libadwaita ≥ 1.6) |
AdwColorScheme values include DEFAULT, FORCE_LIGHT, FORCE_DARK, PREFER_LIGHT, and PREFER_DARK — the PREFER_* variants follow the system setting while expressing a fallback preference.
GNOME HIG guidance : most apps should use light by default and follow the system-wide style. When exposing a per-app preference, always offer three options: Light, Dark, and Follow System. Per-app style controls are primarily justified for text editors or apps used for extended periods.
The GNOME dark mode tutorial walks through wiring AdwStyleManager to a GAction + GSettings so the preference persists across sessions.
XDG Desktop Portal: Bridging Host Preferences into the Sandbox#
Because the Flatpak sandbox blocks direct DConf/GSettings access to the host, system appearance settings reach sandboxed apps via the XDG Desktop Portal :
- Wayland: the active theme and
org.freedesktop.appearance color-schemevalue are exposed through the Settings portal. A matching desktop-environment portal backend (e.g.,xdg-desktop-portal-gnome) must be installed. - X11: GTK3 reads theme info from the XSettings daemon (
gsd-xsettings), which itself reads DConf values from the host.
If no portal backend is present or the theme is unavailable inside the sandbox, GTK apps fall back to Adwaita default. libadwaita apps still respond correctly to the color-scheme value provided through the portal, so dark/light switching works automatically without any extra permissions when the portal is in place.
Flatpak Theme Extensions and Flathub Packaging Rules#
GTK themes that need to be applied inside a Flatpak sandbox must be packaged as Flatpak extensions, not through direct filesystem access. Requesting --filesystem=~/.themes in a manifest's finish-args triggers the Flathub linter error finish-args-incorrect-theme-folder-permission and will block submission. The linter guidance points to the Flatpak desktop integration docs as the canonical reference.
Two accepted packaging patterns:
| Pattern | When to use |
|---|---|
| Standard Flatpak extension | Actively maintained themes |
| Unmaintained GTK theme extension | Legacy / low-activity themes |
Extension ID rule: a theme extension's ID must be prefixed with the extension point ID (defined in a runtime or parent app).
For apps built on libadwaita, custom GTK themes are largely unnecessary — AdwStyleManager handles light/dark switching natively using the built-in Adwaita style, and libadwaita CSS variables and style classes automatically adapt to light, dark, and high-contrast appearances .
Reference Links#
| Resource | URL |
|---|---|
| AdwStyleManager API reference | gnome.pages.gitlab.gnome.org/libadwaita/…/class.StyleManager.html |
| GNOME HIG — UI Styling | developer.gnome.org/hig/guidelines/ui-styling.html |
| GNOME Dark Mode Tutorial | developer.gnome.org/…/dark_mode.html |
| Flatpak Desktop Integration | docs.flatpak.org/…/desktop-integration.html |
| Flathub Linter Reference | docs.flathub.org/docs/for-app-authors/linter |
| libadwaita CSS Variables | gnome.pages.gitlab.gnome.org/libadwaita/…/css-variables.html |
| Flatpak Extension Docs | docs.flatpak.org/…/extension.html |
