ADR 001 Pluggable Themes

ADR-001: Pluggable Themes for Material Dashboard

QQQ 4.0 release. Final 4.0.0 is available. See QQQ 4.0 for release scope and migration guidance.

Design record: This page describes the theming proposal, not a verified 4.0 installation contract. The first release train retains dashboard 0.41.0; confirm implementation and matching frontend support in the linked issue before applying the proposed API.

Status: Accepted Date: 2024-12-28 Deciders: QQQ Team Tags: frontend, theming, css-variables, metadata

Context

The qqq-frontend-material-dashboard currently has hardcoded colors, fonts, and styling throughout the codebase (~73 files with hex color values). Users want to customize the dashboard appearance (colors, logos, fonts, sizing) without modifying source code or rebuilding the frontend.

Existing infrastructure includes:

• QBrandingMetaData: Provides logo, icon, appName, accentColor (partially utilized)
• material-dashboard-overlay: Static asset serving for logos/icons
• MUI Theme: Static theme created at build time

Key gaps:

• accentColor in QContext never reaches MUI theme palette
• No mechanism for runtime theme configuration
• Hardcoded colors scattered across components and CSS

Decision

Implement pluggable themes using CSS Custom Properties (CSS Variables) injected at runtime from backend-defined QThemeMetaData.

Architecture:

1. Backend provides QThemeMetaData as supplemental instance metadata
2. Frontend injects theme values as CSS variables on :root
3. MUI theme factory reads from CSS variables
4. Components reference CSS variables or MUI theme tokens

Rationale

Why CSS Variables over alternatives:

Approach	Pros	Cons
CSS Variables	Runtime switching, no rebuild, browser-native	Requires migration effort
Rebuild with config	Simple implementation	Requires CI/CD per theme
JavaScript theme object	Type-safe	Requires prop drilling, no CSS support
CSS-in-JS only	MUI native	Doesn't cover raw CSS files

CSS Variables chosen because:

• Works with both MUI sx props and raw CSS files
• Enables future runtime theme switching (dark mode)
• Browser-native, performant
• Backward compatible (defaults preserve current appearance)

Why supplemental metadata pattern:

• Follows established QQQ patterns (like QJavalinMetaData)
• Optional - existing deployments unaffected
• Extensible for future theming features

Consequences

Positive

• Users can customize dashboard appearance via backend configuration
• No frontend rebuild required for theme changes
• Foundation for future dark mode / theme switching
• Cleaner separation of design tokens from component logic

Negative

• Migration effort for 73 files with hardcoded colors
• Slight runtime overhead for CSS variable resolution
• Two systems (CSS variables + MUI theme) to maintain in sync

Neutral

• Existing QBrandingMetaData continues to work
• Default theme values match current appearance exactly

Implementation

See GitHub Epic #290 and sub-issues #291-#303.

Key files:

• QThemeMetaData.java - Backend metadata class
• QThemeMetaData.ts - TypeScript interface
• themeUtils.ts - CSS variable injection
• Theme.ts - Dynamic MUI theme factory

See Also

• Feature: Pluggable Themes - Full specification
• Decision Logs - ADR process