UI Themes & View Preferences
Relevant source files
The following files were used as context for generating this wiki page:
Linux Archductor provides a highly customizable GTK4/libadwaita interface designed for parallel coding-agent workflows. The system allows users to define visual themes, accent colors, and layout densities at the repository or workspace level. These preferences are persisted in TOML-based configuration files and applied dynamically via CSS injection and GTK StyleManager integrations.
The architecture separates core configuration logic from the GTK presentation layer. View preferences encompass light/dark/system themes, specific color tokens for various UI elements, and UI density settings (compact vs. comfortable). These settings ensure that the application can adapt to different developer environments and preferences while maintaining a consistent "Graphite Developer Cockpit" aesthetic.
Visual Configuration Model
View preferences are primarily defined within the ViewSettings and ViewPreferences structures. These capture the high-level intent of the UI's appearance.
Key Data Structures
The system uses several enums and structs to represent visual states:
ViewTheme: Represents the base color scheme (System,Dark,Light).AccentColor: Defines the primary highlights of the UI (Blue,Green,Amber,Rose).ViewDensity: Controls the padding and spacing of UI components (Compact,Comfortable).ViewPreferences: A runtime structure that aggregates theme, accent, custom colors, and density.
Sources: crates/gtk-app/src/main.rs:61-125, crates/core/src/settings.rs:165-182
Configuration Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
theme | String | "system" | Selects between light, dark, or system schemes. |
accent_color | String | "green" | Sets the UI highlight color (e.g., blue, green). |
density | String | "compact" | Controls UI spacing (e.g., compact, comfortable). |
terminal_font | String | None | Defines the font family and size for terminal views. |
diff_preference | String | "unified" | Sets the default view for git diffs. |
Sources: crates/core/src/settings.rs:165-182, crates/core/src/settings.rs:379-387
Theme Engine & CSS Injection
The application uses a hybrid approach to styling, combining Libadwaita's StyleManager for system-level themes with a custom CSS provider system for granular control over colors and layouts.
CSS Class Generation
The ViewPreferences::css_classes function maps high-level settings to specific CSS class strings (e.g., lc-theme-dark, lc-accent-green, lc-density-compact). These classes are added to the main application window to trigger style updates.
The diagram shows how view defaults flow from the database into the GTK window via CSS classes and color scheme settings.
Sources: crates/gtk-app/src/main.rs:88-111, crates/gtk-app/src/main.rs:411-419
Custom Color Tokens
User-defined colors are handled through a specialized token system. The VIEW_COLOR_TOKENS constant defines 16 semantic keys (e.g., background, surface, accent, success) that can be overridden with hex values in the repository settings.
Sources: crates/gtk-app/src/main.rs:460-478, crates/gtk-app/src/theme.rs:1-20
Graphite Developer Cockpit
The default theme, termed "Graphite Developer Cockpit," utilizes specific font stacks:
- UI Text:
Mona Sans(falls back to system fonts). - Code Surfaces:
Commit Mono(falls back to JetBrains Mono, SF Mono).
Sources: crates/gtk-app/src/theme.rs:22-26, crates/gtk-app/src/theme.rs:1140-1144
Settings Integration
Visual preferences are managed through the application's layered settings system (Shared vs. Local).
UI Settings Layering
- Shared Settings (
settings.toml): Repository-wide defaults for the whole team. - Local Overrides (
settings.local.toml): Per-machine visual preferences or secrets.
The sequence illustrates the loading and merging of visual settings from disk to the UI.
Sources: crates/core/src/settings.rs:200-221, crates/gtk-app/src/settings.rs:72-105
The Settings Inspector
The settings UI uses a "rail" layout to categorize visual and behavioral preferences. Key sections related to view preferences include:
- General: Theme and accent color toggles.
- Terminal: Font and scrollback configuration.
- Advanced: Raw TOML editing for the
[customization.view]section.
Sources: crates/gtk-app/src/settings.rs:115-132, crates/gtk-app/src/settings.rs:857-881
Dynamic Workspace Application
Visual preferences are not just global; they can change based on the active workspace. When a user selects a workspace in the sidebar, the application refreshes the CSS classes on the main window to match that workspace's configured view defaults.
Refresh Logic
The refresh_view_preferences closure is triggered on workspace selection. It:
- Opens the
WorkspaceStore. - Retrieves
WorkspaceViewDefaultsfor the selected name. - Calculates new
ViewPreferences. - Updates the
StyleManagerand re-injects the CSS provider with specific hex overrides.
Sources: crates/gtk-app/src/main.rs:592-613, crates/gtk-app/src/main.rs:620-631
Notification Rules
The view system also integrates with a notification tracker that fires toasts based on repository-defined notification_rules. For example, a toast can be triggered when a session transitions from Running to stopped, provided the on_session_stop rule is active in the view settings.
Sources: crates/gtk-app/src/main.rs:792-835, crates/core/src/settings.rs:179
Conclusion
The UI Themes & View Preferences system provides a flexible, CSS-driven engine that allows developers to tailor the Archductor cockpit to their specific needs. By combining high-level presets (theme, accent, density) with granular color token overrides and repository-specific font selections, the application ensures high visual quality and functional adaptability across diverse Linux desktop environments.