Skip to content

SmrtHub UI Theming Policy (Authoritative)

Note: The canonical source for this document lives at README.Files/System/Policies/SmrtHub-UI-Theming-Policy.README.md. This is an in-site mirror to aid browsing.

SmrtHub UI Theming Policy (Authoritative)

Canonical rules for building and consuming theme resources across SmrtHub WinUI 3 surfaces (HubWindow, dialogs, popups, notifications UIs) so the UI stays consistent, accessible, and maintainable.

1. Goals

  • Enterprise-grade stability: themes must be deterministic and testable (no ad-hoc brushes sprinkled in UI).
  • Accessibility-first: High Contrast is a first-class mode, not an afterthought.
  • Single composition pipeline: all apps compose theme dictionaries the same way.
  • Token-driven UI: controls consume ThemeResource keys; they do not hardcode colors.

2. Canonical Theme Composition

SmrtHub themes are composed in a stable order:

1) Base tokens (shared non-color tokens: spacing, radii, motion, etc.) 2) Palette (Light / Dark / HighContrast) 3) Typography 4) App overrides (optional) loaded last (per-app tweaks, only when truly needed)

In code, this composition is represented by the Smrt.UI ThemeService and ThemeUris registry.

3. Theme Selection Rules

3.1 High Contrast precedence

  • If Windows High Contrast is enabled, SmrtHub must load the HighContrast palette regardless of luminance or user preference.
  • The High Contrast palette should primarily rely on OS High Contrast system colors.

3.2 Light vs Dark selection

  • When High Contrast is not enabled, Light vs Dark may be selected by:
  • a future user preference setting (when implemented), else
  • system background luminance (best-effort).

4. Resource Key Rules (Non-negotiables)

  • UI must consume brushes via ThemeResource (dynamic) rather than StaticResource when the value should update live on theme changes.
  • Brand-specific overrides are allowed only through dedicated keys (do not override random system brushes throughout the app).

4.1 Current canonical keys (semantic surfaces)

SmrtHub uses semantic surface token families under SmrtHub.Surface.*. These keys are the canonical contract used by HubWindow and should be stable across all SmrtHub WinUI apps.

Surface model: - Chrome: the in-app title bar surface. - SubChrome: app controls row and SplitView rail surfaces. - Canvas: the window/page background surface. - Card: elevated card surfaces placed on Canvas.

Each surface family is split by role: - SmrtHub.Surface.<Surface>.Background — the surface background. - SmrtHub.Surface.<Surface>.Content.* — content tints (icons/text). - SmrtHub.Surface.<Surface>.Control.* — control backgrounds (icon-button background tints).

Title bar (Chrome) contract: - SmrtHub.Surface.Chrome.Background - SmrtHub.Surface.Chrome.Content.Default - SmrtHub.Surface.Chrome.Content.Hover - SmrtHub.Surface.Chrome.Content.Pressed - SmrtHub.Surface.Chrome.Content.Disabled - SmrtHub.Surface.Chrome.Control.Background - SmrtHub.Surface.Chrome.Control.HoverBackground - SmrtHub.Surface.Chrome.Control.PressedBackground - SmrtHub.Surface.Chrome.Control.DisabledBackground - Toggle-specific icon tints: SmrtHub.Surface.Chrome.Toggle.* - Avatar hover overlay: SmrtHub.Surface.Chrome.Avatar.HoverOverlay

Native caption control (min/max/close) glyphs: - SmrtHub.Icon.CaptionControls.Default - SmrtHub.Icon.CaptionControls.Hover - SmrtHub.Icon.CaptionControls.Pressed - SmrtHub.Icon.CaptionControls.Disabled

4.2 Canonical state token families (interaction + feedback)

In addition to surfaces, SmrtHub defines a small set of canonical state token families. These are intentionally framework-level and are shared across apps.

Status (semantic meaning): - SmrtHub.Status.Success.{Foreground,Background} - SmrtHub.Status.Caution.{Foreground,Background} - SmrtHub.Status.Critical.{Foreground,Background} - SmrtHub.Status.Attention.{Foreground,Background}

Busy / progress (long-running operations): - SmrtHub.Busy.Indicator.TrackBrush - SmrtHub.Busy.Indicator.TrackOpacity - SmrtHub.Busy.Indicator.ChunkBrush - SmrtHub.Busy.Indicator.ChunkWidth - SmrtHub.Busy.Indicator.Duration

Transient feedback motion (short-lived “did it work?” affordances): - SmrtHub.Motion.TransientFeedback.SuccessHoldDuration - SmrtHub.Motion.TransientFeedback.SuccessTransitionDuration - SmrtHub.Motion.TransientFeedback.SuccessScaleDown - SmrtHub.Motion.TransientFeedback.SuccessScaleUp

Implementation locations (source of truth): - Status brushes: SmrtApps/src/Smrt.UI/Themes/Semantic/Brushes.xaml - Busy indicator tokens: SmrtApps/src/Smrt.UI/Themes/Palettes/Theme.*.xaml - Motion tokens: SmrtApps/src/Smrt.UI/Themes/Tokens/BaseTokens.xaml

Design rules: - Prefer binding to these keys rather than inventing app-local equivalents. - High Contrast must remain system-driven; tokens should either alias system brushes or map to system colors in the HC palette. - Caption controls are a separate contract (SmrtHub.Icon.CaptionControls.*) and must not be folded into the surface/state token families.

5. High Contrast Requirements

High Contrast palettes must: - Use OS-provided system colors where possible (text, window background, disabled text). - Avoid hard-coded #FFFFFF / #000000 assumptions. - Keep icon + text contrast correct even if the user selects a non-default High Contrast scheme.

6. Brand Colors

SmrtHub brand colors may be expressed in palette dictionaries when the design calls for explicit brand surfaces.

Current brand tones: - Off-black: #202020 - Off-white: #F9F9F9

Rule: - Prefer neutral/tintable assets and system brushes for general UI. - Use explicit brand colors only for deliberate brand surfaces (for example SmrtHub.Surface.Chrome.Background) and keep them centralized in palettes.

7. Icons and Theme Interaction (policy-level)

  • UI icons should be tintable and state-aware.
  • The runtime icon contract is Fluent UI System Icons via FluentIcons.WinUI, tinted via theme/state brushes.
  • SVG remains valid for logos/brand marks and other image assets where runtime tinting is not required.
  • If an asset requires pre-colored tone variants (typically logos/brand marks), those variants are governed by the Asset Policy tone suffix rules.
  • Tone suffixes are named for the background they are designed for (e.g., -light means “designed for light backgrounds” and is often a dark-colored logo).
  • High Contrast should prefer -*-contrast variants, and when possible pick -light-contrast vs -dark-contrast based on the actual system background luminance.

8. Change Control

Theme changes are high-impact. Any palette change must be validated by: - Switching Windows Light/Dark while the app runs - Enabling/disabling High Contrast while the app runs - Moving the window across monitors with different DPI scales

The goal is to guarantee the UI stays legible and stable under enterprise environments.