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] 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 />
+      </>
+    );
+  },
+});