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
   • 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.

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.