fix(theme): avoid sidebar background color bleeding into page content (#2840)

karthikjeeyar · web-flow · commit ee1def6b4c96 · 2026-04-22T19:10:12.000+05:30
* avoid sidebar color bleeding into page content

Signed-off-by: Karthik &lt;karthik.jk11@gmail.com&gt;

* pick the navigation or rhdh colors based on user's config

Signed-off-by: Karthik &lt;karthik.jk11@gmail.com&gt;

---------

Signed-off-by: Karthik &lt;karthik.jk11@gmail.com&gt;
diff --git a/workspaces/theme/.changeset/nasty-bears-relate.md b/workspaces/theme/.changeset/nasty-bears-relate.md
@@ -0,0 +1,5 @@
+---
+'@red-hat-developer-hub/backstage-plugin-theme': patch
+---
+
+Align the navigation sidebar with merged `palette.navigation` and `rhdh.general` colors, including submenu rows and selected/active `BackstageSidebarItem` states. Add `rhdh.general.pageInsetBackgroundColor` so the page inset shell can use its own color (defaults match the previous app bar fill; falls back to `appBarBackgroundColor` when unset). Main content area remains on `mainSectionBackgroundColor`.
diff --git a/workspaces/theme/plugins/theme/report.api.md b/workspaces/theme/plugins/theme/report.api.md
@@ -67,6 +67,7 @@ export interface RHDHThemePalette {
   // (undocumented)
   general: {
     pageInset: string;
+    pageInsetBackgroundColor: string;
     disabled: string;
     disabledBackground: string;
     paperBackgroundImage: string;
diff --git a/workspaces/theme/plugins/theme/src/darkTheme.ts b/workspaces/theme/plugins/theme/src/darkTheme.ts
@@ -49,6 +49,7 @@ export const darkThemeOverrides: Partial<ThemeConfigPalette> = {
   rhdh: {
     general: {
       pageInset: '1.5rem',
+      pageInsetBackgroundColor: '#151515',
 
       disabled: '#AAABAC',
       disabledBackground: '#444548',
diff --git a/workspaces/theme/plugins/theme/src/lightTheme.ts b/workspaces/theme/plugins/theme/src/lightTheme.ts
@@ -27,7 +27,7 @@ export const lightThemeOverrides: Partial<ThemeConfigPalette> = {
     main: '#0066CC',
   },
   navigation: {
-    background: '#222427',
+    background: '#f2f2f2',
     indicator: 'transparent',
     color: '#151515',
     selectedColor: '#151515',
@@ -49,6 +49,7 @@ export const lightThemeOverrides: Partial<ThemeConfigPalette> = {
   rhdh: {
     general: {
       pageInset: '1.5rem',
+      pageInsetBackgroundColor: '#f2f2f2',
 
       disabled: '#6A6E73',
       disabledBackground: '#D2D2D2',
diff --git a/workspaces/theme/plugins/theme/src/types.ts b/workspaces/theme/plugins/theme/src/types.ts
@@ -21,6 +21,7 @@ export type BackstageThemePalette = UnifiedThemeOptions['palette'];
 export interface RHDHThemePalette {
   general: {
     pageInset: string;
+    pageInsetBackgroundColor: string;
 
     disabled: string;
     disabledBackground: string;
diff --git a/workspaces/theme/plugins/theme/src/utils/createComponents.ts b/workspaces/theme/plugins/theme/src/utils/createComponents.ts
@@ -22,6 +22,7 @@ import { type CSSObject } from '@mui/material/styles';
 
 import { ThemeConfig, ThemeConfigOptions, RHDHThemePalette } from '../types';
 import { redHatFontFaces, redHatFonts } from '../fonts';
+import { resolveNavigationSidebarColors } from './navigationSidebarColors';
 
 export type Component = {
   defaultProps?: unknown;
@@ -616,16 +617,33 @@ export const createComponents = (themeConfig: ThemeConfig): Components => {
   }
 
   if (options.sidebars !== 'mui') {
+    const {
+      sidebarBackgroundColor,
+      sidebarItemInteractionBackgroundColor,
+      navigationItemColor,
+      navigationSelectedColor,
+    } = resolveNavigationSidebarColors(themeConfig);
+
     components.BackstageSidebar = {
       styleOverrides: {
         drawer: {
           gap: '0.25rem',
-          borderRight: `0.5rem solid ${general.sidebarBackgroundColor}`,
+          borderRight: `0.5rem solid ${sidebarBackgroundColor}`,
           paddingBottom: '1.5rem',
-          backgroundColor: general.sidebarBackgroundColor,
+          backgroundColor: sidebarBackgroundColor,
           '& hr': {
             backgroundColor: general.sidebarDividerColor,
           },
+          '& [class*="BackstageSidebarItem-selected-"][class*="BackstageSidebarItem-root-"]':
+            {
+              backgroundColor: `${sidebarItemInteractionBackgroundColor} !important`,
+              color: `${navigationSelectedColor} !important`,
+            },
+
+          '& [class*="BackstageSidebarSubmenuItem-selected-"]': {
+            background: `${sidebarItemInteractionBackgroundColor} !important`,
+            color: `${navigationSelectedColor} !important`,
+          },
         },
       },
     };
@@ -637,7 +655,7 @@ export const createComponents = (themeConfig: ThemeConfig): Components => {
           marginLeft: '0.5rem !important',
           textDecorationLine: 'none',
           '&:hover, &:focus-visible': {
-            backgroundColor: general.sidebarItemSelectedBackgroundColor,
+            backgroundColor: sidebarItemInteractionBackgroundColor,
           },
         },
         label: {
@@ -646,15 +664,16 @@ export const createComponents = (themeConfig: ThemeConfig): Components => {
           },
         },
         selected: {
-          backgroundColor: general.sidebarItemSelectedBackgroundColor,
+          backgroundColor: sidebarItemInteractionBackgroundColor,
+          color: navigationSelectedColor,
         },
       },
     };
     components.MuiBottomNavigation = {
       styleOverrides: {
         root: {
-          backgroundColor: `${general.sidebarBackgroundColor} !important`,
-          borderColor: `${general.sidebarBackgroundColor} !important`,
+          backgroundColor: `${sidebarBackgroundColor} !important`,
+          borderColor: `${sidebarBackgroundColor} !important`,
         },
       },
     };
@@ -664,19 +683,19 @@ export const createComponents = (themeConfig: ThemeConfig): Components => {
       },
       styleOverrides: {
         root: {
-          color: `${palette.text?.primary} !important`,
-          backgroundColor: `${general.sidebarBackgroundColor} !important`,
+          color: `${navigationItemColor} !important`,
+          backgroundColor: `${sidebarBackgroundColor} !important`,
           borderRadius: '6px',
           borderTop: '3px solid transparent !important', // default mui selected styling
           paddingTop: '6px !important', // default mui selected styling
           marginTop: '-1px !important', // default mui selected styling
           '&:hover, &:focus-visible': {
-            backgroundColor: `${general.sidebarItemSelectedBackgroundColor} !important`,
+            backgroundColor: `${sidebarItemInteractionBackgroundColor} !important`,
           },
         },
         selected: {
-          backgroundColor: `${general.sidebarItemSelectedBackgroundColor} !important`,
-          color: `${palette.text?.primary} !important`,
+          backgroundColor: `${sidebarItemInteractionBackgroundColor} !important`,
+          color: `${navigationSelectedColor} !important`,
         },
       },
     };
@@ -685,7 +704,7 @@ export const createComponents = (themeConfig: ThemeConfig): Components => {
         root: {
           // undocumented Backstage makeStyles
           "& [class*='makeStyles-overlay-']": {
-            backgroundColor: `${general.sidebarBackgroundColor} !important`,
+            backgroundColor: `${sidebarBackgroundColor} !important`,
           },
           '& hr': {
             backgroundColor: general.sidebarDividerColor,
@@ -728,7 +747,8 @@ export const createComponents = (themeConfig: ThemeConfig): Components => {
         root: {
           // Controls the page inset as in PF6 -- only in desktop view
           '@media (min-width: 600px)': {
-            backgroundColor: general.sidebarBackgroundColor,
+            backgroundColor:
+              general.pageInsetBackgroundColor ?? general.appBarBackgroundColor,
             // Prevents the main content from scrolling weird
             overflowY: 'auto',
             // Cancel out the spacing produced by the page inset border when
diff --git a/workspaces/theme/plugins/theme/src/utils/navigationSidebarChrome.test.ts b/workspaces/theme/plugins/theme/src/utils/navigationSidebarChrome.test.ts
@@ -0,0 +1,92 @@
+/*
+ * Copyright Red Hat, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import type { ThemeConfig } from '../types';
+import { getDefaultThemeConfig } from '../rhdh';
+import { resolveNavigationSidebarColors } from './navigationSidebarColors';
+
+describe('resolveNavigationSidebarChrome', () => {
+  const defaultLight = getDefaultThemeConfig('light');
+
+  it('matches baseline defaults', () => {
+    const c = resolveNavigationSidebarColors(defaultLight);
+    expect(c.sidebarBackgroundColor).toBe(
+      defaultLight.palette?.rhdh?.general?.sidebarBackgroundColor,
+    );
+    expect(c.sidebarItemInteractionBackgroundColor).toBe(
+      defaultLight.palette?.rhdh?.general?.sidebarItemSelectedBackgroundColor,
+    );
+    expect(c.navigationItemColor).toBe(defaultLight.palette?.navigation?.color);
+    expect(c.navigationSelectedColor).toBe(
+      defaultLight.palette?.navigation?.selectedColor,
+    );
+  });
+
+  it('uses palette.navigation.background when only that differs from baseline', () => {
+    const config = {
+      ...defaultLight,
+      palette: {
+        ...defaultLight.palette,
+        navigation: {
+          ...defaultLight.palette?.navigation,
+          background: '#aabbcc',
+        },
+      },
+    } as ThemeConfig;
+    expect(resolveNavigationSidebarColors(config).sidebarBackgroundColor).toBe(
+      '#aabbcc',
+    );
+  });
+
+  it('uses rhdh.general.sidebarBackgroundColor when only that differs from baseline', () => {
+    const config = {
+      ...defaultLight,
+      palette: {
+        ...defaultLight.palette,
+        rhdh: {
+          ...defaultLight.palette?.rhdh,
+          general: {
+            ...defaultLight.palette?.rhdh?.general,
+            sidebarBackgroundColor: '#ddeeff',
+          },
+        },
+      },
+    } as ThemeConfig;
+    expect(resolveNavigationSidebarColors(config).sidebarBackgroundColor).toBe(
+      '#ddeeff',
+    );
+  });
+
+  it('uses palette.navigation.navItem.hoverBackground when only that differs from baseline', () => {
+    const config = {
+      ...defaultLight,
+      palette: {
+        ...defaultLight.palette,
+        navigation: {
+          ...defaultLight.palette?.navigation,
+          navItem: {
+            ...defaultLight.palette?.navigation?.navItem,
+            hoverBackground: '#0a0b0c',
+          },
+        },
+      },
+    } as ThemeConfig;
+    expect(
+      resolveNavigationSidebarColors(config)
+        .sidebarItemInteractionBackgroundColor,
+    ).toBe('#0a0b0c');
+  });
+});
diff --git a/workspaces/theme/plugins/theme/src/utils/navigationSidebarColors.ts b/workspaces/theme/plugins/theme/src/utils/navigationSidebarColors.ts

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +'@red-hat-developer-hub/backstage-plugin-theme': patch
 +---
++
 +Align the navigation sidebar with merged `palette.navigation` and `rhdh.general` colors, including submenu rows and selected/active `BackstageSidebarItem` states. Add `rhdh.general.pageInsetBackgroundColor` so the page inset shell can use its own color (defaults match the previous app bar fill; falls back to `appBarBackgroundColor` when unset). Main content area remains on `mainSectionBackgroundColor`.