Core.Presentation

Core.Presentation is the shared presentation runtime for loading, resolving, and emitting design tokens across Web and MAUI, and for generating projection artifacts consumed by platform UI packages.

Portal-Safe Boundary

Core.Presentation owns cross-platform tokens, themes, icons, and small reusable UI primitives. It does not own product workflows, portal sign-in, API clients, persistence, database connectors, workers, or product-specific navigation. Authenticated portals may use its compiled web theme and components alongside product-owned routes and workflows.

Canonical token source

• Source of truth: Core/Presentation/Tokens/*
• Product overlays: Core/Presentation/themes/products/*.theme.json
• Product-owned brand ramps: <Area>/Design/Tokens/color.<area>-<brand>.json
• Legacy archives:
  • Core/Presentation/Tokens.LegacyArchive/*
  • Core/Presentation/Theme.LegacyArchive/*
  • Core/Presentation/Web.LegacyArchive/*

Runtime pipeline

1. ThemeEmitter reads canonical tokens and emits:
   • Core/Presentation/wwwroot/theme/compiled/tokens.json
   • Core/Presentation/wwwroot/Web/compiled-theme.css with both :root light variables and an html[data-theme="dark"] dark variable set
   • Core/Presentation/themes/base.telerik-map.json
   • Avalonia projections:
     • Core/Avalonia/Styles/Generated/*.axaml
   • MAUI projections:
     • Core/Maui/Resources/Themes/Generated/*.xaml
     • Core/Presentation/Maui/Generated/*.xaml
2. ThemeLoader loads compiled tokens + Telerik map and applies optional product overlays. Product overlays may reference brand ramps in the owning product repo and can also emit product-specific CSS through ThemeLoader.WriteCompiledCss(...).
3. ServiceCollectionExtensions.AddCoreUI(...) wires the theme bundle and Telerik overrides into DI.

The compiled CSS carries Core aliases, compatibility aliases, and the Kendo/Telerik bridge for both theme modes. Product hosts should switch modes by setting html[data-theme="dark"]; page CSS should consume emitted variables rather than hardcoding dark-mode colors.

Compiled artifacts are tracked because consuming packages load them at runtime. The emitter must be deterministic: validation, tests, and runtime startup must not introduce wall-clock timestamps or rewrite identical generated content.

Overlay rules

• Product overlays can modify only:
  • semantic.*
  • brand.*
  • component.*
• Primitive/base keys are immutable in overlays.
• Product-specific brand color values belong in the product repo's Design/Tokens/ payload, not in Core or another product's design workspace. Core overlays may reference those product-owned token files while the product-specific CSS/XAML/Avalonia artifacts are generated by the consuming product or build step.

Standards promotion

When app, portal, API host, or cross-platform experience runbooks prove reusable token, chrome, or presentation behavior, promote the durable rule into Workspace Design/, Docs/Standards, ADRs when architectural, and this package documentation before the runbook is archived. Product-specific themes remain overlays; reusable primitives belong in Core only after they are proven product-agnostic.

Migration tracking

See Core/Presentation/Tokens/MIGRATION.md for remaining compatibility work and final cleanup sequencing.