Appearance

Settings → Appearance edits how Pearl looks: the wallpaper, the color theme, fonts, the colors of other applications, Night Light and Qt integration. Choose Apply & save to save appearance preferences, or Discard to undo unsaved changes. Palette creation, import and Save palette write files separately; saving an active palette updates it live. See Settings for draft and recovery details.

Find the right appearance control

What you want to change	Where to go
Wallpaper, built-in colors, fonts or a wallpaper-derived palette	Settings → Appearance on this page
Exact colors, imported JSON or widget styling	Appearance → Installed themes & customization…, then Theme creation
Ghostty or another application’s colors	Application themes
Qt 5/6 widgets and fonts	Qt applications
Tray, clocks, running applications, bar or dock visibility	Desktop → The bar and Dock and bar islands
Window borders, blur or corner radius	Aqueous visual effects
Pearl Cat or another add-on	Plugins

Bar opacity changes only the bar. Dock visibility is set separately. Community themes and showcase customizations can look different from the defaults.

Wallpaper

In Wallpaper, click Choose image…, select a PNG or JPEG, then Apply & save. Selecting an image sets Wallpaper fit to Cover; you can switch to Contain afterwards. To restore an earlier image, choose it and apply again. The wallpaper also offers gradient and solid background modes with a color choice; gradient is the default for fresh configurations.

The wallpaper is global: one image is shared across every display and fitted independently to each output’s geometry. Per-output settings control bars and docks, not different images. Separate images per monitor remain tracked in Pearl #19.

Double-click the desktop background, or a thumbnail in the bar’s Wallpaper pane, to open the crop editor. Its frame is locked to the output’s aspect ratio, drag places the frame and the scroll wheel zooms it. Crops are stored as fractions of the source image, so a placement survives the file being resized, and every surface reuses the same placement across rotations and restarts. Wallpaper-derived palettes keep reading the whole image, so cropping does not shift dynamic colors. Reset restores the full frame.

The active image file is watched: in-place edits, atomic replacements and deletion followed by recreation refresh the wallpaper automatically.

Slideshow

Slideshow is a section of the same Wallpaper card. Choose folder… picks a directory; only PNG and JPEG files in it are eligible. The folder is rescanned on each rotation, so adding or removing images takes effect without reloading preferences, and an empty or unreadable folder keeps the current wallpaper and retries at the next interval.

• Change every: 10 seconds to 24 hours, 15 minutes by default.
• Order: sequential or random.
• Transition: none, fade, slide, rotate, cover or random, with an adjustable animation length. The reduced motion preference suppresses transitions.

Enabling the slideshow requires an image fit (Cover or Contain) and a folder. Each rotation goes through the normal apply path, so wallpaper-derived colors follow the new image when your theme uses it.

Theme modes

Choose a mode under Theme & colors. Community opens installed palettes and widget styles through Installed themes & customization…. The other modes are:

• Static Material: Pearl’s built-in dark or light Material Design palette. No generator is required.
• Dynamic Material: derives a dark or light palette from a hex seed color or from the selected wallpaper. This mode requires matugen 4.x; a generator failure keeps the current appearance and reports the error. Generated palettes are cached on disk under $XDG_CACHE_HOME/pearl/themes, so repeating a seed or wallpaper is cheap.
• GTK theme: styles Pearl with an installed GTK theme instead of Material colors. Leave GTK theme name empty to follow the normal GTK settings of the session, including GTK_THEME and your own gtk.css. Enter an installed theme name to use it for Pearl alone; the color variant selects its dark or default stylesheet. This never changes another application’s settings.

Note

GTK mode needs GTK4-compatible themes, found through GTK’s normal XDG theme search paths and ~/.themes. GTK3-only themes cannot style GTK4, and a theme’s name alone does not determine its compatibility. Your own GTK CSS keeps its normal highest priority, and because a GTK theme determines its surface opacity, an opaque theme hides the compositor’s blur behind it.

Follow the wallpaper or keep fixed colors

• Wallpaper colors: choose Dynamic, set Dynamic colors from to Wallpaper, choose a Color variant, then Apply & save.
• Fixed colors: choose Material and a variant, or select a local palette, then apply.

Applications follow their own color source, so check that setting if only the shell changes.

Development builds after v0.3.0 add Matugen scheme: Content, Expressive, Fidelity, Fruit salad, Monochrome, Neutral, Rainbow, Tonal spot (default), Vibrant and Smart. v0.3.0 has neither this selector nor the theme.scheme preference; adding that field makes it reject the file. See package channels.

Window borders follow Pearl theme synchronizes Aqueous border colors after saving the theme: focused borders use the palette’s primary color, normal borders the outline color and urgent borders the error color. It defaults off, and GTK mode pauses synchronization so you can edit border colors yourself under Aqueous → Appearance.

Font and motion settings live on the same page: a font family (empty uses the Material fallback in Material modes and native GTK typography in GTK mode), a font size from 10 to 24 pixels, normal or compact density, and reduced motion. Density and reduced motion apply live.

Application themes

