[Adding Themes to QFMD] - Where We Are Now

[KofTwentyTwo]

Where We Are Now

The theme system works. 60+ properties flow from Java metadata to CSS variables to rendered components. Tests pass. Other teams are testing in their apps. The feature is real.

But after living with the code for a few days, I'm not happy with how we got here.

What's Working

The architecture holds up. Define theme in Java, ship it with metadata, inject as CSS variables, components pick it up. No rebuild required. No separate config files. Each tenant can have different colors without touching the frontend codebase.

qInstance.setTheme(new QThemeMetaData()
   .withPrimaryColor("#1976D2")
   .withSidebarBackgroundColor("#1E1E2D"));

That's it. Two lines and the app looks different.

The sidebar theming is solid. Background, text, icons, hover, selected states - all wired up. Same with the branded header. Same with data tables. The component "islands" each have their own color namespace and it works.

What's Ugly

The CSS override file. 1200+ lines of specificity battles with MUI.

.MuiButton-containedPrimary {
   background-color: var(--qqq-primary-color) !important;
}

!important everywhere. 82 of them. That's not engineering, that's brute force.

The :not() chains are getting ridiculous:

.MuiTypography-body2:not(.MuiDrawer-root *):not(.MuiDrawer-paper *):not(.qqq-branded-header-bar *) {
   color: var(--qqq-text-secondary) !important;
}

Every new MUI component needs its own override. Every MUI version bump might break something. Every new island component means adding more :not() exclusions everywhere.

The disconnect hit me when I traced the data flow:

QThemeMetaData (backend)
    -> injectThemeVariables() -> CSS variables on :root
    -> colors.ts reads CSS vars -> Theme.ts builds MUI theme
    -> ThemeProvider wraps app
    -> PLUS: 1200 lines of CSS overrides fighting MUI anyway

We're already using MUI's ThemeProvider. We're already building a dynamic theme. But then we're overriding everything with CSS because we didn't trust MUI to do its job.

Two theming systems fighting each other. That's the problem.

The Decision

We're going to refactor.

The CSS variable approach taught us a lot. We understand the 60+ theme properties. We know which components need which colors. We have 26 Playwright tests that verify the rendered output. That's not wasted work - that's reconnaissance.

But the implementation needs to change. Instead of CSS variables overriding MUI from the outside, we're going to:

1. Build the MUI theme directly from QThemeMetaData
2. Let MUI style its own components correctly from the start
3. Keep CSS variables only for "islands" (sidebar, branded header) and non-MUI components
4. Delete most of the 1200-line override file

// Before: CSS variables -> colors.ts reads them -> Theme.ts -> overrides anyway
// After: QThemeMetaData -> createDynamicTheme() -> MUI handles it

function createDynamicTheme(themeData: QThemeMetaData): Theme {
   return createTheme({
      palette: {
         primary: { main: themeData.primaryColor },
         secondary: { main: themeData.secondaryColor },
         background: { default: themeData.backgroundColor },
         text: { primary: themeData.textPrimary },
      },
      components: {
         MuiButton: {
            styleOverrides: {
               containedPrimary: {
                  backgroundColor: themeData.primaryColor,
               },
            },
         },
      },
   });
}

Direct data flow. No round-trip through CSS variables. MUI components styled correctly without !important. The browser's CSS engine isn't fighting itself.

What We Gain

• Smaller override file. 1200 lines -> maybe 200-300 for islands and DataGrid.
• Fewer !important. 82 -> maybe 10-15.
• Easier debugging. Theme is an inspectable object, not scattered CSS vars.
• MUI version safety. We're using MUI's API, not fighting its internals.
• Future features. Dark mode, hot reload, theme switching - all become possible.

What's Next

The 26 Playwright tests stay. They verify rendered colors, not implementation details. When the refactor is done, they should all pass with no changes.

The CSS variable work moves to a feature branch. It's not getting deleted - it's useful as reference and for the blog posts. But develop goes back to pre-theme state.

New feature branch for the MUI refactor. Clean implementation, right architecture.

Sometimes the fastest way forward is to step back and do it right.