Module system 

Native OS theme discovery: system colors, fonts, and DPI. Discovers system-native styling for colors, fonts, and other metrics.

This module provides a best-effort attempt to query the host operating system for its UI theme information. This is gated behind the io feature flag.

End-user customization (AZ_RICING): By default (if the io feature is enabled), Azul looks for an application-specific stylesheet at ~/.config/azul/styles/<app_name>.css (or %APPDATA%\azul\styles\<app_name>.css on Windows) and applies it as the last layer of the cascade, letting end-users “rice” any Azul app.

The AZ_RICING env var has three modes (case-insensitive):

• unset (default): load the user CSS if present; on Linux, the detection chain is KDE > GNOME > riced > defaults.
• AZ_RICING=off (aliases: disabled, none, 0): skip the user CSS file and the riced-desktop sources (Hyprland config, pywal cache). Use for kiosk builds or CI runs that mustn’t pick up local customization.
• AZ_RICING=force (aliases: prefer, aggressive, 1): on Linux, reorder the detection chain so riced-desktop sources win over GNOME/KDE — useful for tiling-WM users whose XDG_CURRENT_DESKTOP still says gnome. The user CSS file still loads.

Modules

apple_fonts

Apple system font family names for font fallback chains.

defaults

A collection of hard-coded system style defaults that mimic the appearance of various operating systems and desktop environments. These are used as a fallback when the “io” feature is disabled, ensuring deterministic styles for testing and environments where system calls are not desired.

linux_fonts

Linux/GTK common font family names.

windows_fonts

Windows system font family names.

Structs

AccessibilitySettings

Accessibility settings detected from the operating system.

AnimationMetrics

Animation-related preferences from the OS.

AudioMetrics

Audio-feedback preferences from the OS.

FocusVisuals

Focus ring / indicator visual style.

IconStyleOptions

Icon-specific styling options for accessibility and theming.

InputMetrics

Input interaction timing and distance thresholds from the OS.

LinuxCustomization

Linux-specific customisation settings.

SafeAreaInsets

Safe area insets for devices with notches, rounded corners, or sensor housings.

ScrollbarPreferences

OS-level scrollbar behaviour preferences.

SystemColors

Common system colors used for UI elements.

SystemFonts

Common system font settings.

SystemMetrics

Common system metrics for UI element sizing and spacing.

SystemStyle

A unified collection of discovered system style properties.

TextRenderingHints

Text rendering configuration from the OS.

TitlebarButtons

Which window control buttons are available in the titlebar.

TitlebarMetrics

Metrics for titlebar layout and window chrome.

VisualHints

Visual hints from the OS about how icons and decorations should be shown.

Enums

DesktopEnvironment

Represents the detected Linux Desktop Environment.

FocusBehavior

Focus indicator behaviour (always visible vs keyboard-only).

Platform

Represents the detected platform.

RicingMode

User-customization mode controlled by the AZ_RICING env var.

ScrollbarTrackClick

What happens when clicking the scrollbar track area.

ScrollbarVisibility

When scrollbars should be shown (OS-level preference).

SubpixelType

Subpixel rendering layout for font smoothing.

SystemFontType

System font types that can be resolved at runtime based on OS settings.

Theme

The overall theme type.

TitlebarButtonSide

Which side of the titlebar the window control buttons are on.

ToolbarStyle

Toolbar display style (icons, text, or both).

Functions

detect_linux_desktop_env

Detect the Linux desktop environment from environment variables.

detect_system_language

Detect the system language as a BCP 47 tag.

ricing_enabled

True when the user CSS file at ~/.config/azul/styles/<app>.css should be read. False only when AZ_RICING=off is set.

ricing_mode

Read the AZ_RICING env var and classify it. Case-insensitive. Anything we don’t recognise falls through to Default so a typo degrades gracefully instead of disabling the feature silently.