backstage-theming

Backstage theming and design

Two theme systems run side by side in a current Backstage app, and most theming bugs are one of them being styled while the other is not. Decide which surface you are changing before you change anything.

Preconditions

• Frontend generation known. NFS: createApp from @backstage/frontend-defaults, themes registered as extensions via ThemeBlueprint from @backstage/plugin-app-react. Legacy: createApp from @backstage/app-defaults with a themes array option. The theme objects are nearly identical; only registration differs. Run backstage-repo-discovery if unsure.
• Which system owns the pixels you are changing:
  • @backstage/ui ("BUI") — CSS custom properties, --bui-*. Newer surfaces: entity cards, headers, tables, form controls.
  • @backstage/theme + Material UI — a JS theme object. Older plugin pages and every third-party plugin that has not migrated. A portal on a current line contains both. Styling one and declaring victory is the single most common outcome here.
• packages/app/src/index.tsx imports @backstage/ui/css/styles.css. Without it no BUI token has a value and every BUI component renders unstyled.
• Exact theme factory signatures (createUnifiedTheme, createBaseThemeOptions, genPageTheme, and the ThemeBlueprint input shape) read from the installed @backstage/theme and @backstage/plugin-app-react types, not from memory.
• Brand assets available as real files. Do not invent colour values; ask for the brand tokens or read them from an existing asset, and record the source.

Procedure

1. Inventory what is themed today. rg -n "createUnifiedTheme|UnifiedThemeProvider|ThemeBlueprint|themes:" packages/app/src and rg -n "\-\-bui-" packages plugins. Note whether a custom theme exists at all — a default create-app has none, and adding the first one is a different job from editing an existing one.
2. Change BUI tokens first, in one place. Override the custom properties on :root in a stylesheet imported after @backstage/ui/css/styles.css. The families are --bui-bg-*, --bui-fg-*, --bui-gray-*, --bui-accent-*, --bui-border-*, --bui-radius-*, --bui-font-*, --bui-space-*, plus the status families --bui-positive-*, --bui-negative-*, --bui-warning-* and --bui-announcement-*. Read the shipped dist/css/styles.css in the installed @backstage/ui for the exact names on your version; they are added to between minors.
3. Do light and dark together or neither. BUI scopes its palette with a data-theme attribute on a root element. An override written only against :root leaks the light value into dark mode, which looks like "dark mode is broken" and is really a missing scoped override. Set every colour token under both selectors.
4. Then the Material UI side. createUnifiedTheme from @backstage/theme produces a theme both v4 and v5 consumers can use; createUnifiedThemeFromV4 adapts an existing v4 theme rather than rewriting it. Compose from createBaseThemeOptions and palettes.light / palettes.dark instead of building a palette by hand — the defaults carry the page gradients and status colours plugins expect to exist.
5. Set page themes deliberately. genPageTheme({ colors, shape }) builds the header gradient per page type (home, tool, service, website, library, app, apis, documentation, other). Omitting a page type leaves it on the default, which is the usual cause of "one page still has the old header".
6. Register the theme for your generation.
   • NFS: create a theme extension with ThemeBlueprint from @backstage/plugin-app-react and add it to a frontend module. Read the blueprint's parameter names from the installed package before writing it.
   • Legacy: pass themes: [{ id, title, variant, icon, Provider }] to createApp, with Provider rendering UnifiedThemeProvider. Registering a theme does not select it: users pick per account in settings, so verify by switching, not by loading the page once.
7. Keep BUIProvider in the tree, inside the router. It supplies the analytics context and, when it detects a router, installs react-aria's RouterProvider so BUI navigation resolves client-side. Outside the router it silently degrades to no routing integration.
8. Override a component's look through its definition, not its internals. Each BUI component exports a <Name>Definition alongside it. Prefer a token change, then a definition override, then a wrapper component. Never target BUI's generated class names — they are not a public API and change without a major.
9. Brand the app shell. Logos live in packages/app/src/modules/nav/ (LogoFull.tsx, LogoIcon.tsx, SidebarLogo.tsx) in a current scaffold. Replace the SVG contents, keep the components' exported names and their viewBox-driven sizing, and check the collapsed sidebar as well as expanded.
10. Set app.title and organization.name in app-config.yaml. They drive the browser title and several page headers, and a rebrand that misses them leaves the old name in the tab.
11. Check contrast before shipping. Brand colours frequently fail WCAG AA on Backstage's surfaces, particularly accent-on-surface for links and the status families. Fix the token, not the component.