From 6bf7fb3d95b42142c3b3d5384e8ce0fa9444ce83 Mon Sep 17 00:00:00 2001
From: Lee-Dongwook <dlehddnr0713@gmail.com>
Date: Wed, 29 Jul 2026 10:40:38 +0900
Subject: [PATCH] feat: Dialog Hero Header

---
 .changeset/dialog-hero-header.md              |   6 +
 .../stories/DialogHeroHeader.stories.tsx      | 162 +++++++++++
 packages/cli/lib/xle/registry-core.mjs        | 173 +++++++++---
 .../DialogHeroHeaderBasic.doc.mjs             |  14 +
 .../DialogHeroHeaderBasic.tsx                 |  47 ++++
 .../DialogHeroHeaderShowcase.doc.mjs          |  15 +
 .../DialogHeroHeaderShowcase.tsx              |  35 +++
 packages/core/src/Dialog/Dialog.doc.mjs       | 243 +++++++++++++---
 .../core/src/Dialog/DialogHeroHeader.doc.mjs  | 186 ++++++++++++
 .../core/src/Dialog/DialogHeroHeader.test.tsx | 179 ++++++++++++
 packages/core/src/Dialog/DialogHeroHeader.tsx | 265 ++++++++++++++++++
 packages/core/src/Dialog/index.ts             |   5 +-
 12 files changed, 1247 insertions(+), 83 deletions(-)
 create mode 100644 .changeset/dialog-hero-header.md
 create mode 100644 apps/storybook/stories/DialogHeroHeader.stories.tsx
 create mode 100644 packages/cli/templates/blocks/components/DialogHeroHeader/DialogHeroHeaderBasic.doc.mjs
 create mode 100644 packages/cli/templates/blocks/components/DialogHeroHeader/DialogHeroHeaderBasic.tsx
 create mode 100644 packages/cli/templates/blocks/components/DialogHeroHeader/DialogHeroHeaderShowcase.doc.mjs
 create mode 100644 packages/cli/templates/blocks/components/DialogHeroHeader/DialogHeroHeaderShowcase.tsx
 create mode 100644 packages/core/src/Dialog/DialogHeroHeader.doc.mjs
 create mode 100644 packages/core/src/Dialog/DialogHeroHeader.test.tsx
 create mode 100644 packages/core/src/Dialog/DialogHeroHeader.tsx