Beyond the shell itself, Pearl can generate matching color themes for other applications using Matugen. Management is opt-in and lives under Appearance → Application themes.

Turn on Enable application themes, then choose per application: Follow Pearl theme, Choose profile, or Off. Use Material defaults fills in built-in assignments while preserving explicit profile choices and Off. Application colors can follow Pearl, use an independent seed, or use the current wallpaper; wallpaper-derived colors update automatically when the committed image changes.

On the first Pearl session for a new user configuration, GTK 3 and GTK 4 automatically use the managed Material profile and follow Pearl’s colors. Pearl saves this selection once; existing preferences and later Off choices are preserved. Every other target stays opt-in.

The built-in catalog covers toolkits (GTK, qt5ct, qt6ct, KDE color schemes), terminals, editors, browsers, chat clients and a few others. The current list and per-application notes live in the Pearl repository.

Generating files is separate from activating them. Each row in Settings shows the effective profile, status, output location and setup instructions:

• GTK receives a scoped import in your gtk-3.0/gtk.css and gtk-4.0/gtk.css that retains prior contents. Applications that cache CSS may need a restart.
• Terminals get Pearl-named theme or include files; follow the row’s configuration instructions once.
• Editors and chat clients, such as Zed, need the theme selected inside the application. The VS Code family installs a generated pearl-material.vsix through Install from VSIX, reinstalled after palette updates.
• Browsers receive CSS for an explicitly chosen browser profile; Pearl never guesses which profile to edit.

Generated previews live under $XDG_CONFIG_HOME/pearl/matugen/outputs/, and files installed into application directories are tracked by ownership journals.

Recovery

Application files edited outside Pearl are protected: conflicts are reported per application and never undo a successful shell update. Turning an application Off restores only Pearl-owned files that are unchanged; your own edits are retained and reported as a conflict to resolve first. Do not delete ownership journals to bypass a conflict.

Missing or invalid images and generator failures retain existing outputs, and a later valid image event retries automatically. pearlctl preferences reload rechecks the image and reattaches an unavailable directory watch. Retry committed application themes retries the saved snapshot.

To adopt updated profile assets, choose Refresh application profiles, then Use current profile versions on Apply and Apply & save. Existing saved profiles can keep their earlier assets after a package update.

Set up Ghostty and recover readable colors

1. In Application themes · Matugen profiles, enable application themes. Search for ghostty, choose Choose profile → Material · ghostty, set Application colors to Follow Pearl, then Apply & save.
2. Check the row’s status and output path. The generated theme is normally ~/.config/ghostty/themes/pearl-material, under XDG_CONFIG_HOME when set.
3. Add theme = pearl-material to your Ghostty configuration, normally ~/.config/ghostty/config, then reload it or restart Ghostty.

If wallpaper colors are unreadable, try a fixed Material shell palette with application colors on Follow Pearl, or choose Independent seed for application colors. Check text, cursor, selection and ANSI colors; shell contrast checks do not cover every terminal color pair.

To stop using the theme, remove the line you added, restore your previous Ghostty theme and reload. Set the ghostty row to Off and apply to restore only unchanged Pearl-owned files. Resolve any reported file conflict first.

For contrast reports, include Pearl/Ghostty versions, wallpaper or seed, variant, profile ID/version and the affected colors. Development color changes after v0.3.0 may not be in your saved profile. For flickering or rendering artifacts, see Hardware and status.

Night Light

Appearance → Night Light warms the screen on a schedule. It is disabled by default and saves through the shared draft like everything else on the page.

• Temperature: 2500 to 6500 K, 4500 K by default.
• Manual: follows the enabled switch all day.
• Custom schedule: local-time start and end, with the start inclusive and the end exclusive. Overnight intervals work; equal start and end are invalid. Daylight-saving transitions are accounted for at the boundaries.

Night Light uses Aqueous output warming. When no output can apply it, Pearl reports warming as unavailable rather than pretending to write to the display, and rejected requests change nothing.

pearlctl night-light status
pearlctl night-light off
pearlctl night-light resume

off creates a temporary override without writing preferences: with a custom schedule it expires at the next local-time boundary, otherwise it lasts until Pearl restarts. resume clears the override. status separates the requested policy from actual availability and per-output state. The session lock preserves the requested state and rejects interactive changes.

Qt applications

Appearance → Qt applications · QtEngine + Darkly optionally manages the appearance of Qt 5 and Qt 6 applications through the QtEngine platform plugin and the Darkly application style. Management defaults off, joins the shared draft, and previews never write external settings.

Install qtengine and pearl-darkly-style, then enable management and Apply & save. Click Retry saved Qt settings and sign out and back in if the environment status requests it. Launch a fresh Qt application and check the separate Qt 5 and Qt 6 status.

On Devario, use its configured repositories. On another supported Arch-based system, follow Pearl installation. If a provider is missing, check your repository configuration and refresh its package metadata; do not add another distribution’s repository. The package catalogue lists available builds; Settings checks whether the installed Qt providers load.

Caution

