Theme Endpoint — API Contract

1. Purpose

ALPA Mobile supports per-Site branding ("MEC theming"): color palettes, icon tints, and navigation chrome that differ between pilot groups (e.g. United Airlines vs ALPA base). The theme endpoint is an anonymous REST call that returns the complete token map for a given theme, resolved to its final values. The client fetches the pilot's Site's active theme once at launch, caches it, and uses it to hydrate the component library before the first screen renders.

The page feed (Dynamic Feed — Integration Guide) carries only semantic token names — e.g. "Surface/Brand" — never raw color values. The theme endpoint is what resolves those names to actual hex values for the pilot's Site (or Page override). These two endpoints are orthogonal: the feed changes frequently; the theme changes rarely.

2. Endpoint

The full wire contract — HTTP signature, response codes, and the shipped ThemeDto — is maintained by the backend team and not duplicated here: see Dynamic Feed — Integration Guide ("Get Theme by ID" / "Get All Themes") and Admin Portal — Integration Guide. Condensed 2026-08-29 — this section previously restated that contract in full; it had drifted twice already (see WI 2609) because two documents describing the same shape is exactly what goes stale. The facts below are the ones this app's client code actually depends on and that Vlad Oprica's guides don't spell out from the client's point of view.

3. Response Shape

Field-by-field ThemeDto shape lives in the Integration Guides linked above. The token namespace catalogue below is this app's own reference — Vlad's guides don't enumerate it — and is the part worth keeping current here.

Token set delivered

Summary of the namespaces confirmed so far in every ThemeDto.Tokens response:

4. Example Responses

United Airlines theme — GET /api/mobilecontent/dynamic/theme/{ual-default-theme-guid}

ALPA base theme — GET /api/mobilecontent/dynamic/theme/{alpa-default-theme-guid}

There is no reserved mecId=ALPA route (see §2). This is simply the theme whose key a Site with no MEC-specific branding has assigned as its activeThemeId — fetched and cached the same way as any other theme, no special-cased request needed.

5. Token Name → CSS Var / XAML Resource Key

The token path in the response ("Surface/Brand") must be mapped to a framework-specific identifier before it can be applied. The mapping rule is mechanical: forward-slash and hyphens become separators; each segment is title-cased for XAML keys; lowercased with hyphens for CSS vars.

Mapping rule

6. Client Hydration — Blazor

The Blazor Hybrid path maps tokens to CSS custom properties on :root. A thin JS interop call injects a <style id="mec-theme"> element that overrides the base values; no Razor component re-renders.

ThemeService.cs (sketch)

wwwroot/alpa-theme.js

7. Client Hydration — XAML Deferred — post AB#2087

The XAML/MAUI rendering path uses ResourceDictionary.MergedDictionaries. The base ALPA values live in AlpaTheme.xaml (static resources). On login, a MEC-specific dictionary is merged on top; components that reference MEC-variable tokens must use {DynamicResource}.

Token type dispatch

The ThemeDto.Tokens map carries four distinct value formats. XAML hydration must branch on token namespace to determine the correct resource type — a single Color.TryParse pass silently drops spacing, radius, and font tokens.

MecThemeService.cs (sketch)

Gap 1 — rgba() color values

Nav/Hover is delivered as "rgba(255,255,255,0.12)" — the only token in the set that uses this format. MAUI's Color.TryParse does not handle rgba() syntax; it silently returns false, and the token is dropped. The ParseRgba helper above covers this case. If the backend ever needs to add more semi-transparent tokens, they should follow the same rgba(r,g,b,a) format — the helper handles any value matching that pattern.

Gap 2 — Spacing tokens carry a px suffix

All Spacing/* values arrive as strings like "16px". XAML Thickness takes a double, not a string — the suffix must be stripped before parsing. The service stores the resolved double in the dictionary. Component styles consume it by constructing a Thickness from the resource: Padding="{DynamicResource SpacingXsmall}" works if the style converts the double to a Thickness in a converter or sets it on a typed property that accepts double directly.

Gap 3 — BorderRadius/Full = "50%" is not an absolute value

MAUI CornerRadius takes an absolute pixel value — it has no concept of a percentage. "50%" cannot be parsed directly. The contract resolves this by mapping "50%" to the sentinel value CornerRadius(999): any value large enough relative to the element's shorter dimension produces a fully-rounded pill or circle visually identical to what border-radius: 50% achieves in CSS. Components that use {DynamicResource BorderRadiusFull} will receive 999 as their corner radius, which is correct for avatar frames and FAB buttons at any reasonable size.

Gap 4 — Font tokens must match AddFont() registered aliases

The theme endpoint delivers Font/Heading and Font/Body as font-family name strings (e.g. "LeagueSpartan", "FuturaPT"). In MAUI, fonts are not resolved by family name at runtime — they must be registered in MauiProgram.cs via AddFont() with an explicit alias. The string stored in the resource dictionary must exactly match that alias.

This creates a coordination requirement: the alias registered in AddFont() must be kept in sync with the string value the backend delivers for each MEC. If the backend changes a font name (e.g. because a MEC rebrands), the client must register the new alias in the same release — a server-only change is not sufficient for fonts. Known aliases at time of writing:

AlpaTheme.xaml (base — static)

8. Caching & Versioning

Cache strategy

Re-fetch policy (client-owned)

• On launch: fetch the pilot's Site (GET /dynamic/site/{siteKey}) to get activeThemeId, then GET /dynamic/theme/{activeThemeId}. Cache the resolved ThemeDto keyed by themeId.
• Screen navigation with a Page-level override: if PageDto.activeThemeId is non-null and differs from the Site's theme, fetch and cache that theme too, keyed by its own themeId.
• Re-fetch cadence: since there is no version signal, re-fetch on a client-chosen cadence (e.g. app foreground, or a TTL such as once per session) rather than polling for "has it changed." Applying a fresh fetch is cheap and idempotent — just re-run hydration (§6/§7) with the new token map.
• If endpoint unreachable at launch: use the last cached ThemeDto for the pilot's Site (keyed by the last-known activeThemeId), if any. There is no reserved fallback theme served by the API (see §2) — if nothing is cached, degrade per §9 rather than blocking on a network retry.

9. Error Handling & Fallback

10. Open Items