pos-system/docs/adr/001-marketing-dual-theme.md

ADR 001: Marketing Dual-Theme (MarketingDark vs DefaultDark)

Status: Accepted Date: 2026-03-23 Deciders: Frontend Lead, UX/UI Designer Tags: frontend, theming, blazor, mudblazor

---

Context

The GoodGo POS platform (web-client-tpos-net) uses a centralized MudBlazor theme system defined in AppTheme.cs. All layouts — Admin, Auth, POS, Customer — share a single DefaultDark theme with orange primary (#FF5C00), which is the aPOS brand color.

When the Marketing module (CRM, analytics, chatbot, ad campaigns) was added, a design review identified a conflict: orange is the operational/transactional color used throughout the merchant POS workflow. Applying the same color to marketing pages made it impossible for users to distinguish between day-to-day POS tasks and strategic marketing activities.

---

Decision

We introduce a second theme, MarketingDark, used exclusively by MarketingLayout.

Property	DefaultDark	MarketingDark	Reason for change
Primary	#FF5C00 (orange)	#FACC15 (yellow)	Distinct brand identity for marketing context
PrimaryContrastText	#FFFFFF	#18181B (near-black)	Yellow requires dark text for WCAG AA contrast
Background	#0A0A0B	#18181B	Slightly warmer dark to complement yellow
Surface	#1A1A1D	#0F0F10	Inverted surface/background for depth contrast
AppbarBackground	#1A1A1D	#0F0F10	Consistent with surface inversion
TextSecondary	#ADADB0	#71717A	Zinc palette, neutral for yellow-accented UI
LinesDefault	#1F1F23	#27272A	Slightly lighter dividers on darker background

The yellow (#FACC15) was chosen because:

• It is sufficiently distinct from operational orange to signal a context switch.
• It aligns with convention for "analytics/intelligence" dashboards (gold/amber tones).
• It passes WCAG AA contrast when paired with #18181B text (4.62:1 ratio).

---

Consequences

Positive:

• Merchants get a clear visual signal when navigating from POS → Marketing.
• Marketing module can develop its own visual language (charts, KPIs, audience segments) that does not compete with transactional orange highlights in the POS views.
• Single AppTheme.cs file with two named themes is easy to extend if new verticals require additional theme variants.

Negative / Trade-offs:

• Two themes increase the cognitive surface for future frontend contributors. New layouts must explicitly choose AppTheme.DefaultDark or AppTheme.MarketingDark.
• Yellow primary requires careful component-level review — some MudBlazor components (e.g., MudAlert, MudChip) rely on primary color for semantic meaning (action = orange). Marketing-specific components should be audited for color semantics.

Neutral:

• Other layouts (AdminLayout, AuthLayout, PosLayout, CustomerLayout) continue to use AppTheme.DefaultDark unchanged.
• If a third vertical (e.g., a dedicated customer-facing white-label) requires theming, the same pattern applies: add a static property to AppTheme.cs and bind it in the layout.

---

Implementation

Theme applied in MarketingLayout.razor:

<MudThemeProvider IsDarkMode="true" Theme="AppTheme.MarketingDark" />

All other layouts use:

<MudThemeProvider IsDarkMode="true" Theme="AppTheme.DefaultDark" />

Source: apps/web-client-tpos-net/src/WebClientTpos.Client/AppTheme.cs

---

Alternatives Considered

Alternative	Reason rejected
Single theme with CSS overrides per layout	Harder to maintain; bypasses MudBlazor's theming system; likely to cause specificity conflicts
Light theme for Marketing	Dark theme is the platform default; switching to light breaks visual consistency across the app shell (sidebar, topbar)
Same orange (#FF5C00) for Marketing	Usability issue: no visual distinction between operational POS tasks and strategic marketing actions