These changes affect the shared, account-wide Qt configuration, including applications launched outside Pearl. Before downgrading Pearl or removing the Qt packages, disable management, resolve any restoration conflicts and sign out. Older Pearl versions reject the qt preference field, so remove it only after restoring through the current version. Package removal does not erase recovery data or the backups of replaced files.

What management covers:

• Follow Pearl uses the committed Material colors and follows seed and wallpaper changes; in GTK shell mode it uses a labelled static dark or light fallback. Static dark/light fixes Qt to Pearl’s selected static palette.
• Synchronize font maps Pearl’s logical pixel size to Qt’s integer point size at 96 DPI (14 pixels maps to 11 points). An empty Pearl font family leaves Qt’s existing family alone.
• Icon theme, Darkly corner radius, compact density, selected animation keys and four optional KDE focus, hover, negative and background colors follow Pearl. Radius 0 releases ownership of that field.

QtEngine uses one shared configuration for both Qt versions. The Check Qt 5 and Check Qt 6 switches select which installed runtimes Pearl verifies with its probes; they cannot give the two versions different configurations. Running applications receive live palette updates through QtEngine’s file watcher, although base style, font and per-application overrides may need an app restart, which Settings reports conservatively.

Material palette exports for qt5ct, qt6ct and KDE under Application themes are separate selectable files and never change the managed Qt platform configuration.

If Qt configuration changes outside Pearl, Review external Qt changes shows current, previous Pearl and original values, and replacement requires that exact review to remain current. Ordinary retries never overwrite a conflicting external edit, and disabling restores original values only where the current value still matches Pearl’s last write.

Diagnose a missing Qt provider or environment conflict

Check the Qt 5, Qt 6, QtEngine, Darkly and environment status. Source builds need the optional probes (-Dqt-themes=true); provider libraries must match the Qt runtime that loads them.

Check the affected session’s environment and Pearl’s session marker:

printenv QT_QPA_PLATFORMTHEME QT_STYLE_OVERRIDE QTENGINE_CONFIG
cat "${XDG_CONFIG_HOME:-$HOME/.config}/pearl/qt/session.conf"

After setup, the marker and a fresh session should use QT_QPA_PLATFORMTHEME=qtengine. Unset variables print nothing; a missing marker can mean setup has not completed. Already-running apps keep their old environment. Check Settings for conflicts from a competing platform plugin, QT_STYLE_OVERRIDE or QTENGINE_CONFIG before editing their source configuration.

The packaged login wrapper and UWSM hook read this marker at startup. Custom launchers need the Qt startup integration, not a global /etc/environment edit. Pearl installs no global Flatpak override.

If it still fails, report your distribution/channel, Pearl and provider versions, Qt 5/6 and environment status, and an affected application/version.

Advanced

Preferences are stored in $XDG_CONFIG_HOME/pearl/preferences.json, falling back to ~/.config/pearl/preferences.json, with a validated recovery snapshot at pearl/last-good.json beside it. The appearance-relevant fields:

{
  "theme": {
    "mode": "dynamic",
    "variant": "dark",
    "seed": "#6750a4",
    "source": "wallpaper",
    "gtk_name": "",
    "sync_borders": false
  },
  "wallpaper": {
    "mode": "cover",
    "path": "/home/user/Pictures/wall.png",
    "color": "#141218",
    "crops": [],
    "slideshow": {
      "enabled": true,
      "folder": "/home/user/Pictures/walls",
      "interval_seconds": 900,
      "order": "sequential",
      "transition": "fade",
      "transition_ms": 420
    }
  },
  "font": "",
  "font_size": 14,
  "density": "normal",
  "reduced_motion": false,
  "night_light": {
    "enabled": false,
    "temperature_kelvin": 4500,
    "schedule": "manual",
    "start_minute": 1200,
    "end_minute": 420
  }
}

theme.mode is static, dynamic or gtk; variant is dark or light; source is seed or wallpaper; colors are #RRGGBB. Wallpaper modes are gradient, solid, cover and contain. Schedule minutes run 0 to 1439 in local time. Application theming lives in a top-level matugen object and Qt management in a top-level qt object; both are documented in the Pearl repository.

Color exports

Exports generate palette-colored files from templates, for example:

{
  "exports": [
    {
      "name": "terminal.conf",
      "template": "background={{surface}}\nforeground={{text}}\n"
    }
  ]
}

Files are written only under $XDG_CONFIG_HOME/pearl/exports, and you point the consumer application at them; Pearl never rewrites GTK, Qt, terminal or Aqueous configuration implicitly, and no shell hooks or commands are accepted. Supported tokens include surface, text, primary, outline and error_color, enclosed in {{...}}. A sidecar file records what Pearl last wrote, so a file you edited yourself is protected and the first replacement keeps a .bak. GTK theme mode has no Material palette to export and reports that condition.

Command line

pearlctl settings show --page appearance
pearlctl preferences status
pearlctl preferences reload

pearlctl preferences apply submits a full configuration rather than a patch and is covered with its cautions on the Settings page.

Caution

Pearl parses preferences strictly. Before downgrading to an older Pearl version, remove preference fields that version does not know, such as night_light, matugen, qt or slideshow and crop entries, or it will reject the file.