marketplaces/docs/architecture/foundation/adr/ADR-008-theme-engine-and-design-token-runtime.md

ADR-008: Theme Engine and Runtime Design Tokens

Status: Accepted Date: 2026-07-03

Context

Tenant branding must be configuration-driven and must not require tenant-specific code branches.

Decision

Introduce theme engine based on runtime design tokens:

• Branding, color palette, typography, spacing, icons, logos, favicon derive from configuration.
• Theme tokens are applied at runtime through token service and CSS variable mapping.
• Feature code consumes semantic tokens, not tenant constants.

Consequences

Positive:

• Tenant branding changes are configuration-only.
• Removes environment-based visual branching.

Negative:

• Requires token schema governance and fallback policy.

Compliance Requirements

• No tenant-specific style imports in feature components.
• UI styling must resolve through semantic token set.