From 021b36800f1f32da7f61ab72ac371c5903b9ab56 Mon Sep 17 00:00:00 2001
From: Charles de Dreuille <charles.dedreuille@gmail.com>
Date: Thu, 30 Apr 2026 09:33:18 +0100
Subject: [PATCH] fix(ui): collapse plugin header spacing before headers

Signed-off-by: Charles de Dreuille <charles.dedreuille@gmail.com>
---
 .changeset/core-header-marker.md              |  5 +++
 .changeset/plugin-header-spacing.md           |  2 +-
 .../src/layout/Header/Header.tsx              |  6 +++-
 packages/ui/package.json                      |  1 +
 .../PluginHeader/PluginHeader.module.css      | 17 +++++++--
 .../recipes/PluginHeaderAndHeader.stories.tsx | 35 +++++++++++++++++++
 yarn.lock                                     |  1 +
 7 files changed, 62 insertions(+), 5 deletions(-)
 create mode 100644 .changeset/core-header-marker.md

diff --git a/.changeset/core-header-marker.md b/.changeset/core-header-marker.md
new file mode 100644
index 0000000000..6260c8d690
--- /dev/null
+++ b/.changeset/core-header-marker.md
@@ -0,0 +1,5 @@
+---
+'@backstage/core-components': patch
+---
+
+Added a stable DOM marker to the legacy Header so adjacent layout components can coordinate spacing without relying on generated class names.
diff --git a/.changeset/plugin-header-spacing.md b/.changeset/plugin-header-spacing.md
index bebf7a5608..a1c370ea19 100644
--- a/.changeset/plugin-header-spacing.md
+++ b/.changeset/plugin-header-spacing.md
@@ -2,6 +2,6 @@
 '@backstage/ui': patch
 ---
 
-Adjusted PluginHeader spacing so headers with and without tabs align more consistently with surrounding page content.
+Adjusted PluginHeader spacing and borders so headers with and without tabs align more consistently with surrounding page content, including when paired with page headers.
 
 **Affected components:** PluginHeader, Header
diff --git a/packages/core-components/src/layout/Header/Header.tsx b/packages/core-components/src/layout/Header/Header.tsx
index f5facda641..3320ba782a 100644
--- a/packages/core-components/src/layout/Header/Header.tsx
+++ b/packages/core-components/src/layout/Header/Header.tsx
@@ -228,7 +228,11 @@ export function Header(props: PropsWithChildren<Props>) {
   return (
     <>
       <Helmet titleTemplate={titleTemplate} defaultTitle={defaultTitle} />
-      <header style={style} className={classes.header}>
+      <header
+        style={style}
+        className={classes.header}
+        data-backstage-core-header=""
+      >
         <Box className={classes.leftItemsBox}>
           <TypeFragment
             classes={classes}
diff --git a/packages/ui/package.json b/packages/ui/package.json
index a8c28464ed..c68a85b7e5 100644
--- a/packages/ui/package.json
+++ b/packages/ui/package.json
@@ -60,6 +60,7 @@
   },
   "devDependencies": {
     "@backstage/cli": "workspace:^",
+    "@backstage/core-components": "workspace:^",
     "@storybook/react-vite": "^10.3.3",
     "@testing-library/jest-dom": "^6.0.0",
     "@testing-library/react": "^16.0.0",
diff --git a/packages/ui/src/components/PluginHeader/PluginHeader.module.css b/packages/ui/src/components/PluginHeader/PluginHeader.module.css
index d222dae965..8268d9cab0 100644
--- a/packages/ui/src/components/PluginHeader/PluginHeader.module.css
+++ b/packages/ui/src/components/PluginHeader/PluginHeader.module.css
@@ -18,18 +18,29 @@
 
 @layer components {
   .bui-PluginHeader {
-    margin-bottom: var(--bui-space-6);
+    --bui-plugin-header-margin-bottom: var(--bui-space-6);
+    --bui-plugin-header-toolbar-border-bottom: solid 1px var(--bui-border-1);
+    --bui-plugin-header-tabs-border-bottom: 1px solid var(--bui-border-1);
+
+    margin-bottom: var(--bui-plugin-header-margin-bottom);
     padding-inline: var(--bui-space-5);
     margin-top: var(--bui-space-4);
   }
 
+  .bui-PluginHeader:has(+ .bui-HeaderTop),
+  .bui-PluginHeader:has(+ [data-backstage-core-header]) {
+    --bui-plugin-header-margin-bottom: 0;
+    --bui-plugin-header-toolbar-border-bottom: none;
+    --bui-plugin-header-tabs-border-bottom: none;
+  }
+
   .bui-PluginHeaderToolbar {
     display: flex;
     flex-direction: row;
     align-items: center;
     justify-content: space-between;
     color: var(--bui-fg-primary);
-    border-bottom: solid 1px var(--bui-border-1);
+    border-bottom: var(--bui-plugin-header-toolbar-border-bottom);
     padding-bottom: var(--bui-space-4);
 
     &[data-has-tabs] {
@@ -79,6 +90,6 @@
   }
 
   .bui-PluginHeaderTabsWrapper {
-    border-bottom: 1px solid var(--bui-border-1);
+    border-bottom: var(--bui-plugin-header-tabs-border-bottom);
   }
 }
diff --git a/packages/ui/src/recipes/PluginHeaderAndHeader.stories.tsx b/packages/ui/src/recipes/PluginHeaderAndHeader.stories.tsx
index b3bad07185..fab2262f3b 100644
--- a/packages/ui/src/recipes/PluginHeaderAndHeader.stories.tsx
+++ b/packages/ui/src/recipes/PluginHeaderAndHeader.stories.tsx
@@ -15,6 +15,7 @@
  */
 
 import preview from '../../../../.storybook/preview';
+import { Header as CoreHeader } from '@backstage/core-components';
 import type { StoryFn } from '@storybook/react-vite';
 import { MemoryRouter } from 'react-router-dom';
 import { BUIProvider } from '../provider';
@@ -137,6 +138,40 @@ export const SimpleHeader = meta.story({
   ),
 });
 
+export const CoreComponentsHeader = meta.story({
+  decorators: [withLayout],
+  render: () => (
+    <>
+      <PluginHeader icon={<RiCodeSSlashLine />} title="APIs" />
+      <CoreHeader title="payments-api" />
+      <PageContent />
+    </>
+  ),
+});
+
+export const CoreComponentsHeaderWithTabs = meta.story({
+  decorators: [withLayout],
+  render: () => (
+    <>
+      <PluginHeader
+        icon={<RiCodeSSlashLine />}
+        title="APIs"
+        tabs={[
+          { id: 'overview', label: 'Overview', href: '/apis' },
+          {
+            id: 'definitions',
+            label: 'Definitions',
+            href: '/apis/definitions',
+          },
+          { id: 'consumers', label: 'Consumers', href: '/apis/consumers' },
+        ]}
+      />
+      <CoreHeader title="payments-api" />
+      <PageContent />
+    </>
+  ),
+});
+
 export const WithTabs = meta.story({
   decorators: [withLayout],
   render: () => (
diff --git a/yarn.lock b/yarn.lock
index 37c405d2f9..b11895427f 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -7949,6 +7949,7 @@ __metadata:
   resolution: "@backstage/ui@workspace:packages/ui"
   dependencies:
     "@backstage/cli": "workspace:^"
+    "@backstage/core-components": "workspace:^"
     "@backstage/version-bridge": "workspace:^"
     "@braintree/sanitize-url": "npm:^7.1.2"
     "@internationalized/date": "npm:^3.12.0"