GNOME Theming and Appearance#
Bluefin delivers a customized GNOME desktop through three layered mechanisms, each scoped to a different level of the bootc architecture:
- GSchema overrides — compiled into the read-only image at build time; set system-wide defaults for all users
- dconf
distro.d/database — rebuilt at every boot bydconf-update.service; handles relocatable schemas that GSchema overrides can't cover - First-boot user hooks — run per-user at graphical session start via
ublue-user-setup.service; apply hardware-targeted dconf settings
The /usr filesystem is read-only in the deployed system, so users cannot install system-wide GTK themes or extension data via package manager. All persistent user customizations live in ~/.config/dconf/ and ~/.local/share/, which survive all image updates.
GSchema Overrides (Build-Time Defaults)#
zz0-bluefin-modifications.gschema.override is the primary system-wide configuration file. The zz0- prefix ensures it loads last, overriding any upstream defaults.
| Setting | Value |
|---|---|
| Enabled extensions | appindicatorsupport, bazaar-integration, blur-my-shell, custom-command-list, dash-to-dock, gradia-integration, gsconnect |
| Accent color | slate |
| Interface fonts | Adwaita Sans 11 / Mono 11 / Bold 12 for titlebar |
| Wallpaper | 06-bluefin.xml (both light and dark) |
| Dash-to-Dock | Fixed dock, dynamic transparency, rgb(40,40,40) at 80% opacity, DOTS running indicator |
| Window buttons | Minimize, maximize, close (right side) |
| Hot corners | Disabled |
Important note on relocatable schemas: Some GNOME extensions don't ship a GSchema XML file and use relocatable schemas, so their settings must go in dconf
distro.d/instead. The gschema override file itself flags this at line 100: settings that can't be overridden via GSchema (app folders, custom keybindings, Ptyxis profile, Search Light) are handled in dconf.
dconf distro.d/ Files#
These files configure relocatable schemas and extension settings. They are read by dconf-update.service on every boot .
| File | Source | Purpose |
|---|---|---|
01-bluefin-folders | App drawer folders: Gaming, Utilities, Containers, Development, Productivity, Wine | |
02-bluefin-keybindings | Ctrl+Alt+T → terminal; Ctrl+Shift+Esc → Mission Center; Ctrl+Alt+Backspace → Alpaca; Super+Period / Ctrl+Alt+Space → emoji picker | |
03-bluefin-ptyxis-palette | Sets Catppuccin Dynamic palette for Ptyxis | |
04-bluefin-custom-command-menu | Logo menu icon (ublue-logo-symbolic default), app shortcuts, hostname display, help commands | |
05-bluefin-searchlight-extension | Search Light visual config: Super+Space shortcut, dark translucent background, rounded border |
The Ptyxis Catppuccin palette file itself is seeded to ~/.local/share/org.gnome.Ptyxis/palettes/catppuccin-dynamic.palette via /etc/skel .
Hardware-Targeted Theming Hook (10-theming.sh)#
10-theming.sh runs once per user via ublue-user-setup.service (version key: theming user 1) and uses DMI data to apply device-specific appearance settings:
| Hardware | Detection | Settings Applied |
|---|---|---|
| Any Framework laptop | chassis_vendor == "Framework" | Logo menu icon → framework-logo-symbolic; natural scroll enabled |
| Framework 13 specifically | product_name starts with "Laptop (" | Text scaling factor → 1.25× |
| Thelio Astra | product_name == "Thelio Astra" | Logo menu icon → ampere-logo-symbolic |
The logo icon assets (framework-logo-symbolic.svg, ampere-logo-symbolic.svg) are shipped in the image at build time. The default logo menu icon is ublue-logo-symbolic .
To force this hook to re-run (e.g., after a home directory reset), delete ~/.local/share/ublue/setup_versioning.json — or bump the version number in the script.
Flatpak Appearance Bridging#
Flatpak-sandboxed apps receive system appearance preferences (light/dark mode, accent color) through the XDG Desktop Portal Settings portal, not via direct dconf access. The xdg-desktop-portal-gnome backend bridges the org.freedesktop.appearance color-scheme value into the sandbox. libadwaita apps respond automatically — no extra Flatpak permissions needed. Direct filesystem access to ~/.themes is explicitly rejected by the Flathub linter .
Bundled Extensions#
Bluefin ships the following extensions pre-enabled in the image :
| Extension | Purpose |
|---|---|
| Dash to Dock | Unity-style fixed dock |
| AppIndicator Support | System tray icons |
| GSConnect | KDE Connect mobile integration |
| Blur my Shell | Shell blur effects, including dock |
| Search Light | Spotlight-style search (Super+Space) |
| custom-command-list | Logo menu with system commands |
| bazaar-integration / gradia-integration | App store / wallpaper integration |
User-installed extensions go in ~/.local/share/gnome-shell/extensions/ and persist across all image updates. Use GNOME Extension Manager (included) for management.
Key Files & References#
| Resource | Link |
|---|---|
| GSchema override | zz0-bluefin-modifications.gschema.override |
| dconf distro.d/ directory | projectbluefin/common |
| Hardware theming hook | 10-theming.sh |
| dconf update service | dconf-update.service |
| Bluefin documentation | docs.projectbluefin.io |
| XDG Desktop Portal (Flatpak theming) | docs.flatpak.org |
