[Lee-Dongwook]

Issue

#4182

Summary

Adds DialogHeroHeader — a prominent, "hero"-style header for Dialog, the high-emphasis sibling of DialogHeader. It's for dialogs that open onto a featured/marketing/onboarding moment (illustration or icon, larger title, supporting copy), where the compact DialogHeader is too understated.

Ported the value and behavior of the internal XDSModalHeroHeader, mapped to Astryx conventions (Modal → Dialog).

Placement

Lands as a Dialog sub-component in @astryxdesign/core (alongside
DialogHeader), not in lab. DialogHeroHeader needs the internal
DialogContext for the aria-labelledby title handshake and inline-preview
autofocus suppression — the same contract DialogHeader relies on. Putting it
in lab would have meant widening core's public API to export DialogContext;
keeping it in core avoids that and makes it a true sibling.

Anatomy / API

A superset-ish sibling of DialogHeader — same title, subtitle,
onOpenChange, hasDivider, plus hero-only slots:

• title — display-scale heading (h2 element, display-3 sizing), receives
  focus on open and names the dialog via aria-labelledby
• subtitle — supporting text (secondary)
• eyebrow — short overline above the title (accent)
• media — visual slot above the title (illustration / image / icon)
• align — 'center' (default) | 'start'
• onOpenChange — close-button callback (omit = no button), identical to
  DialogHeader
• hasDivider — inherits the Layout divider context

Actions (CTAs) intentionally stay in LayoutFooter, per Astryx's Layout model —
the header doesn't take an actions slot.

Composes entirely from existing primitives (Heading, Text, Button, Icon,
LayoutHeader); StyleX + semantic tokens only; BaseProps escape hatches,
displayName, 'use client'.

What's included

• DialogHeroHeader.tsx implementation
• Colocated DialogHeroHeader.test.tsx (18 tests)
• DialogHeroHeader.doc.mjs (docs / docsZh / docsDense)
• index.ts export wired; Dialog.doc.mjs sub-component + anatomy note
• Storybook story (DialogHeroHeader.stories.tsx)
• Showcase blocks (Basic + Showcase)
• xle registry alias (DHH) and a changeset

Testing

• vitest Dialog suite: 70 passed (incl. 18 new)
• tsc --noEmit: 0 errors
• prettier --check, eslint, pnpm check:repo (sync/boundaries/changesets):
  all clean

Screenshot

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
astryx	Ready	Preview, Comment	Jul 29, 2026 1:53am

[github-actions]

PR Analysis Report

Modified Components

Dialog

Metric	Before	After	Delta
Bundle Size (ESM)	N/A	N/A	N/A
Lines of Code	N/A	757	-
Complexity	N/A	Very High (97)	-

Bundle Size Summary

Package	Size (ESM)	Size (CJS)	Gzipped
@astryxdesign/core	N/A	4.7KB	0B

Accessibility Audit

Status: No accessibility violations detected.

---

_{Generated by PR Enrichment workflow | View full report}

[cixzhang]

Going with #5105 for this one — lab first, so we can adjust the API before it becomes permanent surface.

Your placement analysis was the sharpest thing on this issue: lab needs DialogContext for the aria-labelledby handshake and the autofocus suppression, and that means widening core. You were right, and #5105 pays exactly that cost — a new @astryxdesign/core/Dialog/DialogContext subpath export. We're taking it because a hero header still has open questions (media mode for the close button over light/dark media), and those are cheaper to answer in lab.

Thanks for the port — the behaviour mapping from the internal component was accurate.

[Reviewed by Robohands]