From 5351d8ac639e9dbafaf9aea8dc7bcc88c39fc6d0 Mon Sep 17 00:00:00 2001
From: Charles de Dreuille <charles.dedreuille@gmail.com>
Date: Sun, 26 Apr 2026 09:04:51 +0100
Subject: [PATCH 01/15] Add sticky Header support

Signed-off-by: Charles de Dreuille <charles.dedreuille@gmail.com>
---
 .changeset/header-sticky-prop.md              |   5 +
 .storybook/preview.tsx                        |  49 ++---
 .storybook/themes/spotify.css                 |   4 -
 .../components/Container/Container.module.css |   2 +
 .../src/components/Header/Header.module.css   |  87 +++++++-
 .../src/components/Header/Header.stories.tsx  |  90 +++++++++
 packages/ui/src/components/Header/Header.tsx  | 188 ++++++++++++------
 .../ui/src/components/Header/definition.ts    |   6 +
 packages/ui/src/components/Header/types.ts    |   1 +
 9 files changed, 333 insertions(+), 99 deletions(-)
 create mode 100644 .changeset/header-sticky-prop.md

diff --git a/.changeset/header-sticky-prop.md b/.changeset/header-sticky-prop.md
new file mode 100644
index 0000000000..283c235d43
--- /dev/null
+++ b/.changeset/header-sticky-prop.md
@@ -0,0 +1,5 @@
+---
+'@backstage/ui': patch
+---
+
+Added a `sticky` prop to the `Header` component. When `true`, the title-and-actions bar stays fixed to the top of its scroll container while the rest of the header (tags, description, metadata) scrolls away. The sticky bar background color automatically matches the container surface using the bg-consumer system.
diff --git a/.storybook/preview.tsx b/.storybook/preview.tsx
index 916c48951d..eb0b111bc9 100644
--- a/.storybook/preview.tsx
+++ b/.storybook/preview.tsx
@@ -50,26 +50,11 @@ export default definePreview({
         dynamicTitle: true,
       },
     },
