ZOA UI Theming

IHudTheme

interface

Six colours and an id. The single cross-package contract a HUD component consumes so it never imports the package that authored the theme.

• string ThemeId { get; }
• Color WindowBackgroundColor { get; }
• Color PanelBackgroundColor { get; }
• Color SlotBackgroundColor { get; }
• Color BorderColor { get; }
• Color TextColor { get; }
• Color AccentColor { get; }

IHudThemeProvider

interface

Publishes the active IHudTheme and raises an event when it changes. Resolved from the service registry by consumers; ActiveTheme may be null before a theme loads.

• IHudTheme ActiveTheme { get; }
• event Action<IHudTheme> ThemeChanged

IZOAThemeService

interface

The UI Toolkit side of theming. Attach the generated variables sheet to a panel root, read the fallback-resolved theme view, and react to theme changes.

• ZOAUiTheme ActiveTheme { get; }
• ZOAUiThemeResolvedView ResolvedTheme { get; }
• event Action<ZOAUiTheme> ThemeChanged
• void Attach(VisualElement root)
• void Detach(VisualElement root)
• void RefreshAttachedRoots()
• void ReloadFromSettings()

ZOAThemeService

service

The default implementation of both interfaces. Resolves the active theme from settings, loads the generated stylesheet from Resources, and re-attaches every tracked root on change. It never self-registers.

• ZOAThemeService()
• ZOAThemeService(ZOAUiTheme fallbackTheme)
• void SetActiveTheme(ZOAUiTheme theme)
• void ReloadFromSettings()

VisualElementExtensions

class

The extension methods most call sites use. ApplyZOATheme resolves the service through an installed resolver, falling back to an in-process instance so an unbootstrapped editor panel still renders themed.

• static void ApplyZOATheme(this VisualElement root)
• static void RemoveZOATheme(this VisualElement root)
• static void SetThemeServiceResolver(Func<IZOAThemeService> resolver)

ZOAUiPanelSettings

class

Makes a runtime UIDocument render-ready: canonical PanelSettings plus the base ThemeStyleSheet that UI Toolkit needs before a Label draws any glyphs.

• const string PanelSettingsResourcePath = "UI/ZOA UI Panel Settings"
• const string RuntimeThemeResourcePath = "UI/ZOADefaultRuntimeTheme"
• static PanelSettings LoadCanonical()
• static PanelSettings Ensure(UIDocument document)
• static void EnsureRuntimeTheme(PanelSettings settings)
• static PanelSettings EnsureZOAPanelSettings(this UIDocument document)

ZOAUiThemeResolvedView

class

Active theme projected over a fallback theme. Reach for this instead of reading ActiveTheme directly when you need sprites, textures, cursors, HUD metrics, or scalars, so every UI stack shares one set of fallback rules.

• ZOAUiTheme ActiveTheme / FallbackTheme / EffectiveTheme { get; }
• static ZOAUiThemeResolvedView FromActiveTheme(ZOAUiTheme activeTheme)
• static ZOAUiTheme LoadDefaultTheme()
• Sprite CrosshairSprite { get; } float CrosshairSize { get; }
• float HudBarHeight { get; } float HudBarSpacing { get; }
• Sprite ResolveArchetypeIcon(string archetypeId)
• bool TryResolveSlotLayout(string slotId, out Rect position)

ZOAUiThemeRuntimeSelection

class

Player-facing theme selection. Enumerates the theme catalog out of Resources and persists the chosen theme id in PlayerPrefs, separate from the project default in the settings asset.

• const string PlayerPrefsThemeIdKey = "ZOA.UI.Theme.ActiveThemeId"
• static List<ZOAUiTheme> LoadAvailableThemes()
• static ZOAUiTheme ResolveThemeForService(ZOAUiTheme projectDefault)
• static void PersistThemeSelection(ZOAUiTheme theme)
• static bool TryFindThemeById(string themeId, out ZOAUiTheme theme)
• static void ClearPersistedThemeSelection()

ZOAUiThemeSelectorWidget

class

Builds a runtime-safe theme picker as a VisualElement. Options control whether a pick is persisted, written back to the settings asset, and applied immediately.

• static VisualElement Build(Options options = null)
• class Options { Themes, ActiveTheme, ThemeService, PersistSelection, WriteThemeSettings, ApplyOnSelection, ThemeSelected }

ZOAUiTheme

asset

The theme asset. One ScriptableObject carrying every --zoa-* token the project renders through: palette and tints, typography, spacing, radii, borders, surfaces, text roles, controls, transitions, shadows, focus, sprites, cursors, accessibility values, and HUD bar and notification values. It implements IHudTheme directly. Created via ZOA > UI > UI Theme.

• string ThemeId / DisplayName / Description, int Version, string CacheKey
• Color Yellow, Black, Dark, Slate, Red, Cyan, White, Dim (the nine canonical palette tokens)
• Color SurfaceBase / SurfacePanel / SurfaceEmbedded / SurfaceElevated / SurfaceHover
• Color TextPrimary / TextSecondary / TextAccent, BorderSubtle / BorderDefault / BorderStrong
• float UiScale, bool UseColorBlindMode, Color ColorBlindAccent
• Sprite CrosshairSprite, float CrosshairSize, Texture2D CursorDefault / CursorInteract
• Sprite GetArchetypeIcon(string archetypeId)
• bool TryGetSlotLayout(string slotId, out Rect position)

ZOAUiThemeSettings

asset

Project-level active-theme selector, resolved through a static Instance that loads from Resources/ZOA/ThemeSettings. In the editor it falls back to a project-wide asset search and then to the editor bootstrap, so a fresh clone is never themeless. Created via ZOA > UI > Theme Settings.

• static ZOAUiThemeSettings Instance { get; }
• ZOAUiTheme ActiveTheme { get; set; }
• bool RequireThemeInResources { get; }
• float WorkbenchThemeBackgroundOpacity / ChromeOpacity / ContentOpacity
• ZOAUiThemePaths.DefaultSettingsAssetPath = "Assets/Resources/ZOA/ThemeSettings.asset"