diff --git a/.changeset/dialog-hero-header.md b/.changeset/dialog-hero-header.md
new file mode 100644
index 0000000000000..8bd09e6af46d4
--- /dev/null
+++ b/.changeset/dialog-hero-header.md
@@ -0,0 +1,6 @@
+---
+'@astryxdesign/core': patch
+---
+
+[feat] DialogHeroHeader: prominent, hero-style header for Dialog — the high-emphasis sibling of DialogHeader. Adds an optional media/visual slot and eyebrow above a display-scale title, centered by default (`align="start"` for left alignment), with the same onOpenChange-driven close button and aria-labelledby title behavior. For featured, marketing, or onboarding dialogs.
+@Lee-Dongwook
diff --git a/apps/storybook/stories/DialogHeroHeader.stories.tsx b/apps/storybook/stories/DialogHeroHeader.stories.tsx
new file mode 100644
index 0000000000000..1fadd96442609
--- /dev/null
+++ b/apps/storybook/stories/DialogHeroHeader.stories.tsx
@@ -0,0 +1,162 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {useState} from 'react';
+import type {Meta, StoryObj} from '@storybook/react';
+import {Dialog, DialogHeroHeader} from '@astryxdesign/core/Dialog';
+import {
+  Layout,
+  LayoutContent,
+  LayoutFooter,
+  HStack,
+} from '@astryxdesign/core/Layout';
+import {Button} from '@astryxdesign/core/Button';
+import {Icon} from '@astryxdesign/core/Icon';
+import {Text} from '@astryxdesign/core/Text';
+
+const meta: Meta<typeof DialogHeroHeader> = {
+  title: 'Core/DialogHeroHeader',
+  component: DialogHeroHeader,
+  tags: ['autodocs'],
+  argTypes: {
+    align: {
+      control: 'inline-radio',
+      options: ['center', 'start'],
+      description: 'Horizontal alignment of the hero content',
+    },
+    hasDivider: {
+      control: 'boolean',
+      description: 'Adds a border at the bottom edge',
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof DialogHeroHeader>;
+
+/**
+ * The prominent hero treatment: media, eyebrow, display-scale title, and
+ * supporting text, centered by default. Actions live in LayoutFooter.
+ */
+function CenteredExample() {
+  const [isOpen, setIsOpen] = useState(false);
+
+  return (
+    <>
+      <Button
+        label="Open hero dialog"
+        variant="secondary"
+        onClick={() => setIsOpen(true)}
+      />
+      <Dialog isOpen={isOpen} onOpenChange={open => setIsOpen(open)}>
+        <Layout
+          header={
+            <DialogHeroHeader
+              media={<Icon icon="success" size="lg" color="accent" />}
+              eyebrow="Welcome"
+              title="You're all set up"
+              subtitle="Your workspace is ready. Invite your team to start collaborating."
+              onOpenChange={open => setIsOpen(open)}
+            />
+          }
+          content={
+            <LayoutContent>
+              <Text type="body" color="secondary">
+                Body content for the featured moment goes here.
+              </Text>
+            </LayoutContent>
+          }
+          footer={
+            <LayoutFooter>
+              <HStack gap={2} hAlign="end">
+                <Button
+                  label="Maybe later"
+                  variant="secondary"
+                  onClick={() => setIsOpen(false)}
+                />
+                <Button
+                  label="Invite team"
+                  variant="primary"
+                  onClick={() => setIsOpen(false)}
+                />
+              </HStack>
+            </LayoutFooter>
+          }
+        />
+      </Dialog>
+    </>
+  );
+}
+
+export const Default: Story = {
+  render: () => <CenteredExample />,
+};
+
+/**
+ * Start-aligned variant — left-aligned like DialogHeader, but at hero scale.
+ */
+function StartAlignedExample() {
+  const [isOpen, setIsOpen] = useState(false);
+
+  return (
+    <>
+      <Button
+        label="Open start-aligned"
+        variant="secondary"
+        onClick={() => setIsOpen(true)}
+      />
+      <Dialog isOpen={isOpen} onOpenChange={open => setIsOpen(open)}>
+        <Layout
+          header={
+            <DialogHeroHeader
+              align="start"
+              eyebrow="New feature"
+              title="Introducing Insights"
+              subtitle="Track how your team uses the workspace over time."
+              onOpenChange={open => setIsOpen(open)}
+            />
+          }
+          content={
+            <LayoutContent>
+              <Text type="body" color="secondary">
+                Body content goes here.
+              </Text>
+            </LayoutContent>
+          }
+        />
+      </Dialog>
+    </>
+  );
+}
+
+export const StartAligned: Story = {
+  render: () => <StartAlignedExample />,
+};
+
+/**
+ * Inline preview (isInline) — the same rendering used by docs/showcases, with
+ * autofocus suppressed. Handy for visual review without opening a modal.
+ */
+export const InlinePreview: Story = {
+  render: () => (
+    <Dialog isOpen isInline onOpenChange={() => {}}>
+      <Layout
+        header={
+          <DialogHeroHeader
+            media={<Icon icon="success" size="lg" color="accent" />}
+            eyebrow="Payment received"
+            title="Thanks for your order"
+            subtitle="A receipt has been sent to your email. Your plan is now active."
+            onOpenChange={() => {}}
+          />
+        }
+        content={
+          <LayoutContent>
+            <Text type="body" color="secondary">
+              Dialog body content goes here.
+            </Text>
+          </LayoutContent>
+        }
+      />
+    </Dialog>
+  ),
+};
diff --git a/packages/cli/lib/xle/registry-core.mjs b/packages/cli/lib/xle/registry-core.mjs
index dd5d699bcf29b..05e68e8bcbbd1 100644
--- a/packages/cli/lib/xle/registry-core.mjs
+++ b/packages/cli/lib/xle/registry-core.mjs
@@ -26,45 +26,132 @@
  */
 export const ALIAS_TABLE = {
   // Layout core
-  A: 'AppShell', L: 'Layout', LH: 'LayoutHeader', LC: 'LayoutContent',
-  LF: 'LayoutFooter', LP: 'LayoutPanel', V: 'VStack', H: 'HStack',
-  SI: 'StackItem', G: 'Grid', GS: 'GridSpan', S: 'Section', Ctr: 'Center',
-  F: 'FormLayout', D: 'Divider', Tbar: 'Toolbar', AR: 'AspectRatio',
+  A: 'AppShell',
+  L: 'Layout',
+  LH: 'LayoutHeader',
+  LC: 'LayoutContent',
+  LF: 'LayoutFooter',
+  LP: 'LayoutPanel',
+  V: 'VStack',
+  H: 'HStack',
+  SI: 'StackItem',
+  G: 'Grid',
+  GS: 'GridSpan',
+  S: 'Section',
+  Ctr: 'Center',
+  F: 'FormLayout',
+  D: 'Divider',
+  Tbar: 'Toolbar',
+  AR: 'AspectRatio',
   // Navigation
-  TN: 'TopNav', TNH: 'TopNavHeading', TNI: 'TopNavItem',
-  SN: 'SideNav', SNI: 'SideNavItem', SNS: 'SideNavSection', SNH: 'SideNavHeading',
-  MN: 'MobileNav', MNT: 'MobileNavToggle',
-  BC: 'Breadcrumbs', BCI: 'BreadcrumbItem',
-  TL: 'TabList', Tab: 'Tab', PG: 'Pagination',
-  SG: 'SegmentedControl', SGI: 'SegmentedControlItem',
+  TN: 'TopNav',
+  TNH: 'TopNavHeading',
+  TNI: 'TopNavItem',
+  SN: 'SideNav',
+  SNI: 'SideNavItem',
+  SNS: 'SideNavSection',
+  SNH: 'SideNavHeading',
+  MN: 'MobileNav',
+  MNT: 'MobileNavToggle',
+  BC: 'Breadcrumbs',
+  BCI: 'BreadcrumbItem',
+  TL: 'TabList',
+  Tab: 'Tab',
+  PG: 'Pagination',
+  SG: 'SegmentedControl',
+  SGI: 'SegmentedControlItem',
   // Data display
-  T: 'Table', TH: 'TableHeader', TB: 'TableBody', TF: 'TableFooter',
-  TR: 'TableRow', TC: 'TableCell', TD: 'TableCell', THC: 'TableHeaderCell',
-  UL: 'List', LI: 'ListItem', ML: 'MetadataList', MLI: 'MetadataListItem',
-  C: 'Card', CC: 'ClickableCard', ES: 'EmptyState', Bd: 'Badge',
-  SD: 'StatusDot', Av: 'Avatar', AvG: 'AvatarGroup', Tmb: 'Thumbnail',
-  Ts: 'Timestamp', OFL: 'OverflowList', Cs: 'Carousel', It: 'Item',
+  T: 'Table',
+  TH: 'TableHeader',
+  TB: 'TableBody',
+  TF: 'TableFooter',
+  TR: 'TableRow',
+  TC: 'TableCell',
+  TD: 'TableCell',
+  THC: 'TableHeaderCell',
+  UL: 'List',
+  LI: 'ListItem',
+  ML: 'MetadataList',
+  MLI: 'MetadataListItem',
+  C: 'Card',
+  CC: 'ClickableCard',
+  ES: 'EmptyState',
+  Bd: 'Badge',
+  SD: 'StatusDot',
+  Av: 'Avatar',
+  AvG: 'AvatarGroup',
+  Tmb: 'Thumbnail',
+  Ts: 'Timestamp',
+  OFL: 'OverflowList',
+  Cs: 'Carousel',
+  It: 'Item',
   // Forms & inputs
-  Fd: 'Field', IG: 'InputGroup', IGT: 'InputGroupText',
-  TI: 'TextInput', TA: 'TextArea', NI: 'NumberInput',
-  DI: 'DateInput', DR: 'DateRangeInput', DT: 'DateTimeInput', TM: 'TimeInput',
-  FI: 'FileInput', CB: 'CheckboxInput', CL: 'CheckboxList', CLI: 'CheckboxListItem',
-  RL: 'RadioList', RLI: 'RadioListItem', SW: 'Switch', SL: 'Slider',
-  SE: 'Selector', MS: 'MultiSelector', TY: 'Typeahead', Tkz: 'Tokenizer',
-  PS: 'PowerSearch', CAL: 'Calendar',
+  Fd: 'Field',
+  IG: 'InputGroup',
+  IGT: 'InputGroupText',
+  TI: 'TextInput',
+  TA: 'TextArea',
+  NI: 'NumberInput',
+  DI: 'DateInput',
+  DR: 'DateRangeInput',
+  DT: 'DateTimeInput',
+  TM: 'TimeInput',
+  FI: 'FileInput',
+  CB: 'CheckboxInput',
+  CL: 'CheckboxList',
+  CLI: 'CheckboxListItem',
+  RL: 'RadioList',
+  RLI: 'RadioListItem',
+  SW: 'Switch',
+  SL: 'Slider',
+  SE: 'Selector',
+  MS: 'MultiSelector',
+  TY: 'Typeahead',
+  Tkz: 'Tokenizer',
+  PS: 'PowerSearch',
+  CAL: 'Calendar',
   // Overlay & feedback
-  Dlg: 'Dialog', DH: 'DialogHeader', AD: 'AlertDialog',
-  Po: 'Popover', HC: 'HoverCard', Tt: 'Tooltip', Bn: 'Banner', Ov: 'Overlay',
-  CM: 'ContextMenu', DM: 'DropdownMenu', MM: 'MoreMenu', CP: 'CommandPalette',
-  Col: 'Collapsible', ColG: 'CollapsibleGroup',
-  Sp: 'Spinner', PB: 'ProgressBar', Sk: 'Skeleton',
+  Dlg: 'Dialog',
+  DH: 'DialogHeader',
+  DHH: 'DialogHeroHeader',
+  AD: 'AlertDialog',
+  Po: 'Popover',
+  HC: 'HoverCard',
+  Tt: 'Tooltip',
+  Bn: 'Banner',
+  Ov: 'Overlay',
+  CM: 'ContextMenu',
+  DM: 'DropdownMenu',
+  MM: 'MoreMenu',
+  CP: 'CommandPalette',
+  Col: 'Collapsible',
+  ColG: 'CollapsibleGroup',
+  Sp: 'Spinner',
+  PB: 'ProgressBar',
+  Sk: 'Skeleton',
   // Content & chat
-  Tx: 'Text', Hd: 'Heading', MD: 'Markdown', Cd: 'CodeBlock', BQ: 'Blockquote',
-  K: 'Kbd', Ic: 'Icon', Lk: 'Link', Tk: 'Token',
-  B: 'Button', IB: 'IconButton', BG: 'ButtonGroup', Tg: 'ToggleButton', TgG: 'ToggleButtonGroup',
-  ChL: 'ChatLayout', ChML: 'ChatMessageList', ChM: 'ChatMessage',
-  ChB: 'ChatMessageBubble', ChC: 'ChatComposer', ChCD: 'ChatComposerDrawer',
-  ChS: 'ChatSystemMessage', ChT: 'ChatToolCalls',
+  Tx: 'Text',
+  Hd: 'Heading',
+  MD: 'Markdown',
+  Cd: 'CodeBlock',
+  BQ: 'Blockquote',
+  K: 'Kbd',
+  Ic: 'Icon',
+  Lk: 'Link',
+  Tk: 'Token',
+  B: 'Button',
+  IB: 'IconButton',
+  BG: 'ButtonGroup',
+  Tg: 'ToggleButton',
+  TgG: 'ToggleButtonGroup',
+  ChL: 'ChatLayout',
+  ChML: 'ChatMessageList',
+  ChM: 'ChatMessage',
+  ChB: 'ChatMessageBubble',
+  ChC: 'ChatComposer',
+  ChCD: 'ChatComposerDrawer',
+  ChS: 'ChatSystemMessage',
+  ChT: 'ChatToolCalls',
 };
 
 /** SpacingStep — the canonical spacing enum (matches the doc.mjs prose). */
@@ -89,8 +176,14 @@ export function parseEnumValues(type) {
   const values = [];
   for (const part of parts) {
     const str = part.match(/^'([^']*)'$/) || part.match(/^"([^"]*)"$/);
-    if (str) { values.push(str[1]); continue; }
-    if (/^\d+(\.\d+)?$/.test(part)) { values.push(Number(part)); continue; }
+    if (str) {
+      values.push(str[1]);
+      continue;
+    }
+    if (/^\d+(\.\d+)?$/.test(part)) {
+      values.push(Number(part));
+      continue;
+    }
     return null; // union of non-literal types (e.g. number|string) — not an enum
   }
   return values;
@@ -155,7 +248,9 @@ export function serializeRegistry(registry) {
       dirName: c.dirName,
       importPath: c.importPath,
       undocumented: c.undocumented || false,
-      props: /** @type {Array<Record<string, unknown>>} */ (/** @type {unknown} */ ([...c.props.values()])),
+      props: /** @type {Array<Record<string, unknown>>} */ (
+        /** @type {unknown} */ ([...c.props.values()])
+      ),
     })),
     aliases: [...registry.aliases.entries()],
     componentNames: registry.componentNames,
@@ -175,7 +270,9 @@ export function hydrateRegistry(json) {
     /** @type {Map<string, import('./xle-ast').RegistryProp>} */
     const props = new Map();
     for (const p of c.props) {
-      const prop = /** @type {import('./xle-ast').RegistryProp} */ (/** @type {unknown} */ (p));
+      const prop = /** @type {import('./xle-ast').RegistryProp} */ (
+        /** @type {unknown} */ (p)
+      );
       props.set(String(p.name), prop);
     }
     components.set(c.name, {
diff --git a/packages/cli/templates/blocks/components/DialogHeroHeader/DialogHeroHeaderBasic.doc.mjs b/packages/cli/templates/blocks/components/DialogHeroHeader/DialogHeroHeaderBasic.doc.mjs
new file mode 100644
index 0000000000000..38eaa4868286b
--- /dev/null
+++ b/packages/cli/templates/blocks/components/DialogHeroHeader/DialogHeroHeaderBasic.doc.mjs
@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+  type: 'block',
+  exampleFor: 'DialogHeroHeader',
+  name: 'DialogHeroHeaderBasic',
+  displayName: 'Dialog Hero Header Basic',
+  description:
+    'A hero-style dialog header with a media slot, eyebrow, prominent title, and supporting text — the high-emphasis treatment for onboarding or featured moments.',
+  isReady: true,
+  aspectRatio: 16 / 9,
+  componentsUsed: ['Dialog', 'DialogHeroHeader'],
+};
diff --git a/packages/cli/templates/blocks/components/DialogHeroHeader/DialogHeroHeaderBasic.tsx b/packages/cli/templates/blocks/components/DialogHeroHeader/DialogHeroHeaderBasic.tsx
new file mode 100644
index 0000000000000..d13bf901cc955
--- /dev/null
+++ b/packages/cli/templates/blocks/components/DialogHeroHeader/DialogHeroHeaderBasic.tsx
@@ -0,0 +1,47 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {Dialog, DialogHeroHeader} from '@astryxdesign/core/Dialog';
+import {
+  Layout,
+  LayoutContent,
+  LayoutFooter,
+  HStack,
+} from '@astryxdesign/core/Layout';
+import {Button} from '@astryxdesign/core/Button';
+import {Icon} from '@astryxdesign/core/Icon';
+import {Text} from '@astryxdesign/core/Text';
+
+export default function DialogHeroHeaderBasic() {
+  return (
+    <Dialog isOpen isInline onOpenChange={() => {}}>
+      <Layout
+        header={
+          <DialogHeroHeader
+            media={<Icon icon="success" size="lg" color="accent" />}
+            eyebrow="Welcome"
+            title="You're all set up"
+            subtitle="Your workspace is ready. Invite your team to start collaborating."
+            onOpenChange={() => {}}
+          />
+        }
+        content={
+          <LayoutContent>
+            <Text type="body" color="secondary">
+              Dialog body content goes here.
+            </Text>
+          </LayoutContent>
+        }
+        footer={
+          <LayoutFooter>
+            <HStack gap={2} hAlign="end">
+              <Button label="Maybe later" variant="secondary" />
+              <Button label="Invite team" variant="primary" />
+            </HStack>
+          </LayoutFooter>
+        }
+      />
+    </Dialog>
+  );
+}
diff --git a/packages/cli/templates/blocks/components/DialogHeroHeader/DialogHeroHeaderShowcase.doc.mjs b/packages/cli/templates/blocks/components/DialogHeroHeader/DialogHeroHeaderShowcase.doc.mjs
new file mode 100644
index 0000000000000..841488d3a51c4
--- /dev/null
+++ b/packages/cli/templates/blocks/components/DialogHeroHeader/DialogHeroHeaderShowcase.doc.mjs
@@ -0,0 +1,15 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+  type: 'block',
+  exampleFor: 'DialogHeroHeader',
+  name: 'DialogHeroHeader',
+  displayName: 'Dialog Hero Header',
+  description:
+    'DialogHeroHeader provides a prominent, hero-style header for dialogs with slots for a media/visual, eyebrow, display-scale title, supporting text, and close button.',
+  isReady: true,
+  isShowcase: true,
+  aspectRatio: 16 / 9,
+  componentsUsed: ['Dialog', 'DialogHeroHeader'],
+};
diff --git a/packages/cli/templates/blocks/components/DialogHeroHeader/DialogHeroHeaderShowcase.tsx b/packages/cli/templates/blocks/components/DialogHeroHeader/DialogHeroHeaderShowcase.tsx
new file mode 100644
index 0000000000000..c0d5740053022
--- /dev/null
+++ b/packages/cli/templates/blocks/components/DialogHeroHeader/DialogHeroHeaderShowcase.tsx
@@ -0,0 +1,35 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {Dialog, DialogHeroHeader} from '@astryxdesign/core/Dialog';
+import {Layout, LayoutContent, Card} from '@astryxdesign/core/Layout';
+import {Icon} from '@astryxdesign/core/Icon';
+import {Text} from '@astryxdesign/core/Text';
+
+export default function DialogHeroHeaderShowcase() {
+  return (
+    <Dialog isOpen isInline onOpenChange={() => {}}>
+      <Layout
+        header={
+          <DialogHeroHeader
+            media={<Icon icon="success" size="lg" color="accent" />}
+            eyebrow="Payment received"
+            title="Thanks for your order"
+            subtitle="A receipt has been sent to your email. Your plan is now active."
+            onOpenChange={() => {}}
+          />
+        }
+        content={
+          <LayoutContent>
+            <Card variant="muted">
+              <Text type="body" color="secondary">
+                Dialog body content goes here.
+              </Text>
+            </Card>
+          </LayoutContent>
+        }
+      />
+    </Dialog>
+  );
+}
diff --git a/packages/core/src/Dialog/Dialog.doc.mjs b/packages/core/src/Dialog/Dialog.doc.mjs
index a3d1f892d7996..a5990133aeee6 100644
--- a/packages/core/src/Dialog/Dialog.doc.mjs
+++ b/packages/core/src/Dialog/Dialog.doc.mjs
@@ -7,7 +7,19 @@ export const docs = {
   displayName: 'Dialog',
   group: 'Dialog',
   category: 'Overlay',
-  keywords: ["dialog","modal","popup","overlay","lightbox","alert","confirm","prompt","backdrop","focus trap","imperative"],
+  keywords: [
+    'dialog',
+    'modal',
+    'popup',
+    'overlay',
+    'lightbox',
+    'alert',
+    'confirm',
+    'prompt',
+    'backdrop',
+    'focus trap',
+    'imperative',
+  ],
   // Intentionally a contained isInline preview, not playground.overlay: the
   // component stays visible on load and knobs stay live, whereas a real
   // showModal() overlay makes the page inert — see PlaygroundConfig.overlay
@@ -19,20 +31,30 @@ export const docs = {
       onOpenChange: undefined,
       width: 400,
       children: {
-        __element: 'VStack', props: {gap: 2}, children: [
+        __element: 'VStack',
+        props: {gap: 2},
+        children: [
           {__element: 'Heading', props: {level: 3}, children: 'Dialog Title'},
-          {__element: 'Text', props: {type: 'body'}, children: 'Are you sure you want to proceed? This action can be undone later from settings.'},
+          {
+            __element: 'Text',
+            props: {type: 'body'},
+            children:
+              'Are you sure you want to proceed? This action can be undone later from settings.',
+          },
         ],
       },
     },
   },
   theming: {
     container: true,
-    targets: [
-      {className: 'astryx-dialog', visualProps: ['variant']},
-    ],
+    targets: [{className: 'astryx-dialog', visualProps: ['variant']}],
     vars: [
-      {name: '--_dialog-radius', description: 'Border radius of the dialog', default: 'var(--radius-container)', private: true},
+      {
+        name: '--_dialog-radius',
+        description: 'Border radius of the dialog',
+        default: 'var(--radius-container)',
+        private: true,
+      },
     ],
     derived: [
       {property: 'borderRadius', vars: ['--_dialog-radius']},
@@ -74,47 +96,101 @@ export const docs = {
     {
       name: 'position',
       type: 'DialogPosition',
-      description: 'Static position for the dialog; centered by default when omitted.',
+      description:
+        'Static position for the dialog; centered by default when omitted.',
     },
     {
       name: 'variant',
       type: "'standard' | 'fullscreen'",
-      description: 'Dialog variant: fullscreen expands to fill the entire viewport.',
+      description:
+        'Dialog variant: fullscreen expands to fill the entire viewport.',
       default: "'standard'",
     },
     {
       name: 'purpose',
       type: "'required' | 'form' | 'info'",
-      description: 'Controls dismissal behavior: required disables Escape and backdrop click; form disables backdrop click after interaction; info allows both.',
+      description:
+        'Controls dismissal behavior: required disables Escape and backdrop click; form disables backdrop click after interaction; info allows both.',
       default: "'info'",
     },
     {
       name: 'isInline',
       type: 'boolean',
-      description: 'Renders dialog content inline without the <dialog> element, backdrop, or modal behavior. For documentation previews and showcases only.',
+      description:
+        'Renders dialog content inline without the <dialog> element, backdrop, or modal behavior. For documentation previews and showcases only.',
       default: 'false',
     },
   ],
   components: [
     {name: 'DialogHeader'},
+    {name: 'DialogHeroHeader'},
     {name: 'useImperativeDialog'},
   ],
   usage: {
-    description: 'Dialog displays a modal overlay that blocks interaction with the page until the user responds. Use it for delete confirmations, edit forms, terms acceptance, or any decision that should not be skipped.\n\nFor cases where you want to show a dialog without managing open state, use the `useImperativeDialog` hook: call `dialog.show(content)` and render `dialog.element` in your tree.',
+    description:
+      'Dialog displays a modal overlay that blocks interaction with the page until the user responds. Use it for delete confirmations, edit forms, terms acceptance, or any decision that should not be skipped.\n\nFor cases where you want to show a dialog without managing open state, use the `useImperativeDialog` hook: call `dialog.show(content)` and render `dialog.element` in your tree.',
     bestPractices: [
-      { guidance: true, description: 'Choose the right purpose: info for dismissable content, form to prevent accidental backdrop dismissal, required when the user must respond.' },
-      { guidance: true, description: 'Include a clear title in the header so users immediately understand what the dialog is asking.' },
-      { guidance: true, description: 'Use purpose="form" for dialogs with inputs so the user can\'t accidentally lose data by clicking the backdrop.' },
-      { guidance: true, description: 'Keep dialogs focused on a single task; if the content grows beyond what fits, consider a full page instead.' },
-      { guidance: false, description: 'Use a dialog for simple messages that could be shown inline or as a toast notification.' },
-      { guidance: false, description: 'Nest dialogs inside other dialogs; restructure the flow into steps within a single dialog instead.' },
-      { guidance: false, description: 'Use the fullscreen variant for simple confirmations; it is meant for complex content like editors or long forms.' },
+      {
+        guidance: true,
+        description:
+          'Choose the right purpose: info for dismissable content, form to prevent accidental backdrop dismissal, required when the user must respond.',
+      },
+      {
+        guidance: true,
+        description:
+          'Include a clear title in the header so users immediately understand what the dialog is asking.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use purpose="form" for dialogs with inputs so the user can\'t accidentally lose data by clicking the backdrop.',
+      },
+      {
+        guidance: true,
+        description:
+          'Keep dialogs focused on a single task; if the content grows beyond what fits, consider a full page instead.',
+      },
+      {
+        guidance: false,
+        description:
+          'Use a dialog for simple messages that could be shown inline or as a toast notification.',
+      },
+      {
+        guidance: false,
+        description:
+          'Nest dialogs inside other dialogs; restructure the flow into steps within a single dialog instead.',
+      },
+      {
+        guidance: false,
+        description:
+          'Use the fullscreen variant for simple confirmations; it is meant for complex content like editors or long forms.',
+      },
     ],
     anatomy: [
-      {name: 'Header', required: true, description: 'Title, optional subtitle, and close button. The title receives focus on open and labels the dialog via aria-labelledby.'},
-      {name: 'Body', required: true, description: 'The main content area: text, forms, lists, or any layout.'},
-      {name: 'Footer', required: false, description: 'Action buttons like Save/Cancel or Accept/Decline, aligned to the end.'},
-      {name: 'Backdrop', required: true, description: 'Semi-transparent overlay behind the dialog that blocks page interaction.'},
+      {
+        name: 'Header',
+        required: true,
+        description:
+          'Title, optional subtitle, and close button. The title receives focus on open and labels the dialog via aria-labelledby. Use DialogHeader for the compact treatment, or DialogHeroHeader for a prominent hero header on featured/onboarding dialogs.',
+      },
+      {
+        name: 'Body',
+        required: true,
+        description:
+          'The main content area: text, forms, lists, or any layout.',
+      },
+      {
+        name: 'Footer',
+        required: false,
+        description:
+          'Action buttons like Save/Cancel or Accept/Decline, aligned to the end.',
+      },
+      {
+        name: 'Backdrop',
+        required: true,
+        description:
+          'Semi-transparent overlay behind the dialog that blocks page interaction.',
+      },
     ],
   },
 };
@@ -122,38 +198,117 @@ export const docs = {
 /** @type {import('../docs-types').TranslationDoc} */
 export const docsZh = {
   usage: {
-    description: 'Dialog displays a modal overlay that blocks interaction with the page until the user responds. Use it for delete confirmations, edit forms, terms acceptance, or any decision that should not be skipped.',
+    description:
+      'Dialog displays a modal overlay that blocks interaction with the page until the user responds. Use it for delete confirmations, edit forms, terms acceptance, or any decision that should not be skipped.',
     bestPractices: [
-      { guidance: true, description: 'Choose the right purpose: info for dismissable content, form to prevent accidental backdrop dismissal, required when the user must respond.' },
-      { guidance: true, description: 'Include a clear title in the header so users immediately understand what the dialog is asking.' },
-      { guidance: true, description: 'Use purpose="form" for dialogs with inputs so the user can\'t accidentally lose data by clicking the backdrop.' },
-      { guidance: true, description: 'Keep dialogs focused on a single task; if the content grows beyond what fits, consider a full page instead.' },
-      { guidance: false, description: 'Use a dialog for simple messages that could be shown inline or as a toast notification.' },
-      { guidance: false, description: 'Nest dialogs inside other dialogs; restructure the flow into steps within a single dialog instead.' },
-      { guidance: false, description: 'Use the fullscreen variant for simple confirmations; it is meant for complex content like editors or long forms.' },
+      {
+        guidance: true,
+        description:
+          'Choose the right purpose: info for dismissable content, form to prevent accidental backdrop dismissal, required when the user must respond.',
+      },
+      {
+        guidance: true,
+        description:
+          'Include a clear title in the header so users immediately understand what the dialog is asking.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use purpose="form" for dialogs with inputs so the user can\'t accidentally lose data by clicking the backdrop.',
+      },
+      {
+        guidance: true,
+        description:
+          'Keep dialogs focused on a single task; if the content grows beyond what fits, consider a full page instead.',
+      },
+      {
+        guidance: false,
+        description:
+          'Use a dialog for simple messages that could be shown inline or as a toast notification.',
+      },
+      {
+        guidance: false,
+        description:
+          'Nest dialogs inside other dialogs; restructure the flow into steps within a single dialog instead.',
+      },
+      {
+        guidance: false,
+        description:
+          'Use the fullscreen variant for simple confirmations; it is meant for complex content like editors or long forms.',
+      },
     ],
     anatomy: [
-      {name: 'Header', required: true, description: 'Title, optional subtitle, and close button. The title receives focus on open and labels the dialog via aria-labelledby.'},
-      {name: 'Body', required: true, description: 'The main content area: text, forms, lists, or any layout.'},
-      {name: 'Footer', required: false, description: 'Action buttons like Save/Cancel or Accept/Decline, aligned to the end.'},
-      {name: 'Backdrop', required: true, description: 'Semi-transparent overlay behind the dialog that blocks page interaction.'},
+      {
+        name: 'Header',
+        required: true,
+        description:
+          'Title, optional subtitle, and close button. The title receives focus on open and labels the dialog via aria-labelledby. Use DialogHeader for the compact treatment, or DialogHeroHeader for a prominent hero header on featured/onboarding dialogs.',
+      },
+      {
+        name: 'Body',
+        required: true,
+        description:
+          'The main content area: text, forms, lists, or any layout.',
+      },
+      {
+        name: 'Footer',
+        required: false,
+        description:
+          'Action buttons like Save/Cancel or Accept/Decline, aligned to the end.',
+      },
+      {
+        name: 'Backdrop',
+        required: true,
+        description:
+          'Semi-transparent overlay behind the dialog that blocks page interaction.',
+      },
     ],
   },
 };
 
 /** @type {import('../docs-types').TranslationDoc} */
 export const docsDense = {
-  description: 'modal overlay that blocks page interaction until the user responds',
+  description:
+    'modal overlay that blocks page interaction until the user responds',
   usage: {
-    description: 'Dialog displays a modal overlay that blocks page interaction. Use for delete confirmations, edit forms, terms acceptance.',
+    description:
+      'Dialog displays a modal overlay that blocks page interaction. Use for delete confirmations, edit forms, terms acceptance.',
     bestPractices: [
-      { guidance: true, description: 'Choose the right purpose: info for dismissable content, form to prevent accidental backdrop dismissal, required when user must respond.' },
-      { guidance: true, description: 'Include a clear title in the header so users immediately understand what the dialog is asking.' },
-      { guidance: true, description: 'Use purpose="form" for dialogs with inputs so user can\'t accidentally lose data by clicking the backdrop.' },
-      { guidance: true, description: 'Keep dialogs focused on a single task; if content grows beyond what fits, consider a full page instead.' },
-      { guidance: false, description: 'Use a dialog for simple messages that could be shown inline or as a toast notification.' },
-      { guidance: false, description: 'Nest dialogs inside other dialogs; restructure the flow into steps within a single dialog instead.' },
-      { guidance: false, description: 'Use the fullscreen variant for simple confirmations; it\'s meant for complex content like editors or long forms.' },
+      {
+        guidance: true,
+        description:
+          'Choose the right purpose: info for dismissable content, form to prevent accidental backdrop dismissal, required when user must respond.',
+      },
+      {
+        guidance: true,
+        description:
+          'Include a clear title in the header so users immediately understand what the dialog is asking.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use purpose="form" for dialogs with inputs so user can\'t accidentally lose data by clicking the backdrop.',
+      },
+      {
+        guidance: true,
+        description:
+          'Keep dialogs focused on a single task; if content grows beyond what fits, consider a full page instead.',
+      },
+      {
+        guidance: false,
+        description:
+          'Use a dialog for simple messages that could be shown inline or as a toast notification.',
+      },
+      {
+        guidance: false,
+        description:
+          'Nest dialogs inside other dialogs; restructure the flow into steps within a single dialog instead.',
+      },
+      {
+        guidance: false,
+        description:
+          "Use the fullscreen variant for simple confirmations; it's meant for complex content like editors or long forms.",
+      },
     ],
   },
 };
diff --git a/packages/core/src/Dialog/DialogHeroHeader.doc.mjs b/packages/core/src/Dialog/DialogHeroHeader.doc.mjs
new file mode 100644
index 0000000000000..ef2d910b120e3
--- /dev/null
+++ b/packages/core/src/Dialog/DialogHeroHeader.doc.mjs
@@ -0,0 +1,186 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+  name: 'DialogHeroHeader',
+  subComponentOf: 'Dialog',
+  displayName: 'Dialog Hero Header',
+  isHiddenFromOverview: true,
+  description:
+    'Prominent, hero-style header for dialogs — the high-emphasis sibling of DialogHeader. Adds an optional media/visual slot and eyebrow above a display-scale title, centered by default. Use for featured, marketing, or onboarding moments.',
+  props: [
+    {
+      name: 'title',
+      type: 'string',
+      description:
+        'Dialog title at hero (display) scale (receives focus on open and labels the dialog via aria-labelledby).',
+    },
+    {
+      name: 'subtitle',
+      type: 'string',
+      description: 'Supporting text below the title, in secondary color.',
+    },
+    {
+      name: 'eyebrow',
+      type: 'string',
+      description: 'Short overline above the title, in accent color.',
+    },
+    {
+      name: 'media',
+      type: 'ReactNode',
+      description:
+        'Visual slot above the title (illustration, image, or icon tile).',
+      slotElements: [
+        {
+          __element: 'Icon',
+          props: {
+            icon: 'success',
+            size: 'lg',
+            color: 'accent',
+          },
+        },
+      ],
+    },
+    {
+      name: 'align',
+      type: "'center' | 'start'",
+      description: 'Horizontal alignment of the hero content.',
+      default: "'center'",
+    },
+    {
+      name: 'onOpenChange',
+      type: '(isOpen: boolean) => unknown',
+      description: 'Close button callback (no button if omitted).',
+    },
+    {
+      name: 'hasDivider',
+      type: 'boolean',
+      description: 'Adds border at the bottom edge.',
+      default: 'true',
+    },
+  ],
+  playground: {
+    defaults: {
+      eyebrow: 'Welcome',
+      title: "You're all set up",
+      subtitle: 'Your workspace is ready. Invite your team to get started.',
+      align: 'center',
+      hasDivider: false,
+    },
+  },
+  examples: [
+    {
+      label: 'Basic',
+      code: `
+import {DialogHeroHeader} from '@astryxdesign/core/Dialog';
+
+<DialogHeroHeader
+  eyebrow="Welcome"
+  title="You're all set up"
+  subtitle="Your workspace is ready. Invite your team to get started."
+/>;
+`,
+    },
+    {
+      label: 'With media and close button',
+      code: `
+import {useState} from 'react';
+import {DialogHeroHeader} from '@astryxdesign/core/Dialog';
+import {Icon} from '@astryxdesign/core/Icon';
+
+function Header() {
+  const [, setIsOpen] = useState(true);
+
+  // Passing onOpenChange renders a close button that calls it with false.
+  return (
+    <DialogHeroHeader
+      media={<Icon icon="success" size="lg" color="accent" />}
+      title="Payment successful"
+      subtitle="A receipt has been sent to your email."
+      onOpenChange={setIsOpen}
+    />
+  );
+}
+`,
+    },
+    {
+      label: 'Start-aligned',
+      code: `
+import {DialogHeroHeader} from '@astryxdesign/core/Dialog';
+
+<DialogHeroHeader
+  align="start"
+  eyebrow="New feature"
+  title="Introducing Insights"
+  subtitle="Track how your team uses the workspace over time."
+/>;
+`,
+    },
+  ],
+};
+
+export const docsZh = {
+  name: 'DialogHeroHeader',
+  isHiddenFromOverview: true,
+  displayName: 'Dialog Hero Header',
+  description:
+    '突出的英雄式对话框头部——DialogHeader 的高强调版本。在超大标题上方增加可选的媒体/视觉插槽和眉标，默认居中。适用于精选、营销或引导场景。',
+  props: [
+    {
+      name: 'title',
+      type: 'string',
+      description: '英雄（展示）尺寸的对话框标题（打开时获得焦点）。',
+    },
+    {
+      name: 'subtitle',
+      type: 'string',
+      description: '标题下方的支持性文字，使用次要颜色。',
+    },
+    {
+      name: 'eyebrow',
+      type: 'string',
+      description: '标题上方的简短眉标，使用强调色。',
+    },
+    {
+      name: 'media',
+      type: 'ReactNode',
+      description: '标题上方的视觉插槽（插画、图片或图标）。',
+    },
+    {
+      name: 'align',
+      type: "'center' | 'start'",
+      description: '英雄内容的水平对齐方式。',
+      default: "'center'",
+    },
+    {
+      name: 'onOpenChange',
+      type: '(isOpen: boolean) => unknown',
+      description: '关闭按钮的回调（省略时不显示按钮）。',
+    },
+    {
+      name: 'hasDivider',
+      type: 'boolean',
+      description: '在底部边缘添加分隔线。',
+      default: 'true',
+    },
+  ],
+};
+
+export const docsDense = {
+  name: 'DialogHeroHeader',
+  isHiddenFromOverview: true,
+  displayName: 'Dialog Hero Header',
+  description:
+    'prominent hero-style dialog header (sibling of DialogHeader) w/ media slot + eyebrow above display-scale title; centered by default',
+  propDescriptions: {
+    title:
+      'hero-scale dialog title (focused on open; labels dialog via aria-labelledby)',
+    subtitle: 'supporting text below title (secondary)',
+    eyebrow: 'short overline above title (accent)',
+    media: 'visual slot above title (illustration/image/icon)',
+    align: "content alignment: 'center' (default) | 'start'",
+    onOpenChange: 'close button callback (omit=no button)',
+    hasDivider: 'bottom border',
+  },
+};
diff --git a/packages/core/src/Dialog/DialogHeroHeader.test.tsx b/packages/core/src/Dialog/DialogHeroHeader.test.tsx
new file mode 100644
index 0000000000000..d02a22a0bd0a3
--- /dev/null
+++ b/packages/core/src/Dialog/DialogHeroHeader.test.tsx
@@ -0,0 +1,179 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file DialogHeroHeader.test.tsx
+ * @input Uses vitest, @testing-library/react, DialogHeroHeader component
+ * @output Unit tests for DialogHeroHeader component behavior
+ * @position Testing; validates DialogHeroHeader.tsx implementation
+ *
+ * SYNC: When DialogHeroHeader.tsx changes, update tests to match new behavior
+ */
+
+import {describe, it, expect, vi} from 'vitest';
+import {render, screen} from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import {DialogHeroHeader} from './DialogHeroHeader';
+import {LayoutDividerContext} from '../Layout/LayoutDividerContext';
+
+describe('DialogHeroHeader', () => {
+  it('renders the title', () => {
+    render(<DialogHeroHeader title="Welcome aboard" />);
+    expect(
+      screen.getByRole('heading', {level: 2, name: 'Welcome aboard'}),
+    ).toBeInTheDocument();
+  });
+
+  it('renders the title as an h2 element (display sizing preserves the element)', () => {
+    render(<DialogHeroHeader title="Title" />);
+    const heading = screen.getByRole('heading', {level: 2});
+    expect(heading.tagName).toBe('H2');
+  });
+
+  it('title has tabIndex=-1 for programmatic focus', () => {
+    render(<DialogHeroHeader title="Title" />);
+    const heading = screen.getByRole('heading', {level: 2});
+    expect(heading).toHaveAttribute('tabindex', '-1');
+  });
+
+  it('auto-focuses the title when mounted', () => {
+    render(<DialogHeroHeader title="Title" />);
+    const heading = screen.getByRole('heading', {level: 2});
+    expect(document.activeElement).toBe(heading);
+  });
+
+  it('renders subtitle when provided', () => {
+    render(
+      <DialogHeroHeader title="Title" subtitle="Supporting hero copy here" />,
+    );
+    expect(screen.getByText('Supporting hero copy here')).toBeInTheDocument();
+  });
+
+  it('does not render subtitle when not provided', () => {
+    render(<DialogHeroHeader title="Title" />);
+    expect(
+      screen.queryByText('Supporting hero copy here'),
+    ).not.toBeInTheDocument();
+  });
+
+  it('renders eyebrow when provided', () => {
+    render(<DialogHeroHeader title="Title" eyebrow="Welcome" />);
+    expect(screen.getByText('Welcome')).toBeInTheDocument();
+  });
+
+  it('does not render eyebrow when not provided', () => {
+    render(<DialogHeroHeader title="Title" />);
+    expect(screen.queryByText('Welcome')).not.toBeInTheDocument();
+  });
+
+  it('renders the media slot when provided', () => {
+    render(
+      <DialogHeroHeader
+        title="Title"
+        media={<img alt="Celebration illustration" src="/hero.png" />}
+      />,
+    );
+    expect(
+      screen.getByRole('img', {name: 'Celebration illustration'}),
+    ).toBeInTheDocument();
+  });
+
+  it('does not render a media slot when not provided', () => {
+    render(<DialogHeroHeader title="Title" />);
+    expect(screen.queryByRole('img')).not.toBeInTheDocument();
+  });
+
+  it('renders close button when onOpenChange is provided', () => {
+    render(<DialogHeroHeader title="Title" onOpenChange={() => {}} />);
+    expect(screen.getByRole('button', {name: /close/i})).toBeInTheDocument();
+  });
+
+  it('does not render close button when onOpenChange is not provided', () => {
+    render(<DialogHeroHeader title="Title" />);
+    expect(
+      screen.queryByRole('button', {name: /close/i}),
+    ).not.toBeInTheDocument();
+  });
+
+  it('calls onOpenChange(false) when close button is clicked', async () => {
+    const user = userEvent.setup();
+    const handleHide = vi.fn();
+    render(<DialogHeroHeader title="Title" onOpenChange={handleHide} />);
+
+    await user.click(screen.getByRole('button', {name: /close/i}));
+    expect(handleHide).toHaveBeenCalledTimes(1);
+    expect(handleHide).toHaveBeenCalledWith(false);
+  });
+
+  it('renders without divider by default (no context)', () => {
+    // Without context, hasDivider defaults to false — same classes as explicit hasDivider={false}
+    const {container: noCtx} = render(<DialogHeroHeader title="No ctx" />);
+    const {container: explicitFalse} = render(
+      <DialogHeroHeader title="Explicit false" hasDivider={false} />,
+    );
+    const noCtxHeader = noCtx.firstChild as HTMLElement;
+    const explicitFalseHeader = explicitFalse.firstChild as HTMLElement;
+    expect(noCtxHeader.className).toBe(explicitFalseHeader.className);
+  });
+
+  it('renders with divider when context defaultHasDividers is true', () => {
+    const {container: ctxTrue} = render(
+      <LayoutDividerContext value={{defaultHasDividers: true}}>
+        <DialogHeroHeader title="Ctx true" />
+      </LayoutDividerContext>,
+    );
+    const {container: explicitTrue} = render(
+      <DialogHeroHeader title="Explicit true" hasDivider={true} />,
+    );
+    const ctxHeader = ctxTrue.firstChild as HTMLElement;
+    const explicitHeader = explicitTrue.firstChild as HTMLElement;
+    expect(ctxHeader.className).toBe(explicitHeader.className);
+  });
+
+  it('explicit hasDivider={false} overrides context defaultHasDividers=true', () => {
+    const {container: overridden} = render(
+      <LayoutDividerContext value={{defaultHasDividers: true}}>
+        <DialogHeroHeader title="Overridden" hasDivider={false} />
+      </LayoutDividerContext>,
+    );
+    const {container: noDivider} = render(
+      <DialogHeroHeader title="No divider" hasDivider={false} />,
+    );
+    const overriddenHeader = overridden.firstChild as HTMLElement;
+    const noDividerHeader = noDivider.firstChild as HTMLElement;
+    expect(overriddenHeader.className).toBe(noDividerHeader.className);
+  });
+
+  it('renders media, eyebrow, title, subtitle, and close together', () => {
+    render(
+      <DialogHeroHeader
+        media={<img alt="Hero" src="/hero.png" />}
+        eyebrow="Welcome"
+        title="You're all set up"
+        subtitle="Invite your team to get started."
+        onOpenChange={() => {}}
+      />,
+    );
+    expect(screen.getByRole('img', {name: 'Hero'})).toBeInTheDocument();
+    expect(screen.getByText('Welcome')).toBeInTheDocument();
+    expect(
+      screen.getByRole('heading', {level: 2, name: "You're all set up"}),
+    ).toBeInTheDocument();
+    expect(
+      screen.getByText('Invite your team to get started.'),
+    ).toBeInTheDocument();
+    expect(screen.getByRole('button', {name: /close/i})).toBeInTheDocument();
+  });
+
+  it('start alignment produces different container classes than center', () => {
+    const {container: centered} = render(
+      <DialogHeroHeader title="Centered" align="center" />,
+    );
+    const {container: started} = render(
+      <DialogHeroHeader title="Started" align="start" />,
+    );
+    // The inner content container is the first child of LayoutHeader's inner.
+    const centeredInner = centered.querySelector('h2')?.parentElement;
+    const startedInner = started.querySelector('h2')?.parentElement;
+    expect(centeredInner?.className).not.toBe(startedInner?.className);
+  });
+});
diff --git a/packages/core/src/Dialog/DialogHeroHeader.tsx b/packages/core/src/Dialog/DialogHeroHeader.tsx
new file mode 100644
index 0000000000000..eeb0da223b779
--- /dev/null
+++ b/packages/core/src/Dialog/DialogHeroHeader.tsx
@@ -0,0 +1,265 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file DialogHeroHeader.tsx
+ * @input Uses React, useEffect, useRef, LayoutHeader, Button, Icon, Heading, Text, DialogContext
+ * @output Exports DialogHeroHeader component and DialogHeroHeaderProps
+ * @position Dialog hero header component; prominent sibling of DialogHeader for featured/onboarding dialogs
+ *
+ * The high-emphasis counterpart to DialogHeader: a larger, "hero" treatment
+ * for dialogs that open onto a featured/marketing/onboarding moment. Adds an
+ * optional media/visual slot and an eyebrow overline above a prominent title,
+ * and centers its content by default. Shares DialogHeader's contract — the
+ * title receives focus on open, names the parent Dialog via aria-labelledby,
+ * and the close button is onOpenChange-driven. Actions belong in LayoutFooter,
+ * not the header (Astryx's Layout owns the actions slot).
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/Dialog/Dialog.doc.mjs
+ * - /packages/core/src/Dialog/DialogHeroHeader.doc.mjs
+ * - /packages/core/src/Dialog/DialogHeroHeader.test.tsx
+ * - /packages/core/src/Dialog/index.ts
+ * - /apps/storybook/stories/DialogHeroHeader.stories.tsx
+ * - /packages/cli/templates/blocks/components/Dialog/ (Dialog-family showcase blocks)
+ * - /packages/cli/templates/blocks/components/DialogHeroHeader/ (showcase blocks)
+ */
+
+import {useEffect, useRef, type ReactNode} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import {spacingVars, sizeVars} from '../theme/tokens.stylex';
+import {LayoutHeader} from '../Layout/LayoutHeader';
+import {Button} from '../Button';
+import {Icon} from '../Icon';
+import {Heading} from '../Heading/Heading';
+import {Text} from '../Text/Text';
+import type {BaseProps} from '../BaseProps';
+import {useDialogContext} from './DialogContext';
+import {useTranslator} from '../i18n';
+
+const styles = stylex.create({
+  // Vertical stack of media, eyebrow, title, and subtitle. position:relative
+  // anchors the absolutely-positioned close button to the header edge.
+  container: {
+    position: 'relative',
+    display: 'flex',
+    flexDirection: 'column',
+    gap: spacingVars['--spacing-2'],
+  },
+  center: {
+    alignItems: 'center',
+  },
+  start: {
+    alignItems: 'flex-start',
+  },
+  // Reserve horizontal room so centered content never slides under the
+  // corner close button. Center reserves both sides to stay symmetric;
+  // start only needs the trailing edge cleared.
+  reserveBoth: {
+    paddingInline: sizeVars['--size-element-md'],
+  },
+  reserveEnd: {
+    paddingInlineEnd: sizeVars['--size-element-md'],
+  },
+  // Media/visual slot: illustration, image, or icon tile above the title.
+  media: {
+    display: 'flex',
+    // Extra breathing room below the visual before the text block.
+    marginBlockEnd: spacingVars['--spacing-2'],
+  },
+  titleFocusable: {
+    outline: 'none',
+  },
+  // Close button floats in the top-trailing corner (above any media). The
+  // negative offsets pull the icon button's visual edge out to the header's
+  // padded boundary — same optical compensation as DialogHeader.
+  closeButton: {
+    position: 'absolute',
+    insetBlockStart: `calc(-1 * ${spacingVars['--spacing-2']})`,
+    insetInlineEnd: `calc(-1 * ${spacingVars['--spacing-2']})`,
+  },
+});
+
+export interface DialogHeroHeaderProps extends BaseProps<HTMLDivElement> {
+  /** Ref forwarded to the root element */
+  ref?: React.Ref<HTMLDivElement>;
+
+  /**
+   * The title of the dialog, rendered at hero (display) scale.
+   * This title receives focus when the dialog opens for screen reader
+   * accessibility, and names the parent Dialog via aria-labelledby unless the
+   * consumer passes an explicit aria-label/aria-labelledby to the Dialog.
+   */
+  title: string;
+
+  /**
+   * Optional supporting text displayed below the title in secondary color.
+   * Use for a sentence or two of context on the featured moment.
+   */
+  subtitle?: string;
+
+  /**
+   * Optional short overline rendered above the title in accent color
+   * (e.g. a category, "New", or a step label).
+   */
+  eyebrow?: string;
+
+  /**
+   * Optional media/visual slot rendered above the eyebrow and title —
+   * an illustration, image, or icon tile. Provide your own sizing/visual;
+   * the header only positions it per `align`.
+   */
+  media?: ReactNode;
+
+  /**
+   * Horizontal alignment of the hero content.
+   * - `'center'` (default) — the classic centered hero treatment.
+   * - `'start'` — left-aligned (inline-start), like DialogHeader.
+   * @default 'center'
+   */
+  align?: 'center' | 'start';
+
+  /**
+   * Callback fired when the dialog visibility changes.
+   * Called with `false` when the close button is clicked.
+   * If not provided, no close button will be rendered.
+   */
+  onOpenChange?: (isOpen: boolean) => unknown;
+
+  /**
+   * Adds a themed border at the bottom edge.
+   * When false, spacing collapse is applied automatically for seamless visual flow.
+   * Defaults to the parent Layout's `defaultHasDividers` context value.
+   */
+  hasDivider?: boolean;
+}
+
+/**
+ * Prominent, "hero"-style header for Dialog — the high-emphasis sibling of
+ * DialogHeader.
+ *
+ * Renders an optional media/visual slot and eyebrow above a display-scale
+ * title, with optional supporting text, centered by default. Like
+ * DialogHeader, the title receives focus when a modal dialog opens (for
+ * screen reader accessibility; inline documentation previews suppress this
+ * autofocus), is an h2 with tabIndex={-1} so it can be programmatically
+ * focused without entering the tab order, and names the parent Dialog via
+ * aria-labelledby (unless the Dialog receives an explicit
+ * aria-label/aria-labelledby). The close button is onOpenChange-driven.
+ *
+ * Uses LayoutHeader internally for consistent styling with other layout
+ * headers. Actions (CTAs) belong in LayoutFooter, not here.
+ *
+ * @example
+ * ```
+ * <Dialog isOpen={isOpen} onOpenChange={open => setIsOpen(open)}>
+ *   <Layout
+ *     header={
+ *       <DialogHeroHeader
+ *         media={<Icon icon="success" size="lg" color="accent" />}
+ *         eyebrow="Welcome"
+ *         title="You're all set up"
+ *         subtitle="Your workspace is ready. Invite your team to get started."
+ *         onOpenChange={open => setIsOpen(open)}
+ *       />
+ *     }
+ *     content={<LayoutContent>Content</LayoutContent>}
+ *     footer={<LayoutFooter hasDivider>Actions</LayoutFooter>}
+ *   />
+ * </Dialog>
+ * ```
+ */
+export function DialogHeroHeader({
+  title,
+  subtitle,
+  eyebrow,
+  media,
+  align = 'center',
+  onOpenChange,
+  hasDivider,
+  xstyle,
+  className,
+  style,
+  ref,
+  ...rest
+}: DialogHeroHeaderProps) {
+  const t = useTranslator();
+  const titleRef = useRef<HTMLHeadingElement>(null);
+  const dialogContext = useDialogContext();
+  const shouldAutoFocus = dialogContext?.isInline !== true;
+  const titleId = dialogContext?.titleId;
+  const isCentered = align === 'center';
+  const justify = isCentered ? 'center' : 'start';
+
+  // Auto-focus the title when mounted for screen reader accessibility.
+  // Inline dialogs are documentation/showcase previews, so suppress focus to
+  // avoid stealing scroll position from the surrounding page. Mirrors
+  // DialogHeader — the parent Dialog detects this title (by `titleId`) via a
+  // callback ref to set its default aria-labelledby.
+  useEffect(() => {
+    if (shouldAutoFocus && titleRef.current) {
+      titleRef.current.focus();
+    }
+  }, [shouldAutoFocus]);
+
+  return (
+    <LayoutHeader
+      ref={ref}
+      hasDivider={hasDivider}
+      xstyle={xstyle}
+      className={className}
+      style={style}
+      {...rest}>
+      <div
+        {...stylex.props(
+          styles.container,
+          isCentered ? styles.center : styles.start,
+          onOpenChange && (isCentered ? styles.reserveBoth : styles.reserveEnd),
+        )}>
+        {media && <div {...stylex.props(styles.media)}>{media}</div>}
+        {eyebrow && (
+          <Text
+            type="label"
+            size="sm"
+            color="accent"
+            weight="semibold"
+            justify={justify}>
+            {eyebrow}
+          </Text>
+        )}
+        <Heading
+          ref={titleRef}
+          id={titleId}
+          level={2}
+          type="display-3"
+          tabIndex={-1}
+          justify={justify}
+          textWrap="balance"
+          xstyle={styles.titleFocusable}>
+          {title}
+        </Heading>
+        {subtitle && (
+          <Text type="body" color="secondary" justify={justify}>
+            {subtitle}
+          </Text>
+        )}
+        {onOpenChange && (
+          <Button
+            variant="ghost"
+            label={t('@astryx.dialog.close')}
+            tooltip={t('@astryx.dialog.close')}
+            icon={<Icon icon="close" color="inherit" />}
+            onClick={() => {
+              onOpenChange?.(false);
+            }}
+            isIconOnly
+            xstyle={styles.closeButton}
+          />
+        )}
+      </div>
+    </LayoutHeader>
+  );
+}
+
+DialogHeroHeader.displayName = 'DialogHeroHeader';
diff --git a/packages/core/src/Dialog/index.ts b/packages/core/src/Dialog/index.ts
index c22836ebb37dc..d2c9fc37cd892 100644
--- a/packages/core/src/Dialog/index.ts
+++ b/packages/core/src/Dialog/index.ts
@@ -5,7 +5,7 @@
 /**
  * @file index.ts
  * @input Imports Dialog component and types from Dialog.tsx
- * @output Exports Dialog, DialogHeader, and related types
+ * @output Exports Dialog, DialogHeader, DialogHeroHeader, and related types
  * @position Component entry point; re-exported by /packages/core/src/index.ts
  *
  * SYNC: When modified, update this header and /packages/core/src/Dialog/Dialog.doc.mjs
@@ -23,5 +23,8 @@ export type {
 export {DialogHeader} from './DialogHeader';
 export type {DialogHeaderProps} from './DialogHeader';
 
+export {DialogHeroHeader} from './DialogHeroHeader';
+export type {DialogHeroHeaderProps} from './DialogHeroHeader';
+
 export {useImperativeDialog} from './useImperativeDialog';
 export type {ImperativeDialogReturn} from './useImperativeDialog';