-    background: {
-      name: 'Background',
-      description: 'Global background for components',
-      defaultValue: 'app',
-      toolbar: {
-        icon: 'contrast',
-        items: [
-          { value: 'app', title: 'App Background' },
-          { value: 'neutral-1', title: 'Neutral 1 Background' },
-          { value: 'neutral-2', title: 'Neutral 2 Background' },
-          { value: 'neutral-3', title: 'Neutral 3 Background' },
-        ],
-      },
-    },
   },
 
   initialGlobals: {
     themeMode: 'light',
     themeName: 'backstage',
-    background: 'app',
   },
 
   parameters: {
@@ -143,7 +128,6 @@ export default definePreview({
         globals.themeMode === 'light' ? themes.light : themes.dark;
       const selectedThemeMode = globals.themeMode || 'light';
       const selectedThemeName = globals.themeName || 'backstage';
-      const selectedBackground = globals.background || 'app';
       const isFullscreen = context.parameters.layout === 'fullscreen';
 
       useEffect(() => {
@@ -155,15 +139,13 @@ export default definePreview({
           document.body.removeAttribute('data-theme-mode');
           document.body.removeAttribute('data-theme-name');
         };
-      }, [selectedTheme, selectedThemeName]);
+      }, [selectedThemeMode, selectedThemeName]);
 
       useEffect(() => {
         appThemeApi.setActiveThemeId(selectedThemeMode);
       }, [selectedThemeMode]);
 
       document.body.style.backgroundColor = 'var(--bui-bg-app)';
-      document.body.style.padding =
-        isFullscreen && selectedBackground !== 'app' ? '1rem' : '';
       const docsStoryElements = document.getElementsByClassName('docs-story');
       Array.from(docsStoryElements).forEach(element => {
         (element as HTMLElement).style.backgroundColor = 'var(--bui-bg-app)';
@@ -174,18 +156,23 @@ export default definePreview({
           {/* @ts-ignore */}
           <TestApiProvider apis={apis}>
             <AlertDisplay />
-            {Array.from({
-              length:
-                selectedBackground === 'app'
-                  ? 0
-                  : parseInt(selectedBackground.split('-')[1], 10),
-            }).reduce<React.ReactNode>(
-              children => (
-                <Box bg="neutral" p="4">
-                  {children}
-                </Box>
-              ),
-              <Story />,
+            {selectedThemeName === 'spotify' ? (
+              <Box
+                bg="neutral"
+                m={isFullscreen ? '4' : undefined}
+                style={{
+                  borderRadius: 'var(--bui-radius-3)',
+                  height: isFullscreen
+                    ? 'calc(100vh - (var(--bui-space-4) * 2))'
+                    : undefined,
+                  overflow: 'auto',
+                  overscrollBehavior: 'none',
+                }}
+              >
+                <Story />
+              </Box>
+            ) : (
+              <Story />
             )}
           </TestApiProvider>
         </UnifiedThemeProvider>
diff --git a/.storybook/themes/spotify.css b/.storybook/themes/spotify.css
index 30aa0274d0..d8f06c68c0 100644
--- a/.storybook/themes/spotify.css
+++ b/.storybook/themes/spotify.css
@@ -190,10 +190,6 @@
   .bui-Tag {
     border-radius: var(--bui-radius-full);
   }
-
-  .bui-Container {
-    padding-inline: 0;
-  }
 }
 
 [data-theme-mode='light'][data-theme-name='spotify'] {
diff --git a/packages/ui/src/components/Container/Container.module.css b/packages/ui/src/components/Container/Container.module.css
index 1ebf52ccf3..9381126ee4 100644
--- a/packages/ui/src/components/Container/Container.module.css
+++ b/packages/ui/src/components/Container/Container.module.css
@@ -18,6 +18,8 @@
 
 @layer components {
   .bui-Container {
+    flex: 1;
+    width: 100%;
     max-width: 120rem;
     padding-inline: var(--bui-space-4);
     margin-inline: auto;
diff --git a/packages/ui/src/components/Header/Header.module.css b/packages/ui/src/components/Header/Header.module.css
index 2e3ca28d3b..08626268f7 100644
--- a/packages/ui/src/components/Header/Header.module.css
+++ b/packages/ui/src/components/Header/Header.module.css
@@ -18,16 +18,87 @@
 
 @layer components {
   .bui-Header {
+    display: flex;
+    flex-direction: column;
+    padding-top: var(--bui-space-2);
+    width: 100%;
+    padding-inline: var(--bui-space-5);
+  }
+
+  .bui-Header[data-sticky] {
+    display: contents;
+  }
+
+  .bui-HeaderAfterSticky {
     display: flex;
     flex-direction: column;
     gap: var(--bui-space-3);
-    margin-top: var(--bui-space-6);
+  }
+
+  .bui-Header[data-sticky] .bui-HeaderBeforeSticky,
+  .bui-Header[data-sticky] .bui-HeaderStickySentinel,
+  .bui-Header[data-sticky] .bui-HeaderContent,
+  .bui-Header[data-sticky] .bui-HeaderAfterSticky {
+    width: 100%;
+    padding-inline: var(--bui-space-5);
+    box-sizing: border-box;
+  }
+
+  .bui-HeaderBeforeSticky {
+    padding-top: var(--bui-space-4);
+  }
+
+  .bui-Header[data-sticky] .bui-HeaderBeforeSticky {
+    padding-top: var(--bui-space-6);
+  }
+
+  .bui-HeaderStickySentinel {
+    height: 1px;
+    margin-bottom: -1px;
+    pointer-events: none;
   }
 
   .bui-HeaderContent {
     display: flex;
     flex-direction: row;
     justify-content: space-between;
+    gap: var(--bui-space-3);
+    padding-block: var(--bui-space-3);
+  }
+
+  .bui-HeaderContent[data-sticky] {
+    position: sticky;
+    top: 0;
+    z-index: 10;
+    background-color: var(--bui-bg-app);
+
+    .bui-Header[data-on-bg='neutral-1'] & {
+      background-color: var(--bui-bg-neutral-1);
+    }
+
+    .bui-Header[data-on-bg='neutral-2'] & {
+      background-color: var(--bui-bg-neutral-2);
+    }
+
+    .bui-Header[data-on-bg='neutral-3'] & {
+      background-color: var(--bui-bg-neutral-3);
+    }
+  }
+
+  .bui-HeaderContent[data-sticky]::after {
+    position: absolute;
+    right: 0;
+    bottom: 0;
+    left: 0;
+    height: 1px;
+    content: '';
+    background-color: var(--bui-border-1);
+    opacity: 0;
+    transition: opacity 200ms ease;
+  }
+
+  .bui-HeaderContent[data-stuck]::after {
+    opacity: 1;
   }
 
   .bui-HeaderTabsWrapper {
@@ -39,6 +110,7 @@
     flex-direction: row;
     align-items: center;
     gap: var(--bui-space-2);
+    flex-shrink: 0;
   }
 
   .bui-HeaderBreadcrumbs {
@@ -46,6 +118,19 @@
     flex-direction: row;
     align-items: center;
     gap: var(--bui-space-2);
+    min-width: 0;
+  }
+
+  .bui-HeaderTitle {
+    margin: 0;
+    padding: 0;
+    overflow: hidden;
+    font-family: var(--bui-font-regular);
+    font-size: var(--bui-font-size-6);
+    font-weight: var(--bui-font-weight-bold);
+    line-height: 140%;
+    text-overflow: ellipsis;
+    white-space: nowrap;
   }
 
   .bui-HeaderTags {
diff --git a/packages/ui/src/components/Header/Header.stories.tsx b/packages/ui/src/components/Header/Header.stories.tsx
index 59e5cf254d..09dadce9f4 100644
--- a/packages/ui/src/components/Header/Header.stories.tsx
+++ b/packages/ui/src/components/Header/Header.stories.tsx
@@ -24,6 +24,7 @@ import { MemoryRouter } from 'react-router-dom';
 import { BUIProvider } from '../../provider';
 import { Button, ButtonIcon, MenuTrigger, Menu, MenuItem } from '../../';
 import { RiMore2Line } from '@remixicon/react';
+import { Container } from '../Container/Container';
 
 const meta = preview.meta({
   title: 'Backstage UI/Header',
@@ -393,3 +394,92 @@ export const WithExplicitActiveTab = meta.story({
     activeTabId: 'campaigns',
   },
 });
+
+export const NonSticky = meta.story({
+  decorators: [withRouter],
+  render: () => (
+    <>
+      <Header
+        title="Sticky Page Title"
+        description="This is a description of the page that scrolls away when you scroll down."
+        tags={[
+          { label: 'TypeScript' },
+          { label: 'Platform', href: '/platform' },
+        ]}
+        metadata={[
+          { label: 'Owner', value: 'platform-team' },
+          { label: 'Type', value: 'website' },
+        ]}
+        customActions={<Button>Custom action</Button>}
+      />
+      <Container pb="3">
+        {Array.from({ length: 60 }, (_, i) => (
+          <p key={i} style={{ marginBottom: '16px' }}>
+            Scroll down to see the title bar stick to the top while the tags,
+            description, and metadata scroll away. Line {i + 1}.
+          </p>
+        ))}
+      </Container>
+    </>
+  ),
+});
+
+export const Sticky = meta.story({
+  decorators: [withRouter],
+  render: () => (
+    <>
+      <Header
+        title="Sticky Page Title"
+        sticky
+        description="This is a description of the page that scrolls away when you scroll down."
+        tags={[
+          { label: 'TypeScript' },
+          { label: 'Platform', href: '/platform' },
+        ]}
+        metadata={[
+          { label: 'Owner', value: 'platform-team' },
+          { label: 'Type', value: 'website' },
+        ]}
+        customActions={<Button>Custom action</Button>}
+      />
+      <Container pb="3">
+        {Array.from({ length: 60 }, (_, i) => (
+          <p key={i} style={{ marginBottom: '16px' }}>
+            Scroll down to see the title bar stick to the top while the tags,
+            description, and metadata scroll away. Line {i + 1}.
+          </p>
+        ))}
+      </Container>
+    </>
+  ),
+});
+
+export const StickyWithLongTitle = meta.story({
+  decorators: [withRouter],
+  render: () => (
+    <>
+      <Header
+        title="This is a very long page title that should demonstrate how the sticky Header behaves when the title takes up significantly more horizontal space than usual"
+        sticky
+        description="This is a description of the page that scrolls away when you scroll down."
+        tags={[
+          { label: 'TypeScript' },
+          { label: 'Platform', href: '/platform' },
+        ]}
+        metadata={[
+          { label: 'Owner', value: 'platform-team' },
+          { label: 'Type', value: 'website' },
+        ]}
+        customActions={<Button>Custom action</Button>}
+      />
+      <Container pb="3">
+        {Array.from({ length: 60 }, (_, i) => (
+          <p key={i} style={{ marginBottom: '16px' }}>
+            Scroll down to see the long title bar stick to the top while the
+            tags, description, and metadata scroll away. Line {i + 1}.
+          </p>
+        ))}
+      </Container>
+    </>
+  ),
+});
diff --git a/packages/ui/src/components/Header/Header.tsx b/packages/ui/src/components/Header/Header.tsx
index 3f17e35732..ae992f4b41 100644
--- a/packages/ui/src/components/Header/Header.tsx
+++ b/packages/ui/src/components/Header/Header.tsx
@@ -21,10 +21,25 @@ import { HeaderNav } from './HeaderNav';
 import { useDefinition } from '../../hooks/useDefinition';
 import { HeaderDefinition } from './definition';
 import { sanitizeUrl } from '@braintree/sanitize-url';
-import { Container } from '../Container';
 import { Lexer } from 'marked';
 import { Link } from '../Link';
-import { Fragment, useMemo } from 'react';
+import { Fragment, useEffect, useMemo, useRef, useState } from 'react';
+
+const getScrollParent = (element: HTMLElement | null): Element | null => {
+  let parent = element?.parentElement;
+
+  while (parent) {
+    const { overflowY } = window.getComputedStyle(parent);
+
+    if (/(auto|scroll|overlay)/.test(overflowY)) {
+      return parent;
+    }
+
+    parent = parent.parentElement;
+  }
+
+  return null;
+};
 
 /**
  * Parses inline Markdown links in a string and returns an array of React nodes.
@@ -52,7 +67,7 @@ function renderInlineMarkdown(text: string): React.ReactNode[] {
  * @public
  */
 export const Header = (props: HeaderProps) => {
-  const { ownProps } = useDefinition(HeaderDefinition, props);
+  const { ownProps, dataAttributes } = useDefinition(HeaderDefinition, props);
   const {
     classes,
     title,
@@ -63,41 +78,86 @@ export const Header = (props: HeaderProps) => {
     description,
     tags,
     metadata,
+    sticky,
   } = ownProps;
 
   const descriptionNodes = useMemo(
     () => (description ? renderInlineMarkdown(description) : null),
     [description],
   );
+  const stickySentinelRef = useRef<HTMLDivElement>(null);
+  const [isStuck, setIsStuck] = useState(false);
+
+  useEffect(() => {
+    if (!sticky) {
+      setIsStuck(false);
+      return;
+    }
+
+    const sentinel = stickySentinelRef.current;
+    if (!sentinel) {
+      return;
+    }
+
+    const observer = new IntersectionObserver(
+      ([entry]) => {
+        setIsStuck(!entry.isIntersecting);
+      },
+      { root: getScrollParent(sentinel), threshold: 0 },
+    );
+
+    observer.observe(sentinel);
+
+    return () => {
+      observer.disconnect();
+    };
+  }, [sticky]);
 
   return (
-    <Container className={classes.root}>
+    <header
+      className={classes.root}
+      data-sticky={sticky || undefined}
+      {...dataAttributes}
+    >
       {tags && tags.length > 0 && (
-        <ul className={classes.tags}>
-          {tags.map((tag, i) => (
-            <li
-              key={`${i}:${tag.label}:${tag.href ?? ''}`}
-              className={classes.tag}
-            >
-              {tag.href ? (
-                <Link
-                  href={tag.href}
-                  variant="body-medium"
-                  color="secondary"
-                  standalone
-                >
-                  {tag.label}
-                </Link>
-              ) : (
-                <Text variant="body-medium" color="secondary">
-                  {tag.label}
-                </Text>
-              )}
-            </li>
-          ))}
-        </ul>
+        <div className={classes.beforeSticky}>
+          <ul className={classes.tags}>
+            {tags.map((tag, i) => (
+              <li
+                key={`${i}:${tag.label}:${tag.href ?? ''}`}
+                className={classes.tag}
+              >
+                {tag.href ? (
+                  <Link
+                    href={tag.href}
+                    variant="body-medium"
+                    color="secondary"
+                    standalone
+                  >
+                    {tag.label}
+                  </Link>
+                ) : (
+                  <Text variant="body-medium" color="secondary">
+                    {tag.label}
+                  </Text>
+                )}
+              </li>
+            ))}
+          </ul>
+        </div>
       )}
-      <div className={classes.content}>
+      {sticky && (
+        <div
+          ref={stickySentinelRef}
+          className={classes.stickySentinel}
+          aria-hidden="true"
+        />
+      )}
+      <div
+        className={classes.content}
+        data-sticky={sticky || undefined}
+        data-stuck={isStuck || undefined}
+      >
         <div className={classes.breadcrumbs}>
           {breadcrumbs &&
             breadcrumbs.map(breadcrumb => (
@@ -116,47 +176,49 @@ export const Header = (props: HeaderProps) => {
                 <RiArrowRightSLine size={16} color="var(--bui-fg-secondary)" />
               </Fragment>
             ))}
-          <Text variant="title-small" weight="bold" as="h2">
-            {title}
-          </Text>
+          <h2 className={classes.title}>{title}</h2>
         </div>
         <div className={classes.controls}>{customActions}</div>
       </div>
-      {description && (
-        <Text
-          variant="body-medium"
-          color="secondary"
-          className={classes.description}
-        >
-          {descriptionNodes}
-        </Text>
-      )}
-      {metadata && metadata.length > 0 && (
-        <dl className={classes.metaRow}>
-          {metadata.map((item, i) => (
-            <div key={`${i}:${item.label}`} className={classes.metaItem}>
-              <dt>
-                <Text variant="body-medium" color="secondary">
-                  {item.label}
-                </Text>
-              </dt>
-              <dd>
-                {typeof item.value === 'string' ? (
-                  <Text variant="body-medium">{item.value}</Text>
-                ) : (
-                  item.value
-                )}
-              </dd>
+      {(description || (metadata && metadata.length > 0) || tabs) && (
+        <div className={classes.afterSticky}>
+          {description && (
+            <Text
+              variant="body-medium"
+              color="secondary"
+              className={classes.description}
+            >
+              {descriptionNodes}
+            </Text>
+          )}
+          {metadata && metadata.length > 0 && (
+            <dl className={classes.metaRow}>
+              {metadata.map((item, i) => (
+                <div key={`${i}:${item.label}`} className={classes.metaItem}>
+                  <dt>
+                    <Text variant="body-medium" color="secondary">
+                      {item.label}
+                    </Text>
+                  </dt>
+                  <dd>
+                    {typeof item.value === 'string' ? (
+                      <Text variant="body-medium">{item.value}</Text>
+                    ) : (
+                      item.value
+                    )}
+                  </dd>
+                </div>
+              ))}
+            </dl>
+          )}
+          {tabs && (
+            <div className={classes.tabsWrapper}>
+              <HeaderNav tabs={tabs} activeTabId={activeTabId} />
             </div>
-          ))}
-        </dl>
-      )}
-      {tabs && (
-        <div className={classes.tabsWrapper}>
-          <HeaderNav tabs={tabs} activeTabId={activeTabId} />
+          )}
         </div>
       )}
-    </Container>
+    </header>
   );
 };
 
diff --git a/packages/ui/src/components/Header/definition.ts b/packages/ui/src/components/Header/definition.ts
index c0420dade5..ace08f5195 100644
--- a/packages/ui/src/components/Header/definition.ts
+++ b/packages/ui/src/components/Header/definition.ts
@@ -24,10 +24,15 @@ import styles from './Header.module.css';
  */
 export const HeaderDefinition = defineComponent<HeaderOwnProps>()({
   styles,
+  bg: 'consumer',
   classNames: {
     root: 'bui-Header',
+    beforeSticky: 'bui-HeaderBeforeSticky',
+    stickySentinel: 'bui-HeaderStickySentinel',
     content: 'bui-HeaderContent',
+    afterSticky: 'bui-HeaderAfterSticky',
     breadcrumbs: 'bui-HeaderBreadcrumbs',
+    title: 'bui-HeaderTitle',
     tabsWrapper: 'bui-HeaderTabsWrapper',
     controls: 'bui-HeaderControls',
     tags: 'bui-HeaderTags',
@@ -46,6 +51,7 @@ export const HeaderDefinition = defineComponent<HeaderOwnProps>()({
     tags: {},
     metadata: {},
     className: {},
+    sticky: {},
   },
 });
 
diff --git a/packages/ui/src/components/Header/types.ts b/packages/ui/src/components/Header/types.ts
index bc9ce8985b..d126f40ce3 100644
--- a/packages/ui/src/components/Header/types.ts
+++ b/packages/ui/src/components/Header/types.ts
@@ -116,6 +116,7 @@ export interface HeaderOwnProps {
   tags?: HeaderTag[];
   metadata?: HeaderMetadataItem[];
   className?: string;
+  sticky?: boolean;
 }
 
 /**

From eb1fabae6ba5fd843ceddd7dbf72dc2b5347a704 Mon Sep 17 00:00:00 2001
From: Charles de Dreuille <charles.dedreuille@gmail.com>
Date: Sun, 26 Apr 2026 09:26:12 +0100
Subject: [PATCH 02/15] Refine sticky Header title transition

Signed-off-by: Charles de Dreuille <charles.dedreuille@gmail.com>
---
 packages/ui/report.api.md                     | 26 +++++++
 .../src/components/Header/Header.module.css   | 77 +++++++++++++++++--
 .../src/components/Header/Header.stories.tsx  | 35 +++++++++
 packages/ui/src/components/Header/Header.tsx  | 68 +++++++++++-----
 .../ui/src/components/Header/definition.ts    |  6 ++
 5 files changed, 188 insertions(+), 24 deletions(-)

diff --git a/packages/ui/report.api.md b/packages/ui/report.api.md
index 1e549de36d..d49a512536 100644
--- a/packages/ui/report.api.md
+++ b/packages/ui/report.api.md
@@ -1579,10 +1579,21 @@ export const HeaderDefinition: {
   readonly styles: {
     readonly [key: string]: string;
   };
+  readonly bg: 'consumer';
   readonly classNames: {
     readonly root: 'bui-Header';
+    readonly beforeSticky: 'bui-HeaderBeforeSticky';
+    readonly stickySentinel: 'bui-HeaderStickySentinel';
     readonly content: 'bui-HeaderContent';
+    readonly afterSticky: 'bui-HeaderAfterSticky';
     readonly breadcrumbs: 'bui-HeaderBreadcrumbs';
+    readonly breadcrumbsSmall: 'bui-HeaderBreadcrumbsSmall';
+    readonly breadcrumbLink: 'bui-HeaderBreadcrumbLink';
+    readonly breadcrumbLinkSmall: 'bui-HeaderBreadcrumbLinkSmall';
+    readonly breadcrumbSeparator: 'bui-HeaderBreadcrumbSeparator';
+    readonly titleStack: 'bui-HeaderTitleStack';
+    readonly title: 'bui-HeaderTitle';
+    readonly titleSmall: 'bui-HeaderTitleSmall';
     readonly tabsWrapper: 'bui-HeaderTabsWrapper';
     readonly controls: 'bui-HeaderControls';
     readonly tags: 'bui-HeaderTags';
@@ -1601,6 +1612,7 @@ export const HeaderDefinition: {
     readonly tags: {};
     readonly metadata: {};
     readonly className: {};
+    readonly sticky: {};
   };
 };
 
@@ -1732,6 +1744,8 @@ export interface HeaderOwnProps {
   // (undocumented)
   metadata?: HeaderMetadataItem[];
   // (undocumented)
+  sticky?: boolean;
+  // (undocumented)
   tabs?: HeaderNavTabItem[];
   // (undocumented)
   tags?: HeaderTag[];
@@ -1750,10 +1764,21 @@ export const HeaderPageDefinition: {
   readonly styles: {
     readonly [key: string]: string;
   };
+  readonly bg: 'consumer';
   readonly classNames: {
     readonly root: 'bui-Header';
+    readonly beforeSticky: 'bui-HeaderBeforeSticky';
+    readonly stickySentinel: 'bui-HeaderStickySentinel';
     readonly content: 'bui-HeaderContent';
+    readonly afterSticky: 'bui-HeaderAfterSticky';
     readonly breadcrumbs: 'bui-HeaderBreadcrumbs';
+    readonly breadcrumbsSmall: 'bui-HeaderBreadcrumbsSmall';
+    readonly breadcrumbLink: 'bui-HeaderBreadcrumbLink';
+    readonly breadcrumbLinkSmall: 'bui-HeaderBreadcrumbLinkSmall';
+    readonly breadcrumbSeparator: 'bui-HeaderBreadcrumbSeparator';
+    readonly titleStack: 'bui-HeaderTitleStack';
+    readonly title: 'bui-HeaderTitle';
+    readonly titleSmall: 'bui-HeaderTitleSmall';
     readonly tabsWrapper: 'bui-HeaderTabsWrapper';
     readonly controls: 'bui-HeaderControls';
     readonly tags: 'bui-HeaderTags';
@@ -1772,6 +1797,7 @@ export const HeaderPageDefinition: {
     readonly tags: {};
     readonly metadata: {};
     readonly className: {};
+    readonly sticky: {};
   };
 };
 
diff --git a/packages/ui/src/components/Header/Header.module.css b/packages/ui/src/components/Header/Header.module.css
index 08626268f7..0834767d2c 100644
--- a/packages/ui/src/components/Header/Header.module.css
+++ b/packages/ui/src/components/Header/Header.module.css
@@ -113,26 +113,93 @@
     flex-shrink: 0;
   }
 
-  .bui-HeaderBreadcrumbs {
+  .bui-HeaderTitleStack {
+    position: relative;
+    flex: 1 1 auto;
+    height: calc(var(--bui-font-size-6) * 1.4);
+    min-width: 0;
+    overflow: hidden;
+  }
+
+  .bui-HeaderBreadcrumbs,
+  .bui-HeaderBreadcrumbsSmall {
+    position: absolute;
+    inset-inline: 0;
+    top: 50%;
     display: flex;
     flex-direction: row;
     align-items: center;
     gap: var(--bui-space-2);
     min-width: 0;
+    transition: opacity 200ms ease, transform 200ms ease;
   }
 
-  .bui-HeaderTitle {
-    margin: 0;
-    padding: 0;
+  .bui-HeaderBreadcrumbs {
+    opacity: 1;
+    transform: translateY(-50%);
+  }
+
+  .bui-HeaderBreadcrumbsSmall {
+    gap: var(--bui-space-1);
+    opacity: 0;
+    transform: translateY(25%);
+  }
+
+  .bui-HeaderBreadcrumbs .bui-HeaderBreadcrumbLink,
+  .bui-HeaderBreadcrumbsSmall .bui-HeaderBreadcrumbLinkSmall {
+    max-width: 240px;
     overflow: hidden;
     font-family: var(--bui-font-regular);
-    font-size: var(--bui-font-size-6);
     font-weight: var(--bui-font-weight-bold);
     line-height: 140%;
     text-overflow: ellipsis;
     white-space: nowrap;
   }
 
+  .bui-HeaderBreadcrumbs .bui-HeaderBreadcrumbLink {
+    font-size: var(--bui-font-size-6);
+  }
+
+  .bui-HeaderBreadcrumbsSmall .bui-HeaderBreadcrumbLinkSmall {
+    font-size: var(--bui-font-size-4);
+  }
+
+  .bui-HeaderBreadcrumbSeparator {
+    flex-shrink: 0;
+  }
+
+  .bui-HeaderTitle,
+  .bui-HeaderTitleSmall {
+    margin: 0;
+    padding: 0;
+    flex: 1 1 auto;
+    min-width: 0;
+    font-family: var(--bui-font-regular);
+    font-weight: var(--bui-font-weight-bold);
+    line-height: 140%;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+
+  .bui-HeaderTitle {
+    font-size: var(--bui-font-size-6);
+  }
+
+  .bui-HeaderTitleSmall {
+    font-size: var(--bui-font-size-4);
+  }
+
+  .bui-HeaderContent[data-stuck] .bui-HeaderBreadcrumbs {
+    opacity: 0;
+    transform: translateY(-125%);
+  }
+
+  .bui-HeaderContent[data-stuck] .bui-HeaderBreadcrumbsSmall {
+    opacity: 1;
+    transform: translateY(-50%);
+  }
+
   .bui-HeaderTags {
     display: flex;
     flex-direction: row;
diff --git a/packages/ui/src/components/Header/Header.stories.tsx b/packages/ui/src/components/Header/Header.stories.tsx
index 09dadce9f4..b77a4c16c1 100644
--- a/packages/ui/src/components/Header/Header.stories.tsx
+++ b/packages/ui/src/components/Header/Header.stories.tsx
@@ -483,3 +483,38 @@ export const StickyWithLongTitle = meta.story({
     </>
   ),
 });
+
+export const StickyWithBreadcrumbsAndLongTitle = meta.story({
+  decorators: [withRouter],
+  render: () => (
+    <>
+      <Header
+        title="This is a very long page title that should demonstrate how sticky breadcrumbs and titles behave when both need to fit in the compact stuck state"
+        sticky
+        breadcrumbs={[
+          { label: 'Home', href: '/' },
+          { label: 'Very Long Breadcrumb Name', href: '/long-breadcrumb' },
+        ]}
+        description="This is a description of the page that scrolls away when you scroll down."
+        tags={[
+          { label: 'TypeScript' },
+          { label: 'Platform', href: '/platform' },
+        ]}
+        metadata={[
+          { label: 'Owner', value: 'platform-team' },
+          { label: 'Type', value: 'website' },
+        ]}
+        customActions={<Button>Custom action</Button>}
+      />
+      <Container pb="3">
+        {Array.from({ length: 60 }, (_, i) => (
+          <p key={i} style={{ marginBottom: '16px' }}>
+            Scroll down to see the breadcrumb and long title bar stick to the
+            top while the tags, description, and metadata scroll away. Line{' '}
+            {i + 1}.
+          </p>
+        ))}
+      </Container>
+    </>
+  ),
+});
diff --git a/packages/ui/src/components/Header/Header.tsx b/packages/ui/src/components/Header/Header.tsx
index ae992f4b41..1313555daa 100644
--- a/packages/ui/src/components/Header/Header.tsx
+++ b/packages/ui/src/components/Header/Header.tsx
@@ -158,25 +158,55 @@ export const Header = (props: HeaderProps) => {
         data-sticky={sticky || undefined}
         data-stuck={isStuck || undefined}
       >
-        <div className={classes.breadcrumbs}>
-          {breadcrumbs &&
-            breadcrumbs.map(breadcrumb => (
-              <Fragment key={breadcrumb.label}>
-                <Link
-                  href={breadcrumb.href}
-                  variant="title-small"
-                  weight="bold"
-                  color="secondary"
-                  truncate
-                  style={{ maxWidth: '240px' }}
-                  standalone
-                >
-                  {breadcrumb.label}
-                </Link>
-                <RiArrowRightSLine size={16} color="var(--bui-fg-secondary)" />
-              </Fragment>
-            ))}
-          <h2 className={classes.title}>{title}</h2>
+        <div className={classes.titleStack}>
+          <div
+            className={classes.breadcrumbs}
+            aria-hidden={isStuck || undefined}
+          >
+            {breadcrumbs &&
+              breadcrumbs.map(breadcrumb => (
+                <Fragment key={breadcrumb.label}>
+                  <Link
+                    href={isStuck ? undefined : breadcrumb.href}
+                    color="secondary"
+                    className={classes.breadcrumbLink}
+                    standalone
+                  >
+                    {breadcrumb.label}
+                  </Link>
+                  <RiArrowRightSLine
+                    className={classes.breadcrumbSeparator}
+                    size={16}
+                    color="var(--bui-fg-secondary)"
+                  />
+                </Fragment>
+              ))}
+            <h2 className={classes.title}>{title}</h2>
+          </div>
+          <div
+            className={classes.breadcrumbsSmall}
+            aria-hidden={!isStuck || undefined}
+          >
+            {breadcrumbs &&
+              breadcrumbs.map(breadcrumb => (
+                <Fragment key={breadcrumb.label}>
+                  <Link
+                    href={isStuck ? breadcrumb.href : undefined}
+                    color="secondary"
+                    className={classes.breadcrumbLinkSmall}
+                    standalone
+                  >
+                    {breadcrumb.label}
+                  </Link>
+                  <RiArrowRightSLine
+                    className={classes.breadcrumbSeparator}
+                    size={16}
+                    color="var(--bui-fg-secondary)"
+                  />
+                </Fragment>
+              ))}
+            <h2 className={classes.titleSmall}>{title}</h2>
+          </div>
         </div>
         <div className={classes.controls}>{customActions}</div>
       </div>
diff --git a/packages/ui/src/components/Header/definition.ts b/packages/ui/src/components/Header/definition.ts
index ace08f5195..4811871094 100644
--- a/packages/ui/src/components/Header/definition.ts
+++ b/packages/ui/src/components/Header/definition.ts
@@ -32,7 +32,13 @@ export const HeaderDefinition = defineComponent<HeaderOwnProps>()({
     content: 'bui-HeaderContent',
     afterSticky: 'bui-HeaderAfterSticky',
     breadcrumbs: 'bui-HeaderBreadcrumbs',
+    breadcrumbsSmall: 'bui-HeaderBreadcrumbsSmall',
+    breadcrumbLink: 'bui-HeaderBreadcrumbLink',
+    breadcrumbLinkSmall: 'bui-HeaderBreadcrumbLinkSmall',
+    breadcrumbSeparator: 'bui-HeaderBreadcrumbSeparator',
+    titleStack: 'bui-HeaderTitleStack',
     title: 'bui-HeaderTitle',
+    titleSmall: 'bui-HeaderTitleSmall',
     tabsWrapper: 'bui-HeaderTabsWrapper',
     controls: 'bui-HeaderControls',
     tags: 'bui-HeaderTags',

From dceca05fb49c22ace53b90d350f54d5dc32bad54 Mon Sep 17 00:00:00 2001
From: Charles de Dreuille <charles.dedreuille@gmail.com>
Date: Sun, 26 Apr 2026 14:16:09 +0100
Subject: [PATCH 03/15] Fix non-sticky Header title duplication

Signed-off-by: Charles de Dreuille <charles.dedreuille@gmail.com>
---
 packages/ui/src/components/Header/Header.tsx | 50 ++++++++++----------
 1 file changed, 26 insertions(+), 24 deletions(-)

diff --git a/packages/ui/src/components/Header/Header.tsx b/packages/ui/src/components/Header/Header.tsx
index 1313555daa..d46468799e 100644
--- a/packages/ui/src/components/Header/Header.tsx
+++ b/packages/ui/src/components/Header/Header.tsx
@@ -183,30 +183,32 @@ export const Header = (props: HeaderProps) => {
               ))}
             <h2 className={classes.title}>{title}</h2>
           </div>
-          <div
-            className={classes.breadcrumbsSmall}
-            aria-hidden={!isStuck || undefined}
-          >
-            {breadcrumbs &&
-              breadcrumbs.map(breadcrumb => (
-                <Fragment key={breadcrumb.label}>
-                  <Link
-                    href={isStuck ? breadcrumb.href : undefined}
-                    color="secondary"
-                    className={classes.breadcrumbLinkSmall}
-                    standalone
-                  >
-                    {breadcrumb.label}
-                  </Link>
-                  <RiArrowRightSLine
-                    className={classes.breadcrumbSeparator}
-                    size={16}
-                    color="var(--bui-fg-secondary)"
-                  />
-                </Fragment>
-              ))}
-            <h2 className={classes.titleSmall}>{title}</h2>
-          </div>
+          {sticky && (
+            <div
+              className={classes.breadcrumbsSmall}
+              aria-hidden={!isStuck || undefined}
+            >
+              {breadcrumbs &&
+                breadcrumbs.map(breadcrumb => (
+                  <Fragment key={breadcrumb.label}>
+                    <Link
+                      href={isStuck ? breadcrumb.href : undefined}
+                      color="secondary"
+                      className={classes.breadcrumbLinkSmall}
+                      standalone
+                    >
+                      {breadcrumb.label}
+                    </Link>
+                    <RiArrowRightSLine
+                      className={classes.breadcrumbSeparator}
+                      size={16}
+                      color="var(--bui-fg-secondary)"
+                    />
+                  </Fragment>
+                ))}
+              <h2 className={classes.titleSmall}>{title}</h2>
+            </div>
+          )}
         </div>
         <div className={classes.controls}>{customActions}</div>
       </div>

From 6c4606a71cfc19fdd00b60773680ec8a7df4b8fe Mon Sep 17 00:00:00 2001
From: Charles de Dreuille <charles.dedreuille@gmail.com>
Date: Sun, 26 Apr 2026 15:05:45 +0100
Subject: [PATCH 04/15] Polish sticky Header implementation

Signed-off-by: Charles de Dreuille <charles.dedreuille@gmail.com>
---
 .changeset/header-sticky-prop.md                    |  2 ++
 packages/ui/src/components/Header/Header.module.css | 12 +++++++-----
 packages/ui/src/components/Header/Header.tsx        |  8 ++++++--
 3 files changed, 15 insertions(+), 7 deletions(-)

diff --git a/.changeset/header-sticky-prop.md b/.changeset/header-sticky-prop.md
index 283c235d43..0e2722ed04 100644
--- a/.changeset/header-sticky-prop.md
+++ b/.changeset/header-sticky-prop.md
@@ -3,3 +3,5 @@
 ---
 
 Added a `sticky` prop to the `Header` component. When `true`, the title-and-actions bar stays fixed to the top of its scroll container while the rest of the header (tags, description, metadata) scrolls away. The sticky bar background color automatically matches the container surface using the bg-consumer system.
+
+**Affected components:** Header
diff --git a/packages/ui/src/components/Header/Header.module.css b/packages/ui/src/components/Header/Header.module.css
index 0834767d2c..0d6e9f7612 100644
--- a/packages/ui/src/components/Header/Header.module.css
+++ b/packages/ui/src/components/Header/Header.module.css
@@ -116,8 +116,10 @@
   .bui-HeaderTitleStack {
     position: relative;
     flex: 1 1 auto;
-    height: calc(var(--bui-font-size-6) * 1.4);
+    height: 1lh;
     min-width: 0;
+    font-size: var(--bui-font-size-6);
+    line-height: 140%;
     overflow: hidden;
   }
 
@@ -151,13 +153,13 @@
     overflow: hidden;
     font-family: var(--bui-font-regular);
     font-weight: var(--bui-font-weight-bold);
-    line-height: 140%;
+    line-height: inherit;
     text-overflow: ellipsis;
     white-space: nowrap;
   }
 
   .bui-HeaderBreadcrumbs .bui-HeaderBreadcrumbLink {
-    font-size: var(--bui-font-size-6);
+    font-size: inherit;
   }
 
   .bui-HeaderBreadcrumbsSmall .bui-HeaderBreadcrumbLinkSmall {
@@ -176,14 +178,14 @@
     min-width: 0;
     font-family: var(--bui-font-regular);
     font-weight: var(--bui-font-weight-bold);
-    line-height: 140%;
+    line-height: inherit;
     overflow: hidden;
     text-overflow: ellipsis;
     white-space: nowrap;
   }
 
   .bui-HeaderTitle {
-    font-size: var(--bui-font-size-6);
+    font-size: inherit;
   }
 
   .bui-HeaderTitleSmall {
diff --git a/packages/ui/src/components/Header/Header.tsx b/packages/ui/src/components/Header/Header.tsx
index d46468799e..ad70508250 100644
--- a/packages/ui/src/components/Header/Header.tsx
+++ b/packages/ui/src/components/Header/Header.tsx
@@ -29,9 +29,11 @@ const getScrollParent = (element: HTMLElement | null): Element | null => {
   let parent = element?.parentElement;
 
   while (parent) {
-    const { overflowY } = window.getComputedStyle(parent);
+    const { overflow, overflowX, overflowY } = window.getComputedStyle(parent);
 
-    if (/(auto|scroll|overlay)/.test(overflowY)) {
+    if (
+      /(auto|scroll|overlay|hidden)/.test(`${overflow}${overflowX}${overflowY}`)
+    ) {
       return parent;
     }
 
@@ -85,6 +87,8 @@ export const Header = (props: HeaderProps) => {
     () => (description ? renderInlineMarkdown(description) : null),
     [description],
   );
+  // The sentinel sits directly before the sticky content and leaves the
+  // viewport when the content becomes stuck, letting us toggle stuck styling.
   const stickySentinelRef = useRef<HTMLDivElement>(null);
   const [isStuck, setIsStuck] = useState(false);
 

From 6b05c0a4de6f8b5bbd54f968790afcd1f7fb123d Mon Sep 17 00:00:00 2001
From: Charles de Dreuille <charles.dedreuille@gmail.com>
Date: Sun, 26 Apr 2026 15:20:12 +0100
Subject: [PATCH 05/15] Address sticky Header review feedback

Signed-off-by: Charles de Dreuille <charles.dedreuille@gmail.com>
---
 packages/ui/report.api.md                     |  1 -
 .../src/components/Header/Header.stories.tsx  |  6 ++--
 packages/ui/src/components/Header/Header.tsx  | 32 ++++++++++++++++++-
 packages/ui/src/components/Header/types.ts    |  4 +++
 4 files changed, 38 insertions(+), 5 deletions(-)

diff --git a/packages/ui/report.api.md b/packages/ui/report.api.md
index d49a512536..85f59f178f 100644
--- a/packages/ui/report.api.md
+++ b/packages/ui/report.api.md
@@ -1743,7 +1743,6 @@ export interface HeaderOwnProps {
   description?: string;
   // (undocumented)
   metadata?: HeaderMetadataItem[];
-  // (undocumented)
   sticky?: boolean;
   // (undocumented)
   tabs?: HeaderNavTabItem[];
diff --git a/packages/ui/src/components/Header/Header.stories.tsx b/packages/ui/src/components/Header/Header.stories.tsx
index b77a4c16c1..9cc715e471 100644
--- a/packages/ui/src/components/Header/Header.stories.tsx
+++ b/packages/ui/src/components/Header/Header.stories.tsx
@@ -24,7 +24,7 @@ import { MemoryRouter } from 'react-router-dom';
 import { BUIProvider } from '../../provider';
 import { Button, ButtonIcon, MenuTrigger, Menu, MenuItem } from '../../';
 import { RiMore2Line } from '@remixicon/react';
-import { Container } from '../Container/Container';
+import { Container } from '../Container';
 
 const meta = preview.meta({
   title: 'Backstage UI/Header',
@@ -415,8 +415,8 @@ export const NonSticky = meta.story({
       <Container pb="3">
         {Array.from({ length: 60 }, (_, i) => (
           <p key={i} style={{ marginBottom: '16px' }}>
-            Scroll down to see the title bar stick to the top while the tags,
-            description, and metadata scroll away. Line {i + 1}.
+            Scroll down to see the entire header scroll away with the rest of
+            the page content. Line {i + 1}.
           </p>
         ))}
       </Container>
diff --git a/packages/ui/src/components/Header/Header.tsx b/packages/ui/src/components/Header/Header.tsx
index ad70508250..6e36d627f8 100644
--- a/packages/ui/src/components/Header/Header.tsx
+++ b/packages/ui/src/components/Header/Header.tsx
@@ -43,6 +43,16 @@ const getScrollParent = (element: HTMLElement | null): Element | null => {
   return null;
 };
 
+const isStickySentinelOutOfView = (
+  sentinel: HTMLElement,
+  root: Element | null,
+) => {
+  const sentinelRect = sentinel.getBoundingClientRect();
+  const rootTop = root ? root.getBoundingClientRect().top : 0;
+
+  return sentinelRect.bottom <= rootTop;
+};
+
 /**
  * Parses inline Markdown links in a string and returns an array of React nodes.
  * URLs are sanitized via `@braintree/sanitize-url`; unsafe URLs are rendered as
@@ -103,11 +113,31 @@ export const Header = (props: HeaderProps) => {
       return;
     }
 
+    const root = getScrollParent(sentinel);
+
+    if (typeof IntersectionObserver === 'undefined') {
+      const updateStuckState = () => {
+        setIsStuck(isStickySentinelOutOfView(sentinel, root));
+      };
+      const scrollTarget = root ?? window;
+
+      updateStuckState();
+      scrollTarget.addEventListener('scroll', updateStuckState, {
+        passive: true,
+      });
+      window.addEventListener('resize', updateStuckState);
+
+      return () => {
+        scrollTarget.removeEventListener('scroll', updateStuckState);
+        window.removeEventListener('resize', updateStuckState);
+      };
+    }
+
     const observer = new IntersectionObserver(
       ([entry]) => {
         setIsStuck(!entry.isIntersecting);
       },
-      { root: getScrollParent(sentinel), threshold: 0 },
+      { root, threshold: 0 },
     );
 
     observer.observe(sentinel);
diff --git a/packages/ui/src/components/Header/types.ts b/packages/ui/src/components/Header/types.ts
index d126f40ce3..77fbe937c3 100644
--- a/packages/ui/src/components/Header/types.ts
+++ b/packages/ui/src/components/Header/types.ts
@@ -116,6 +116,10 @@ export interface HeaderOwnProps {
   tags?: HeaderTag[];
   metadata?: HeaderMetadataItem[];
   className?: string;
+  /**
+   * Makes the title-and-actions row stick to the top of its nearest scroll
+   * container while the rest of the header content scrolls away.
+   */
   sticky?: boolean;
 }
 

From fc6f0d98e00ff44ba795aae827d671ba4a4ba8c5 Mon Sep 17 00:00:00 2001
From: Charles de Dreuille <charles.dedreuille@gmail.com>
Date: Sun, 26 Apr 2026 15:29:36 +0100
Subject: [PATCH 06/15] Remove display contents from sticky Header

Signed-off-by: Charles de Dreuille <charles.dedreuille@gmail.com>
---
 .../src/components/Header/Header.module.css   |  20 +-
 packages/ui/src/components/Header/Header.tsx  | 241 ++++++++++--------
 2 files changed, 137 insertions(+), 124 deletions(-)

diff --git a/packages/ui/src/components/Header/Header.module.css b/packages/ui/src/components/Header/Header.module.css
index 0d6e9f7612..d8d0119771 100644
--- a/packages/ui/src/components/Header/Header.module.css
+++ b/packages/ui/src/components/Header/Header.module.css
@@ -25,20 +25,16 @@
     padding-inline: var(--bui-space-5);
   }
 
-  .bui-Header[data-sticky] {
-    display: contents;
-  }
-
   .bui-HeaderAfterSticky {
     display: flex;
     flex-direction: column;
     gap: var(--bui-space-3);
   }
 
-  .bui-Header[data-sticky] .bui-HeaderBeforeSticky,
-  .bui-Header[data-sticky] .bui-HeaderStickySentinel,
-  .bui-Header[data-sticky] .bui-HeaderContent,
-  .bui-Header[data-sticky] .bui-HeaderAfterSticky {
+  .bui-HeaderBeforeSticky[data-sticky],
+  .bui-HeaderStickySentinel[data-sticky],
+  .bui-HeaderContent[data-sticky],
+  .bui-HeaderAfterSticky[data-sticky] {
     width: 100%;
     padding-inline: var(--bui-space-5);
     box-sizing: border-box;
@@ -48,7 +44,7 @@
     padding-top: var(--bui-space-4);
   }
 
-  .bui-Header[data-sticky] .bui-HeaderBeforeSticky {
+  .bui-HeaderBeforeSticky[data-sticky] {
     padding-top: var(--bui-space-6);
   }
 
@@ -72,15 +68,15 @@
     z-index: 10;
     background-color: var(--bui-bg-app);
 
-    .bui-Header[data-on-bg='neutral-1'] & {
+    &[data-on-bg='neutral-1'] {
       background-color: var(--bui-bg-neutral-1);
     }
 
-    .bui-Header[data-on-bg='neutral-2'] & {
+    &[data-on-bg='neutral-2'] {
       background-color: var(--bui-bg-neutral-2);
     }
 
-    .bui-Header[data-on-bg='neutral-3'] & {
+    &[data-on-bg='neutral-3'] {
       background-color: var(--bui-bg-neutral-3);
     }
   }
diff --git a/packages/ui/src/components/Header/Header.tsx b/packages/ui/src/components/Header/Header.tsx
index 6e36d627f8..ab64dd6e7d 100644
--- a/packages/ui/src/components/Header/Header.tsx
+++ b/packages/ui/src/components/Header/Header.tsx
@@ -79,7 +79,9 @@ function renderInlineMarkdown(text: string): React.ReactNode[] {
  * @public
  */
 export const Header = (props: HeaderProps) => {
-  const { ownProps, dataAttributes } = useDefinition(HeaderDefinition, props);
+  const { ownProps, dataAttributes } = useDefinition(HeaderDefinition, props, {
+    classNameTarget: props.sticky ? 'content' : 'root',
+  });
   const {
     classes,
     title,
@@ -147,63 +149,70 @@ export const Header = (props: HeaderProps) => {
     };
   }, [sticky]);
 
-  return (
-    <header
-      className={classes.root}
-      data-sticky={sticky || undefined}
-      {...dataAttributes}
-    >
-      {tags && tags.length > 0 && (
-        <div className={classes.beforeSticky}>
-          <ul className={classes.tags}>
-            {tags.map((tag, i) => (
-              <li
-                key={`${i}:${tag.label}:${tag.href ?? ''}`}
-                className={classes.tag}
+  const beforeStickyContent = tags && tags.length > 0 && (
+    <div className={classes.beforeSticky} data-sticky={sticky || undefined}>
+      <ul className={classes.tags}>
+        {tags.map((tag, i) => (
+          <li
+            key={`${i}:${tag.label}:${tag.href ?? ''}`}
+            className={classes.tag}
+          >
+            {tag.href ? (
+              <Link
+                href={tag.href}
+                variant="body-medium"
+                color="secondary"
+                standalone
               >
-                {tag.href ? (
-                  <Link
-                    href={tag.href}
-                    variant="body-medium"
-                    color="secondary"
-                    standalone
-                  >
-                    {tag.label}
-                  </Link>
-                ) : (
-                  <Text variant="body-medium" color="secondary">
-                    {tag.label}
-                  </Text>
-                )}
-              </li>
+                {tag.label}
+              </Link>
+            ) : (
+              <Text variant="body-medium" color="secondary">
+                {tag.label}
+              </Text>
+            )}
+          </li>
+        ))}
+      </ul>
+    </div>
+  );
+
+  const titleAndActionsContent = (
+    <>
+      <div className={classes.titleStack}>
+        <div className={classes.breadcrumbs} aria-hidden={isStuck || undefined}>
+          {breadcrumbs &&
+            breadcrumbs.map(breadcrumb => (
+              <Fragment key={breadcrumb.label}>
+                <Link
+                  href={isStuck ? undefined : breadcrumb.href}
+                  color="secondary"
+                  className={classes.breadcrumbLink}
+                  standalone
+                >
+                  {breadcrumb.label}
+                </Link>
+                <RiArrowRightSLine
+                  className={classes.breadcrumbSeparator}
+                  size={16}
+                  color="var(--bui-fg-secondary)"
+                />
+              </Fragment>
             ))}
-          </ul>
+          <h2 className={classes.title}>{title}</h2>
         </div>
-      )}
-      {sticky && (
-        <div
-          ref={stickySentinelRef}
-          className={classes.stickySentinel}
-          aria-hidden="true"
-        />
-      )}
-      <div
-        className={classes.content}
-        data-sticky={sticky || undefined}
-        data-stuck={isStuck || undefined}
-      >
-        <div className={classes.titleStack}>
+        {sticky && (
           <div
-            className={classes.breadcrumbs}
-            aria-hidden={isStuck || undefined}
+            className={classes.breadcrumbsSmall}
+            aria-hidden={!isStuck || undefined}
           >
             {breadcrumbs &&
               breadcrumbs.map(breadcrumb => (
                 <Fragment key={breadcrumb.label}>
                   <Link
-                    href={isStuck ? undefined : breadcrumb.href}
+                    href={isStuck ? breadcrumb.href : undefined}
                     color="secondary"
-                    className={classes.breadcrumbLink}
+                    className={classes.breadcrumbLinkSmall}
                     standalone
                   >
                     {breadcrumb.label}
@@ -215,75 +224,83 @@ export const Header = (props: HeaderProps) => {
                   />
                 </Fragment>
               ))}
-            <h2 className={classes.title}>{title}</h2>
+            <h2 className={classes.titleSmall}>{title}</h2>
           </div>
-          {sticky && (
-            <div
-              className={classes.breadcrumbsSmall}
-              aria-hidden={!isStuck || undefined}
-            >
-              {breadcrumbs &&
-                breadcrumbs.map(breadcrumb => (
-                  <Fragment key={breadcrumb.label}>
-                    <Link
-                      href={isStuck ? breadcrumb.href : undefined}
-                      color="secondary"
-                      className={classes.breadcrumbLinkSmall}
-                      standalone
-                    >
-                      {breadcrumb.label}
-                    </Link>
-                    <RiArrowRightSLine
-                      className={classes.breadcrumbSeparator}
-                      size={16}
-                      color="var(--bui-fg-secondary)"
-                    />
-                  </Fragment>
-                ))}
-              <h2 className={classes.titleSmall}>{title}</h2>
-            </div>
-          )}
-        </div>
-        <div className={classes.controls}>{customActions}</div>
+        )}
       </div>
-      {(description || (metadata && metadata.length > 0) || tabs) && (
-        <div className={classes.afterSticky}>
-          {description && (
-            <Text
-              variant="body-medium"
-              color="secondary"
-              className={classes.description}
-            >
-              {descriptionNodes}
-            </Text>
-          )}
-          {metadata && metadata.length > 0 && (
-            <dl className={classes.metaRow}>
-              {metadata.map((item, i) => (
-                <div key={`${i}:${item.label}`} className={classes.metaItem}>
-                  <dt>
-                    <Text variant="body-medium" color="secondary">
-                      {item.label}
-                    </Text>
-                  </dt>
-                  <dd>
-                    {typeof item.value === 'string' ? (
-                      <Text variant="body-medium">{item.value}</Text>
-                    ) : (
-                      item.value
-                    )}
-                  </dd>
-                </div>
-              ))}
-            </dl>
-          )}
-          {tabs && (
-            <div className={classes.tabsWrapper}>
-              <HeaderNav tabs={tabs} activeTabId={activeTabId} />
+      <div className={classes.controls}>{customActions}</div>
+    </>
+  );
+
+  const afterStickyContent = (description ||
+    (metadata && metadata.length > 0) ||
+    tabs) && (
+    <div className={classes.afterSticky} data-sticky={sticky || undefined}>
+      {description && (
+        <Text
+          variant="body-medium"
+          color="secondary"
+          className={classes.description}
+        >
+          {descriptionNodes}
+        </Text>
+      )}
+      {metadata && metadata.length > 0 && (
+        <dl className={classes.metaRow}>
+          {metadata.map((item, i) => (
+            <div key={`${i}:${item.label}`} className={classes.metaItem}>
+              <dt>
+                <Text variant="body-medium" color="secondary">
+                  {item.label}
+                </Text>
+              </dt>
+              <dd>
+                {typeof item.value === 'string' ? (
+                  <Text variant="body-medium">{item.value}</Text>
+                ) : (
+                  item.value
+                )}
+              </dd>
             </div>
-          )}
+          ))}
+        </dl>
+      )}
+      {tabs && (
+        <div className={classes.tabsWrapper}>
+          <HeaderNav tabs={tabs} activeTabId={activeTabId} />
         </div>
       )}
+    </div>
+  );
+
+  if (sticky) {
+    return (
+      <>
+        {beforeStickyContent}
+        <div
+          ref={stickySentinelRef}
+          className={classes.stickySentinel}
+          data-sticky=""
+          aria-hidden="true"
+        />
+        <header
+          className={classes.content}
+          data-sticky=""
+          data-stuck={isStuck || undefined}
+          {...dataAttributes}
+        >
+          {titleAndActionsContent}
+        </header>
+        {afterStickyContent}
+      </>
+    );
+  }
+
+  return (
+    <header className={classes.root} {...dataAttributes}>
+      {beforeStickyContent}
+      <div className={classes.content}>{titleAndActionsContent}</div>
+      {afterStickyContent}
     </header>
   );
 };

From aa56d03cd2e2782599a90cf398d44a2fce81a4b4 Mon Sep 17 00:00:00 2001
From: Charles de Dreuille <charles.dedreuille@gmail.com>
Date: Sun, 26 Apr 2026 15:43:41 +0100
Subject: [PATCH 07/15] Unify Header landmark structure

Signed-off-by: Charles de Dreuille <charles.dedreuille@gmail.com>
---
 .../src/components/Header/Header.module.css   | 18 ++-----
 packages/ui/src/components/Header/Header.tsx  | 47 +++++++++----------
 2 files changed, 27 insertions(+), 38 deletions(-)

diff --git a/packages/ui/src/components/Header/Header.module.css b/packages/ui/src/components/Header/Header.module.css
index d8d0119771..a885393c3f 100644
--- a/packages/ui/src/components/Header/Header.module.css
+++ b/packages/ui/src/components/Header/Header.module.css
@@ -17,24 +17,15 @@
 @layer tokens, base, components, utilities;
 
 @layer components {
-  .bui-Header {
-    display: flex;
-    flex-direction: column;
-    padding-top: var(--bui-space-2);
-    width: 100%;
-    padding-inline: var(--bui-space-5);
-  }
-
   .bui-HeaderAfterSticky {
     display: flex;
     flex-direction: column;
     gap: var(--bui-space-3);
   }
 
-  .bui-HeaderBeforeSticky[data-sticky],
-  .bui-HeaderStickySentinel[data-sticky],
-  .bui-HeaderContent[data-sticky],
-  .bui-HeaderAfterSticky[data-sticky] {
+  .bui-HeaderBeforeSticky,
+  .bui-HeaderContent,
+  .bui-HeaderAfterSticky {
     width: 100%;
     padding-inline: var(--bui-space-5);
     box-sizing: border-box;
@@ -59,7 +50,8 @@
     flex-direction: row;
     justify-content: space-between;
     gap: var(--bui-space-3);
-    padding-block: var(--bui-space-3);
+    padding-top: var(--bui-space-2);
+    padding-bottom: var(--bui-space-3);
   }
 
   .bui-HeaderContent[data-sticky] {
diff --git a/packages/ui/src/components/Header/Header.tsx b/packages/ui/src/components/Header/Header.tsx
index ab64dd6e7d..2d8c37c4f9 100644
--- a/packages/ui/src/components/Header/Header.tsx
+++ b/packages/ui/src/components/Header/Header.tsx
@@ -180,12 +180,16 @@ export const Header = (props: HeaderProps) => {
   const titleAndActionsContent = (
     <>
       <div className={classes.titleStack}>
-        <div className={classes.breadcrumbs} aria-hidden={isStuck || undefined}>
+        <div
+          className={classes.breadcrumbs}
+          aria-hidden={isStuck || undefined}
+          inert={isStuck ? '' : undefined}
+        >
           {breadcrumbs &&
             breadcrumbs.map(breadcrumb => (
               <Fragment key={breadcrumb.label}>
                 <Link
-                  href={isStuck ? undefined : breadcrumb.href}
+                  href={breadcrumb.href}
                   color="secondary"
                   className={classes.breadcrumbLink}
                   standalone
@@ -205,12 +209,13 @@ export const Header = (props: HeaderProps) => {
           <div
             className={classes.breadcrumbsSmall}
             aria-hidden={!isStuck || undefined}
+            inert={isStuck ? undefined : ''}
           >
             {breadcrumbs &&
               breadcrumbs.map(breadcrumb => (
                 <Fragment key={breadcrumb.label}>
                   <Link
-                    href={isStuck ? breadcrumb.href : undefined}
+                    href={breadcrumb.href}
                     color="secondary"
                     className={classes.breadcrumbLinkSmall}
                     standalone
@@ -273,35 +278,27 @@ export const Header = (props: HeaderProps) => {
     </div>
   );
 
-  if (sticky) {
-    return (
-      <>
-        {beforeStickyContent}
+  return (
+    <>
+      {beforeStickyContent}
+      {sticky && (
         <div
           ref={stickySentinelRef}
           className={classes.stickySentinel}
           data-sticky=""
           aria-hidden="true"
         />
-        <header
-          className={classes.content}
-          data-sticky=""
-          data-stuck={isStuck || undefined}
-          {...dataAttributes}
-        >
-          {titleAndActionsContent}
-        </header>
-        {afterStickyContent}
-      </>
-    );
-  }
-
-  return (
-    <header className={classes.root} {...dataAttributes}>
-      {beforeStickyContent}
-      <div className={classes.content}>{titleAndActionsContent}</div>
+      )}
+      <header
+        className={classes.content}
+        data-sticky={sticky || undefined}
+        data-stuck={isStuck || undefined}
+        {...dataAttributes}
+      >
+        {titleAndActionsContent}
+      </header>
       {afterStickyContent}
-    </header>
+    </>
   );
 };
 

From 68d1f91c916528a38625f3361fcaa6262cd9d884 Mon Sep 17 00:00:00 2001
From: Charles de Dreuille <charles.dedreuille@gmail.com>
Date: Sun, 26 Apr 2026 16:07:50 +0100
Subject: [PATCH 08/15] Avoid hidden duplicate Header links

Signed-off-by: Charles de Dreuille <charles.dedreuille@gmail.com>
---
 .../src/components/Header/Header.module.css   | 17 ------
 packages/ui/src/components/Header/Header.tsx  | 55 ++++++++-----------
 2 files changed, 24 insertions(+), 48 deletions(-)

diff --git a/packages/ui/src/components/Header/Header.module.css b/packages/ui/src/components/Header/Header.module.css
index a885393c3f..a0387952e3 100644
--- a/packages/ui/src/components/Header/Header.module.css
+++ b/packages/ui/src/components/Header/Header.module.css
@@ -121,18 +121,11 @@
     align-items: center;
     gap: var(--bui-space-2);
     min-width: 0;
-    transition: opacity 200ms ease, transform 200ms ease;
-  }
-
-  .bui-HeaderBreadcrumbs {
-    opacity: 1;
     transform: translateY(-50%);
   }
 
   .bui-HeaderBreadcrumbsSmall {
     gap: var(--bui-space-1);
-    opacity: 0;
-    transform: translateY(25%);
   }
 
   .bui-HeaderBreadcrumbs .bui-HeaderBreadcrumbLink,
@@ -180,16 +173,6 @@
     font-size: var(--bui-font-size-4);
   }
 
-  .bui-HeaderContent[data-stuck] .bui-HeaderBreadcrumbs {
-    opacity: 0;
-    transform: translateY(-125%);
-  }
-
-  .bui-HeaderContent[data-stuck] .bui-HeaderBreadcrumbsSmall {
-    opacity: 1;
-    transform: translateY(-50%);
-  }
-
   .bui-HeaderTags {
     display: flex;
     flex-direction: row;
diff --git a/packages/ui/src/components/Header/Header.tsx b/packages/ui/src/components/Header/Header.tsx
index 2d8c37c4f9..e076b66240 100644
--- a/packages/ui/src/components/Header/Header.tsx
+++ b/packages/ui/src/components/Header/Header.tsx
@@ -180,37 +180,8 @@ export const Header = (props: HeaderProps) => {
   const titleAndActionsContent = (
     <>
       <div className={classes.titleStack}>
-        <div
-          className={classes.breadcrumbs}
-          aria-hidden={isStuck || undefined}
-          inert={isStuck ? '' : undefined}
-        >
-          {breadcrumbs &&
-            breadcrumbs.map(breadcrumb => (
-              <Fragment key={breadcrumb.label}>
-                <Link
-                  href={breadcrumb.href}
-                  color="secondary"
-                  className={classes.breadcrumbLink}
-                  standalone
-                >
-                  {breadcrumb.label}
-                </Link>
-                <RiArrowRightSLine
-                  className={classes.breadcrumbSeparator}
-                  size={16}
-                  color="var(--bui-fg-secondary)"
-                />
-              </Fragment>
-            ))}
-          <h2 className={classes.title}>{title}</h2>
-        </div>
-        {sticky && (
-          <div
-            className={classes.breadcrumbsSmall}
-            aria-hidden={!isStuck || undefined}
-            inert={isStuck ? undefined : ''}
-          >
+        {isStuck ? (
+          <div className={classes.breadcrumbsSmall}>
             {breadcrumbs &&
               breadcrumbs.map(breadcrumb => (
                 <Fragment key={breadcrumb.label}>
@@ -231,6 +202,28 @@ export const Header = (props: HeaderProps) => {
               ))}
             <h2 className={classes.titleSmall}>{title}</h2>
           </div>
+        ) : (
+          <div className={classes.breadcrumbs}>
+            {breadcrumbs &&
+              breadcrumbs.map(breadcrumb => (
+                <Fragment key={breadcrumb.label}>
+                  <Link
+                    href={breadcrumb.href}
+                    color="secondary"
+                    className={classes.breadcrumbLink}
+                    standalone
+                  >
+                    {breadcrumb.label}
+                  </Link>
+                  <RiArrowRightSLine
+                    className={classes.breadcrumbSeparator}
+                    size={16}
+                    color="var(--bui-fg-secondary)"
+                  />
+                </Fragment>
+              ))}
+            <h2 className={classes.title}>{title}</h2>
+          </div>
         )}
       </div>
       <div className={classes.controls}>{customActions}</div>

From 0e71545ee68a847107d76202515b0028988b3e25 Mon Sep 17 00:00:00 2001
From: Charles de Dreuille <charles.dedreuille@gmail.com>
Date: Sun, 26 Apr 2026 17:36:18 +0100
Subject: [PATCH 09/15] Preserve Header className target

Signed-off-by: Charles de Dreuille <charles.dedreuille@gmail.com>
---
 packages/ui/src/components/Header/Header.tsx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/ui/src/components/Header/Header.tsx b/packages/ui/src/components/Header/Header.tsx
index e076b66240..ca1d43c776 100644
--- a/packages/ui/src/components/Header/Header.tsx
+++ b/packages/ui/src/components/Header/Header.tsx
@@ -80,7 +80,7 @@ function renderInlineMarkdown(text: string): React.ReactNode[] {
  */
 export const Header = (props: HeaderProps) => {
   const { ownProps, dataAttributes } = useDefinition(HeaderDefinition, props, {
-    classNameTarget: props.sticky ? 'content' : 'root',
+    classNameTarget: 'content',
   });
   const {
     classes,

From 8a0a5c955306c0316b56bd6d8cde35e59de9a808 Mon Sep 17 00:00:00 2001
From: Charles de Dreuille <charles.dedreuille@gmail.com>
Date: Sun, 26 Apr 2026 20:36:24 +0100
Subject: [PATCH 10/15] feat(ui): improve Header layout with tag-aware padding
 and renamed sections

- Add data-has-tags attribute to reduce header padding-top when tags are present
- Rename beforeSticky/afterSticky classes to headerTop/headerBottom
- Always render headerBottom for consistent bottom margin
- Inline JSX sections into a single return statement

Signed-off-by: Charles de Dreuille <charles.dedreuille@gmail.com>
---
 .storybook/themes/spotify.css                 |   7 +-
 packages/ui/report.api.md                     |   8 +-
 .../src/components/Header/Header.module.css   |  17 +-
 packages/ui/src/components/Header/Header.tsx  | 242 +++++++++---------
 .../ui/src/components/Header/definition.ts    |   4 +-
 .../recipes/PluginHeaderAndHeader.stories.tsx | 108 ++++----
 6 files changed, 193 insertions(+), 193 deletions(-)

diff --git a/.storybook/themes/spotify.css b/.storybook/themes/spotify.css
index d8f06c68c0..6478bf1112 100644
--- a/.storybook/themes/spotify.css
+++ b/.storybook/themes/spotify.css
@@ -246,17 +246,16 @@
  */
 [data-theme-name='spotify'] {
   .bui-PluginHeaderToolbar {
-    padding: 0;
     height: 32px;
     border: none;
     background: none;
-    margin-bottom: var(--bui-space-2);
+    margin-top: var(--bui-space-4);
   }
 
   .bui-PluginHeaderTabsWrapper {
-    padding: 0;
     border: none;
     background: none;
-    margin-left: -8px;
+    margin-left: 0;
+    margin-top: var(--bui-space-2);
   }
 }
diff --git a/packages/ui/report.api.md b/packages/ui/report.api.md
index 85f59f178f..7b4cc74ee1 100644
--- a/packages/ui/report.api.md
+++ b/packages/ui/report.api.md
@@ -1582,10 +1582,10 @@ export const HeaderDefinition: {
   readonly bg: 'consumer';
   readonly classNames: {
     readonly root: 'bui-Header';
-    readonly beforeSticky: 'bui-HeaderBeforeSticky';
+    readonly headerTop: 'bui-HeaderTop';
     readonly stickySentinel: 'bui-HeaderStickySentinel';
     readonly content: 'bui-HeaderContent';
-    readonly afterSticky: 'bui-HeaderAfterSticky';
+    readonly headerBottom: 'bui-HeaderBottom';
     readonly breadcrumbs: 'bui-HeaderBreadcrumbs';
     readonly breadcrumbsSmall: 'bui-HeaderBreadcrumbsSmall';
     readonly breadcrumbLink: 'bui-HeaderBreadcrumbLink';
@@ -1766,10 +1766,10 @@ export const HeaderPageDefinition: {
   readonly bg: 'consumer';
   readonly classNames: {
     readonly root: 'bui-Header';
-    readonly beforeSticky: 'bui-HeaderBeforeSticky';
+    readonly headerTop: 'bui-HeaderTop';
     readonly stickySentinel: 'bui-HeaderStickySentinel';
     readonly content: 'bui-HeaderContent';
-    readonly afterSticky: 'bui-HeaderAfterSticky';
+    readonly headerBottom: 'bui-HeaderBottom';
     readonly breadcrumbs: 'bui-HeaderBreadcrumbs';
     readonly breadcrumbsSmall: 'bui-HeaderBreadcrumbsSmall';
     readonly breadcrumbLink: 'bui-HeaderBreadcrumbLink';
diff --git a/packages/ui/src/components/Header/Header.module.css b/packages/ui/src/components/Header/Header.module.css
index a0387952e3..c248a5e925 100644
--- a/packages/ui/src/components/Header/Header.module.css
+++ b/packages/ui/src/components/Header/Header.module.css
@@ -17,25 +17,26 @@
 @layer tokens, base, components, utilities;
 
 @layer components {
-  .bui-HeaderAfterSticky {
+  .bui-HeaderBottom {
     display: flex;
     flex-direction: column;
     gap: var(--bui-space-3);
+    margin-bottom: var(--bui-space-5);
   }
 
-  .bui-HeaderBeforeSticky,
+  .bui-HeaderTop,
   .bui-HeaderContent,
-  .bui-HeaderAfterSticky {
+  .bui-HeaderBottom {
     width: 100%;
     padding-inline: var(--bui-space-5);
     box-sizing: border-box;
   }
 
-  .bui-HeaderBeforeSticky {
+  .bui-HeaderTop {
     padding-top: var(--bui-space-4);
   }
 
-  .bui-HeaderBeforeSticky[data-sticky] {
+  .bui-HeaderTop[data-sticky] {
     padding-top: var(--bui-space-6);
   }
 
@@ -50,10 +51,14 @@
     flex-direction: row;
     justify-content: space-between;
     gap: var(--bui-space-3);
-    padding-top: var(--bui-space-2);
+    padding-top: var(--bui-space-6);
     padding-bottom: var(--bui-space-3);
   }
 
+  .bui-HeaderContent[data-has-tags] {
+    padding-top: var(--bui-space-2);
+  }
+
   .bui-HeaderContent[data-sticky] {
     position: sticky;
     top: 0;
diff --git a/packages/ui/src/components/Header/Header.tsx b/packages/ui/src/components/Header/Header.tsx
index ca1d43c776..56f43157a3 100644
--- a/packages/ui/src/components/Header/Header.tsx
+++ b/packages/ui/src/components/Header/Header.tsx
@@ -99,6 +99,7 @@ export const Header = (props: HeaderProps) => {
     () => (description ? renderInlineMarkdown(description) : null),
     [description],
   );
+
   // The sentinel sits directly before the sticky content and leaves the
   // viewport when the content becomes stuck, letting us toggle stuck styling.
   const stickySentinelRef = useRef<HTMLDivElement>(null);
@@ -149,131 +150,35 @@ export const Header = (props: HeaderProps) => {
     };
   }, [sticky]);
 
-  const beforeStickyContent = tags && tags.length > 0 && (
-    <div className={classes.beforeSticky} data-sticky={sticky || undefined}>
-      <ul className={classes.tags}>
-        {tags.map((tag, i) => (
-          <li
-            key={`${i}:${tag.label}:${tag.href ?? ''}`}
-            className={classes.tag}
-          >
-            {tag.href ? (
-              <Link
-                href={tag.href}
-                variant="body-medium"
-                color="secondary"
-                standalone
-              >
-                {tag.label}
-              </Link>
-            ) : (
-              <Text variant="body-medium" color="secondary">
-                {tag.label}
-              </Text>
-            )}
-          </li>
-        ))}
-      </ul>
-    </div>
-  );
-
-  const titleAndActionsContent = (
-    <>
-      <div className={classes.titleStack}>
-        {isStuck ? (
-          <div className={classes.breadcrumbsSmall}>
-            {breadcrumbs &&
-              breadcrumbs.map(breadcrumb => (
-                <Fragment key={breadcrumb.label}>
-                  <Link
-                    href={breadcrumb.href}
-                    color="secondary"
-                    className={classes.breadcrumbLinkSmall}
-                    standalone
-                  >
-                    {breadcrumb.label}
-                  </Link>
-                  <RiArrowRightSLine
-                    className={classes.breadcrumbSeparator}
-                    size={16}
-                    color="var(--bui-fg-secondary)"
-                  />
-                </Fragment>
-              ))}
-            <h2 className={classes.titleSmall}>{title}</h2>
-          </div>
-        ) : (
-          <div className={classes.breadcrumbs}>
-            {breadcrumbs &&
-              breadcrumbs.map(breadcrumb => (
-                <Fragment key={breadcrumb.label}>
-                  <Link
-                    href={breadcrumb.href}
-                    color="secondary"
-                    className={classes.breadcrumbLink}
-                    standalone
-                  >
-                    {breadcrumb.label}
-                  </Link>
-                  <RiArrowRightSLine
-                    className={classes.breadcrumbSeparator}
-                    size={16}
-                    color="var(--bui-fg-secondary)"
-                  />
-                </Fragment>
-              ))}
-            <h2 className={classes.title}>{title}</h2>
-          </div>
-        )}
-      </div>
-      <div className={classes.controls}>{customActions}</div>
-    </>
-  );
-
-  const afterStickyContent = (description ||
-    (metadata && metadata.length > 0) ||
-    tabs) && (
-    <div className={classes.afterSticky} data-sticky={sticky || undefined}>
-      {description && (
-        <Text
-          variant="body-medium"
-          color="secondary"
-          className={classes.description}
-        >
-          {descriptionNodes}
-        </Text>
-      )}
-      {metadata && metadata.length > 0 && (
-        <dl className={classes.metaRow}>
-          {metadata.map((item, i) => (
-            <div key={`${i}:${item.label}`} className={classes.metaItem}>
-              <dt>
-                <Text variant="body-medium" color="secondary">
-                  {item.label}
-                </Text>
-              </dt>
-              <dd>
-                {typeof item.value === 'string' ? (
-                  <Text variant="body-medium">{item.value}</Text>
-                ) : (
-                  item.value
-                )}
-              </dd>
-            </div>
-          ))}
-        </dl>
-      )}
-      {tabs && (
-        <div className={classes.tabsWrapper}>
-          <HeaderNav tabs={tabs} activeTabId={activeTabId} />
-        </div>
-      )}
-    </div>
-  );
-
   return (
     <>
-      {beforeStickyContent}
+      {tags && tags.length > 0 && (
+        <div className={classes.headerTop} data-sticky={sticky || undefined}>
+          <ul className={classes.tags}>
+            {tags.map((tag, i) => (
+              <li
+                key={`${i}:${tag.label}:${tag.href ?? ''}`}
+                className={classes.tag}
+              >
+                {tag.href ? (
+                  <Link
+                    href={tag.href}
+                    variant="body-medium"
+                    color="secondary"
+                    standalone
+                  >
+                    {tag.label}
+                  </Link>
+                ) : (
+                  <Text variant="body-medium" color="secondary">
+                    {tag.label}
+                  </Text>
+                )}
+              </li>
+            ))}
+          </ul>
+        </div>
+      )}
       {sticky && (
         <div
           ref={stickySentinelRef}
@@ -282,15 +187,98 @@ export const Header = (props: HeaderProps) => {
           aria-hidden="true"
         />
       )}
-      <header
+      <div
         className={classes.content}
         data-sticky={sticky || undefined}
         data-stuck={isStuck || undefined}
+        data-has-tags={tags && tags.length > 0 ? '' : undefined}
         {...dataAttributes}
       >
-        {titleAndActionsContent}
-      </header>
-      {afterStickyContent}
+        <div className={classes.titleStack}>
+          {isStuck ? (
+            <div className={classes.breadcrumbsSmall}>
+              {breadcrumbs &&
+                breadcrumbs.map(breadcrumb => (
+                  <Fragment key={breadcrumb.label}>
+                    <Link
+                      href={breadcrumb.href}
+                      color="secondary"
+                      className={classes.breadcrumbLinkSmall}
+                      standalone
+                    >
+                      {breadcrumb.label}
+                    </Link>
+                    <RiArrowRightSLine
+                      className={classes.breadcrumbSeparator}
+                      size={16}
+                      color="var(--bui-fg-secondary)"
+                    />
+                  </Fragment>
+                ))}
+              <h2 className={classes.titleSmall}>{title}</h2>
+            </div>
+          ) : (
+            <div className={classes.breadcrumbs}>
+              {breadcrumbs &&
+                breadcrumbs.map(breadcrumb => (
+                  <Fragment key={breadcrumb.label}>
+                    <Link
+                      href={breadcrumb.href}
+                      color="secondary"
+                      className={classes.breadcrumbLink}
+                      standalone
+                    >
+                      {breadcrumb.label}
+                    </Link>
+                    <RiArrowRightSLine
+                      className={classes.breadcrumbSeparator}
+                      size={16}
+                      color="var(--bui-fg-secondary)"
+                    />
+                  </Fragment>
+                ))}
+              <h2 className={classes.title}>{title}</h2>
+            </div>
+          )}
+        </div>
+        <div className={classes.controls}>{customActions}</div>
+      </div>
+      <div className={classes.headerBottom} data-sticky={sticky || undefined}>
+        {description && (
+          <Text
+            variant="body-medium"
+            color="secondary"
+            className={classes.description}
+          >
+            {descriptionNodes}
+          </Text>
+        )}
+        {metadata && metadata.length > 0 && (
+          <dl className={classes.metaRow}>
+            {metadata.map((item, i) => (
+              <div key={`${i}:${item.label}`} className={classes.metaItem}>
+                <dt>
+                  <Text variant="body-medium" color="secondary">
+                    {item.label}
+                  </Text>
+                </dt>
+                <dd>
+                  {typeof item.value === 'string' ? (
+                    <Text variant="body-medium">{item.value}</Text>
+                  ) : (
+                    item.value
+                  )}
+                </dd>
+              </div>
+            ))}
+          </dl>
+        )}
+        {tabs && (
+          <div className={classes.tabsWrapper}>
+            <HeaderNav tabs={tabs} activeTabId={activeTabId} />
+          </div>
+        )}
+      </div>
     </>
   );
 };
diff --git a/packages/ui/src/components/Header/definition.ts b/packages/ui/src/components/Header/definition.ts
index 4811871094..010f641391 100644
--- a/packages/ui/src/components/Header/definition.ts
+++ b/packages/ui/src/components/Header/definition.ts
@@ -27,10 +27,10 @@ export const HeaderDefinition = defineComponent<HeaderOwnProps>()({
   bg: 'consumer',
   classNames: {
     root: 'bui-Header',
-    beforeSticky: 'bui-HeaderBeforeSticky',
+    headerTop: 'bui-HeaderTop',
     stickySentinel: 'bui-HeaderStickySentinel',
     content: 'bui-HeaderContent',
-    afterSticky: 'bui-HeaderAfterSticky',
+    headerBottom: 'bui-HeaderBottom',
     breadcrumbs: 'bui-HeaderBreadcrumbs',
     breadcrumbsSmall: 'bui-HeaderBreadcrumbsSmall',
     breadcrumbLink: 'bui-HeaderBreadcrumbLink',
diff --git a/packages/ui/src/recipes/PluginHeaderAndHeader.stories.tsx b/packages/ui/src/recipes/PluginHeaderAndHeader.stories.tsx
index a43252a9b7..623a4cf7b9 100644
--- a/packages/ui/src/recipes/PluginHeaderAndHeader.stories.tsx
+++ b/packages/ui/src/recipes/PluginHeaderAndHeader.stories.tsx
@@ -157,52 +157,6 @@ export const WithTabs = meta.story({
   ),
 });
 
-export const WithBreadcrumb = meta.story({
-  decorators: [withLayout],
-  render: () => (
-    <>
-      <PluginHeader
-        icon={<RiGitBranchLine />}
-        title="CI/CD"
-        titleLink="/"
-        tabs={[
-          { id: 'builds', label: 'Builds', href: '/builds' },
-          { id: 'pipelines', label: 'Pipelines', href: '/pipelines' },
-          { id: 'deployments', label: 'Deployments', href: '/deployments' },
-          { id: 'settings', label: 'Settings', href: '/settings' },
-        ]}
-        customActions={
-          <>
-            <ButtonIcon
-              variant="secondary"
-              icon={<RiRefreshLine />}
-              aria-label="Refresh"
-            />
-          </>
-        }
-      />
-      <Header
-        title="main · #842"
-        breadcrumbs={[
-          { label: 'Catalog', href: '/catalog' },
-          { label: 'Services', href: '/catalog?kind=Component' },
-        ]}
-        customActions={
-          <>
-            <Button variant="secondary" iconStart={<RiDownloadLine />}>
-              Download logs
-            </Button>
-            <Button variant="primary" iconStart={<RiPlayLine />}>
-              Re-run pipeline
-            </Button>
-          </>
-        }
-      />
-      <PageContent />
-    </>
-  ),
-});
-
 const subTabs: HeaderNavTabItem[] = [
   { id: 'summary', label: 'Summary', href: '/summary' },
   { id: 'steps', label: 'Steps', href: '/steps' },
@@ -244,11 +198,65 @@ export const WithSubTabs = meta.story({
           }
         />
         <Header
-          title="main · #842"
+          title="Production deployment pipeline run"
           tabs={subTabs}
-          breadcrumbs={[
-            { label: 'Catalog', href: '/catalog' },
-            { label: 'Services', href: '/catalog?kind=Component' },
+          customActions={
+            <>
+              <Button variant="secondary" iconStart={<RiDownloadLine />}>
+                Download logs
+              </Button>
+              <Button variant="primary" iconStart={<RiPlayLine />}>
+                Re-run pipeline
+              </Button>
+            </>
+          }
+        />
+        <PageContent />
+      </>
+    );
+  },
+});
+
+export const WithSubTabsAndTags = meta.story({
+  decorators: [
+    (Story: StoryFn) => (
+      <MemoryRouter initialEntries={['/summary']}>
+        <BUIProvider>
+          <Story />
+        </BUIProvider>
+      </MemoryRouter>
+    ),
+  ],
+  render: () => {
+    return (
+      <>
+        <PluginHeader
+          icon={<RiGitBranchLine />}
+          title="CI/CD"
+          titleLink="/"
+          tabs={[
+            { id: 'builds', label: 'Builds', href: '/builds' },
+            { id: 'pipelines', label: 'Pipelines', href: '/pipelines' },
+            { id: 'deployments', label: 'Deployments', href: '/deployments' },
+            { id: 'settings', label: 'Settings', href: '/settings' },
+          ]}
+          customActions={
+            <>
+              <ButtonIcon
+                variant="secondary"
+                icon={<RiRefreshLine />}
+                aria-label="Refresh"
+              />
+            </>
+          }
+        />
+        <Header
+          title="Production deployment pipeline run"
+          tabs={subTabs}
+          tags={[
+            { label: 'Production' },
+            { label: 'Owner: Platform', href: '/catalog?owner=platform' },
+            { label: 'Tier 1' },
           ]}
           customActions={
             <>

From 84f151c5eeed9ee241c5d22af798b99acad493dd Mon Sep 17 00:00:00 2001
From: Charles de Dreuille <charles.dedreuille@gmail.com>
Date: Sun, 26 Apr 2026 20:52:54 +0100
Subject: [PATCH 11/15] fix(ui): simplify HeaderTop padding-top to always use
 space-6

Signed-off-by: Charles de Dreuille <charles.dedreuille@gmail.com>
---
 packages/ui/src/components/Header/Header.module.css | 4 ----
 1 file changed, 4 deletions(-)

diff --git a/packages/ui/src/components/Header/Header.module.css b/packages/ui/src/components/Header/Header.module.css
index c248a5e925..dbdcb9c776 100644
--- a/packages/ui/src/components/Header/Header.module.css
+++ b/packages/ui/src/components/Header/Header.module.css
@@ -33,10 +33,6 @@
   }
 
   .bui-HeaderTop {
-    padding-top: var(--bui-space-4);
-  }
-
-  .bui-HeaderTop[data-sticky] {
     padding-top: var(--bui-space-6);
   }
 

From 7b0c998feac8e64a5a0e9c678568d00d28260ac7 Mon Sep 17 00:00:00 2001
From: Charles de Dreuille <charles.dedreuille@gmail.com>
Date: Sun, 26 Apr 2026 20:57:57 +0100
Subject: [PATCH 12/15] fix(ui): remove unused root class name from
 HeaderDefinition

Signed-off-by: Charles de Dreuille <charles.dedreuille@gmail.com>
---
 packages/ui/src/components/Header/definition.ts | 1 -
 1 file changed, 1 deletion(-)

diff --git a/packages/ui/src/components/Header/definition.ts b/packages/ui/src/components/Header/definition.ts
index 010f641391..8fd12cc97b 100644
--- a/packages/ui/src/components/Header/definition.ts
+++ b/packages/ui/src/components/Header/definition.ts
@@ -26,7 +26,6 @@ export const HeaderDefinition = defineComponent<HeaderOwnProps>()({
   styles,
   bg: 'consumer',
   classNames: {
-    root: 'bui-Header',
     headerTop: 'bui-HeaderTop',
     stickySentinel: 'bui-HeaderStickySentinel',
     content: 'bui-HeaderContent',

From ec93dd281aeff04df6d11bd769c171cd29a9eed7 Mon Sep 17 00:00:00 2001
From: Charles de Dreuille <charles.dedreuille@gmail.com>
Date: Sun, 26 Apr 2026 21:15:42 +0100
Subject: [PATCH 13/15] fix(ui): always render headerTop, adjust content
 padding, add story

- Always render headerTop wrapper for consistent spacing
- Reduce default content padding-top from space-6 to space-3
- Add PluginHeaderAndHeader story and update Spotify theme

Signed-off-by: Charles de Dreuille <charles.dedreuille@gmail.com>
---
 .storybook/themes/spotify.css                 |  4 ++
 packages/ui/report.api.md                     |  2 -
 .../src/components/Header/Header.module.css   |  2 +-
 packages/ui/src/components/Header/Header.tsx  |  8 +--
 .../recipes/PluginHeaderAndHeader.stories.tsx | 67 +++++++++++++++++++
 5 files changed, 76 insertions(+), 7 deletions(-)

diff --git a/.storybook/themes/spotify.css b/.storybook/themes/spotify.css
index 6478bf1112..f91eb62e02 100644
--- a/.storybook/themes/spotify.css
+++ b/.storybook/themes/spotify.css
@@ -258,4 +258,8 @@
     margin-left: 0;
     margin-top: var(--bui-space-2);
   }
+
+  .bui-HeaderTop {
+    padding-top: var(--bui-space-4);
+  }
 }
diff --git a/packages/ui/report.api.md b/packages/ui/report.api.md
index 7b4cc74ee1..c90408ef23 100644
--- a/packages/ui/report.api.md
+++ b/packages/ui/report.api.md
@@ -1581,7 +1581,6 @@ export const HeaderDefinition: {
   };
   readonly bg: 'consumer';
   readonly classNames: {
-    readonly root: 'bui-Header';
     readonly headerTop: 'bui-HeaderTop';
     readonly stickySentinel: 'bui-HeaderStickySentinel';
     readonly content: 'bui-HeaderContent';
@@ -1765,7 +1764,6 @@ export const HeaderPageDefinition: {
   };
   readonly bg: 'consumer';
   readonly classNames: {
-    readonly root: 'bui-Header';
     readonly headerTop: 'bui-HeaderTop';
     readonly stickySentinel: 'bui-HeaderStickySentinel';
     readonly content: 'bui-HeaderContent';
diff --git a/packages/ui/src/components/Header/Header.module.css b/packages/ui/src/components/Header/Header.module.css
index dbdcb9c776..58bcf2699d 100644
--- a/packages/ui/src/components/Header/Header.module.css
+++ b/packages/ui/src/components/Header/Header.module.css
@@ -47,7 +47,7 @@
     flex-direction: row;
     justify-content: space-between;
     gap: var(--bui-space-3);
-    padding-top: var(--bui-space-6);
+    padding-top: var(--bui-space-3);
     padding-bottom: var(--bui-space-3);
   }
 
diff --git a/packages/ui/src/components/Header/Header.tsx b/packages/ui/src/components/Header/Header.tsx
index 56f43157a3..cb83dead13 100644
--- a/packages/ui/src/components/Header/Header.tsx
+++ b/packages/ui/src/components/Header/Header.tsx
@@ -152,8 +152,8 @@ export const Header = (props: HeaderProps) => {
 
   return (
     <>
-      {tags && tags.length > 0 && (
-        <div className={classes.headerTop} data-sticky={sticky || undefined}>
+      <div className={classes.headerTop} data-sticky={sticky || undefined}>
+        {tags && tags.length > 0 && (
           <ul className={classes.tags}>
             {tags.map((tag, i) => (
               <li
@@ -177,8 +177,8 @@ export const Header = (props: HeaderProps) => {
               </li>
             ))}
           </ul>
-        </div>
-      )}
+        )}
+      </div>
       {sticky && (
         <div
           ref={stickySentinelRef}
diff --git a/packages/ui/src/recipes/PluginHeaderAndHeader.stories.tsx b/packages/ui/src/recipes/PluginHeaderAndHeader.stories.tsx
index 623a4cf7b9..4f74572ef5 100644
--- a/packages/ui/src/recipes/PluginHeaderAndHeader.stories.tsx
+++ b/packages/ui/src/recipes/PluginHeaderAndHeader.stories.tsx
@@ -58,6 +58,19 @@ const PageContent = () => (
   </Container>
 );
 
+const LongPageContent = () => (
+  <Container mt="6" pb="3">
+    <Flex direction="row" gap="4" mb="4">
+      <Card style={{ minHeight: 200, flex: 1 }} />
+      <Card style={{ minHeight: 200, flex: 1 }} />
+      <Card style={{ minHeight: 200, flex: 1 }} />
+    </Flex>
+    {Array.from({ length: 40 }, (_, i) => (
+      <Card key={i} style={{ minHeight: 200, marginBottom: 16 }} />
+    ))}
+  </Container>
+);
+
 // ---------------------------------------------------------------------------
 // Shared layout decorator
 // ---------------------------------------------------------------------------
@@ -274,3 +287,57 @@ export const WithSubTabsAndTags = meta.story({
     );
   },
 });
+
+export const WithStickyHeader = meta.story({
+  decorators: [
+    (Story: StoryFn) => (
+      <MemoryRouter initialEntries={['/summary']}>
+        <BUIProvider>
+          <Story />
+        </BUIProvider>
+      </MemoryRouter>
+    ),
+  ],
+  render: () => {
+    return (
+      <>
+        <PluginHeader
+          icon={<RiGitBranchLine />}
+          title="CI/CD"
+          titleLink="/"
+          tabs={[
+            { id: 'builds', label: 'Builds', href: '/builds' },
+            { id: 'pipelines', label: 'Pipelines', href: '/pipelines' },
+            { id: 'deployments', label: 'Deployments', href: '/deployments' },
+            { id: 'settings', label: 'Settings', href: '/settings' },
+          ]}
+          customActions={
+            <>
+              <ButtonIcon
+                variant="secondary"
+                icon={<RiRefreshLine />}
+                aria-label="Refresh"
+              />
+            </>
+          }
+        />
+        <Header
+          title="Production deployment pipeline run"
+          sticky
+          tabs={subTabs}
+          customActions={
+            <>
+              <Button variant="secondary" iconStart={<RiDownloadLine />}>
+                Download logs
+              </Button>
+              <Button variant="primary" iconStart={<RiPlayLine />}>
+                Re-run pipeline
+              </Button>
+            </>
+          }
+        />
+        <LongPageContent />
+      </>
+    );
+  },
+});

From 5efddbdbca1aac0ac020d3f0b6bf7003d4d581f2 Mon Sep 17 00:00:00 2001
From: Charles de Dreuille <charles.dedreuille@gmail.com>
Date: Mon, 27 Apr 2026 11:30:04 +0100
Subject: [PATCH 14/15] chore(ui): bump header sticky changeset to minor

Signed-off-by: Charles de Dreuille <charles.dedreuille@gmail.com>
---
 .changeset/header-sticky-prop.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.changeset/header-sticky-prop.md b/.changeset/header-sticky-prop.md
index 0e2722ed04..b376bb04da 100644
--- a/.changeset/header-sticky-prop.md
+++ b/.changeset/header-sticky-prop.md
@@ -1,5 +1,5 @@
 ---
-'@backstage/ui': patch
+'@backstage/ui': minor
 ---
 
 Added a `sticky` prop to the `Header` component. When `true`, the title-and-actions bar stays fixed to the top of its scroll container while the rest of the header (tags, description, metadata) scrolls away. The sticky bar background color automatically matches the container surface using the bg-consumer system.

From db5956a2a0c9e5adc309e78c0437788f333dde5d Mon Sep 17 00:00:00 2001
From: Charles de Dreuille <charles.dedreuille@gmail.com>
Date: Mon, 27 Apr 2026 13:41:12 +0100
Subject: [PATCH 15/15] chore(ui): note header class breaking change

Signed-off-by: Charles de Dreuille <charles.dedreuille@gmail.com>
---
 .changeset/header-sticky-prop.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/.changeset/header-sticky-prop.md b/.changeset/header-sticky-prop.md
index b376bb04da..b74af33ae0 100644
--- a/.changeset/header-sticky-prop.md
+++ b/.changeset/header-sticky-prop.md
@@ -4,4 +4,6 @@
 
 Added a `sticky` prop to the `Header` component. When `true`, the title-and-actions bar stays fixed to the top of its scroll container while the rest of the header (tags, description, metadata) scrolls away. The sticky bar background color automatically matches the container surface using the bg-consumer system.
 
+**BREAKING**: Removed the main header class from the `Header` component. Custom styles that target this class should be updated to target the component sections that remain.
+
 **Affected components:** Header