Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

feat(Dialog): expose DialogHeader theme targets (#6240)

ksying224b530656ea
diff --git a/.changeset/dialog-header-theme-targets.md b/.changeset/dialog-header-theme-targets.md
new file mode 100644
index 0000000000..db96bffbaa
--- /dev/null
+++ b/.changeset/dialog-header-theme-targets.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[feature] DialogHeader exposes theme targets for its header gap, title/subtitle gap, and close-icon size.
+
+@ksying
diff --git a/packages/cli/foundation/discovery/theming-targets.test.mjs b/packages/cli/foundation/discovery/theming-targets.test.mjs
index 0377a1dae4..34623084e1 100644
--- a/packages/cli/foundation/discovery/theming-targets.test.mjs
+++ b/packages/cli/foundation/discovery/theming-targets.test.mjs
@@ -258,6 +258,35 @@ describe('collectThemingTargets', () => {
},
);
+ it('keeps DialogHeader theming metadata available in its direct doc', async () => {
+ const doc = await loadComponentDoc(
+ path.join(coreSrc, 'Dialog', 'DialogHeader.doc.mjs'),
+ );
+ expect(doc.subComponentOf).toBe('Dialog');
+ expect(doc.theming.targets).toEqual([
+ {className: 'astryx-dialog-header'},
+ {className: 'astryx-dialog-header-title-block'},
+ {className: 'astryx-dialog-header-close-icon'},
+ ]);
+ });
+
+ it.each([
+ 'dialog-header',
+ 'dialog-header-title-block',
+ 'dialog-header-close-icon',
+ ])('enumerates %s once under its canonical Dialog owner', async key => {
+ const matches = (await enumerated).filter(target => target.key === key);
+ expect(matches).toEqual([
+ {
+ key,
+ className: `astryx-${key}`,
+ component: 'Dialog',
+ props: [],
+ states: [],
+ },
+ ]);
+ });
+
it.each(['table-header', 'table-body', 'table-footer'])(
'enumerates %s once under its canonical Table owner',
async key => {
diff --git a/packages/core/src/Dialog/Dialog.doc.mjs b/packages/core/src/Dialog/Dialog.doc.mjs
index 78f3fc230e..15ca9414a4 100644
--- a/packages/core/src/Dialog/Dialog.doc.mjs
+++ b/packages/core/src/Dialog/Dialog.doc.mjs
@@ -30,6 +30,9 @@ export const docs = {
container: true,
targets: [
{className: 'astryx-dialog', visualProps: ['variant']},
+ {className: 'astryx-dialog-header'},
+ {className: 'astryx-dialog-header-title-block'},
+ {className: 'astryx-dialog-header-close-icon'},
],
vars: [
{name: '--_dialog-radius', description: 'Border radius of the dialog', default: 'var(--radius-container)', private: true},
diff --git a/packages/core/src/Dialog/Dialog.spec.md b/packages/core/src/Dialog/Dialog.spec.md
index ca21369ab7..486e3f9812 100644
--- a/packages/core/src/Dialog/Dialog.spec.md
+++ b/packages/core/src/Dialog/Dialog.spec.md
@@ -17,7 +17,7 @@ verified_by:
packages/core/src/Dialog/__tests__/Dialog.a11y.test.tsx,
packages/core/src/Dialog/__tests__/Dialog.a11y.chromium.spec.ts,
]
-modules: []
+modules: [module:Dialog/DialogHeader]
families: [family:overlay-dismissal]
design_specs: []
architecture:
diff --git a/packages/core/src/Dialog/DialogHeader.doc.mjs b/packages/core/src/Dialog/DialogHeader.doc.mjs
index 876cde22a6..609191a793 100644
--- a/packages/core/src/Dialog/DialogHeader.doc.mjs
+++ b/packages/core/src/Dialog/DialogHeader.doc.mjs
@@ -8,6 +8,14 @@ export const docs = {
displayName: 'Dialog Header',
isHiddenFromOverview: true,
description: 'Header for dialogs with a title, optional subtitle, close button, and start/end content slots.',
+ usage: {
+ description: 'Use DialogHeader to give a dialog a labelled title area and optional close control.',
+ anatomy: [
+ {name: 'Header row', required: true, description: 'Arranges the title block, optional start/end content, and close control.'},
+ {name: 'Title block', required: true, description: 'Groups the title and optional subtitle.'},
+ {name: 'Close icon', required: false, description: 'Visual close glyph inside the close button.'},
+ ],
+ },
props: [
{
name: 'title',
@@ -72,6 +80,13 @@ export const docs = {
hasDivider: true,
},
},
+ theming: {
+ targets: [
+ {className: 'astryx-dialog-header'},
+ {className: 'astryx-dialog-header-title-block'},
+ {className: 'astryx-dialog-header-close-icon'},
+ ],
+ },
examples: [
{
label: 'Basic',
@@ -117,6 +132,14 @@ export const docsZh = {
isHiddenFromOverview: true,
displayName: 'Dialog Header',
description: '对话框头部,包含标题、可选副标题、关闭按钮以及首尾内容插槽。',
+ usage: {
+ description: '使用 DialogHeader 为对话框提供带标签的标题区和可选的关闭控件。',
+ anatomy: [
+ {name: 'Header row', required: true, description: '排列标题区、可选的首尾内容和关闭控件。'},
+ {name: 'Title block', required: true, description: '组合标题和可选副标题。'},
+ {name: 'Close icon', required: false, description: '关闭按钮内的关闭图标。'},
+ ],
+ },
props: [
{
name: 'title',
@@ -150,6 +173,13 @@ export const docsZh = {
default: 'true',
},
],
+ theming: {
+ targets: [
+ {className: 'astryx-dialog-header'},
+ {className: 'astryx-dialog-header-title-block'},
+ {className: 'astryx-dialog-header-close-icon'},
+ ],
+ },
};
export const docsDense = {
@@ -157,6 +187,14 @@ export const docsDense = {
isHiddenFromOverview: true,
displayName: 'Dialog Header',
description: 'dialog header w/ title, optional subtitle, close button, start/end content slots',
+ usage: {
+ description: 'labelled dialog title area + optional close control',
+ anatomy: [
+ {name: 'Header row', required: true, description: 'arranges title block, optional start/end content, close control'},
+ {name: 'Title block', required: true, description: 'groups title + optional subtitle'},
+ {name: 'Close icon', required: false, description: 'close glyph inside close button'},
+ ],
+ },
propDescriptions: {
title: 'dialog title (focused on open; labels dialog via aria-labelledby)',
subtitle: 'subtitle below title',
diff --git a/packages/core/src/Dialog/DialogHeader.test.tsx b/packages/core/src/Dialog/DialogHeader.test.tsx
index f012b58f51..168c39a0b5 100644
--- a/packages/core/src/Dialog/DialogHeader.test.tsx
+++ b/packages/core/src/Dialog/DialogHeader.test.tsx
@@ -14,6 +14,13 @@ import {render, screen} from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import {DialogHeader} from './DialogHeader';
import {LayoutDividerContext} from '../Layout/LayoutDividerContext';
+import {defineTheme} from '../theme/defineTheme';
+import {generateThemeCSS} from '../theme/generateThemeRules';
+
+function generateThemeTestCSS(theme: Parameters<typeof generateThemeCSS>[0]) {
+ const {prose, component} = generateThemeCSS(theme);
+ return [prose, component].filter(Boolean).join('\n\n');
+}
describe('DialogHeader', () => {
it('renders the title', () => {
@@ -56,6 +63,48 @@ describe('DialogHeader', () => {
expect(screen.getByRole('button', {name: /close/i})).toBeInTheDocument();
});
+ it('exposes theme targets for the header row, title block, and close icon', () => {
+ const {container} = render(
+ <DialogHeader
+ title="Title"
+ subtitle="Subtitle"
+ onOpenChange={() => {}}
+ />,
+ );
+
+ expect(container.querySelector('.astryx-dialog-header')).not.toBeNull();
+ expect(screen.getByRole('heading', {level: 2}).parentElement).toHaveClass(
+ 'astryx-dialog-header-title-block',
+ );
+
+ const closeIcon = screen
+ .getByRole('button', {name: /close/i})
+ .querySelector('.astryx-dialog-header-close-icon');
+ expect(closeIcon).toHaveClass('astryx-icon');
+ });
+
+ it('lets themes set the two internal gaps and close-icon size', () => {
+ const theme = defineTheme({
+ name: 'dialog-header-targets-test',
+ components: {
+ 'dialog-header': {base: {gap: '8px'}},
+ 'dialog-header-title-block': {base: {gap: '4px'}},
+ 'dialog-header-close-icon': {
+ base: {width: '16px', height: '16px', fontSize: '16px'},
+ },
+ },
+ });
+ const css = generateThemeTestCSS(theme);
+
+ expect(css).toContain('.astryx-dialog-header {');
+ expect(css).toContain('gap: 8px');
+ expect(css).toContain('.astryx-dialog-header-title-block {');
+ expect(css).toContain('gap: 4px');
+ expect(css).toContain('.astryx-dialog-header-close-icon {');
+ expect(css).toContain('width: 16px');
+ expect(css).toContain('height: 16px');
+ });
+
it('does not render close button when onOpenChange is not provided', () => {
render(<DialogHeader title="Title" />);
expect(
diff --git a/packages/core/src/Dialog/DialogHeader.tsx b/packages/core/src/Dialog/DialogHeader.tsx
index d32c2e88cd..5f37e4c238 100644
--- a/packages/core/src/Dialog/DialogHeader.tsx
+++ b/packages/core/src/Dialog/DialogHeader.tsx
@@ -4,7 +4,7 @@
/**
* @file DialogHeader.tsx
- * @input Uses React, useEffect, useRef, LayoutHeader, Button, Icon, Heading, Text, DialogContext
+ * @input Uses React, StyleX, LayoutHeader, Button, Icon, Heading, Text, DialogContext, mergeProps, themeProps
* @output Exports DialogHeader component and DialogHeaderProps
* @position Dialog header component; used with Dialog and Layout
*
@@ -25,6 +25,8 @@ import {Icon} from '../Icon';
import {Heading} from '../Heading/Heading';
import {Text} from '../Text/Text';
import type {BaseProps} from '../BaseProps';
+import {mergeProps} from '../utils';
+import {themeProps} from '../utils/themeProps';
import {useDialogContext} from './DialogContext';
import {useTranslator} from '../i18n';
@@ -41,6 +43,9 @@ const styles = stylex.create({
marginInlineEnd: `calc(-1 * ${spacingVars['--spacing-2']})`,
},
titleWrapper: {
+ display: 'flex',
+ flexDirection: 'column',
+ gap: spacingVars['--spacing-0'],
flex: 1,
minWidth: 0,
// Visual centering: align title center with close button center
@@ -161,11 +166,19 @@ export function DialogHeader({
className={className}
style={style}
{...rest}>
- <div {...stylex.props(styles.container)}>
+ <div
+ {...mergeProps(
+ themeProps('dialog-header'),
+ stylex.props(styles.container),
+ )}>
{startContent && (
<div {...stylex.props(styles.actions)}>{startContent}</div>
)}
- <div {...stylex.props(styles.titleWrapper)}>
+ <div
+ {...mergeProps(
+ themeProps('dialog-header-title-block'),
+ stylex.props(styles.titleWrapper),
+ )}>
<Heading
ref={titleRef}
id={titleId}
@@ -192,7 +205,13 @@ export function DialogHeader({
variant="ghost"
label={t('@astryx.dialog.close')}
tooltip={t('@astryx.dialog.close')}
- icon={<Icon icon="close" color="inherit" />}
+ icon={
+ <Icon
+ icon="close"
+ color="inherit"
+ {...themeProps('dialog-header-close-icon')}
+ />
+ }
onClick={() => {
onOpenChange?.(false);
}}
diff --git a/packages/core/src/Dialog/modules/DialogHeader.spec.md b/packages/core/src/Dialog/modules/DialogHeader.spec.md
new file mode 100644
index 0000000000..14d3ed51d2
--- /dev/null
+++ b/packages/core/src/Dialog/modules/DialogHeader.spec.md
@@ -0,0 +1,152 @@
+---
+schema_version: 3
+template_version: 1
+kind: module
+id: module:Dialog/DialogHeader
+authority: current
+archive_reason: null
+superseded_by: null
+approved_by: cixzhang
+approved_at: 2026-09-14
+owners: [cixzhang, imdreamrunner]
+review_triggers: [theming, layout]
+verified_by:
+ [
+ packages/core/src/Dialog/DialogHeader.test.tsx,
+ packages/core/src/theme/themingTargets.test.ts,
+ scripts/check-knowledge.mjs,
+ ]
+parent_component: component:Dialog
+references: [architecture:component-theming-surface]
+---
+
+# DialogHeader module contract
+
+## Intent
+
+`DialogHeader` presents the title region of a Dialog and its optional close
+control. This record owns the stable header-row, title-block, and close-icon
+anatomy and their public theming targets.
+
+## Compatibility and migration
+
+- Released default preserved: `yes`
+- Compatibility class: additive theme targets only; default layout, paint,
+ interaction, accessibility, and public props remain unchanged
+- Migration decision: none
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Ownership boundary
+
+**Owns**
+
+- The header row that arranges title content and trailing controls.
+- The title block that groups the title and optional subtitle.
+- The close icon rendered for the optional close action.
+- The `dialog-header`, `dialog-header-title-block`, and
+ `dialog-header-close-icon` targets.
+
+**Does not own / non-goals**
+
+- Dialog modality, dismissal policy, or focus lifecycle — owned by
+ `component:Dialog` and its linked system records.
+- Generic Button or Icon presentation outside this module — owned by those
+ components.
+- New public props or default visual changes.
+
+## Public API and concepts
+
+No component prop changes. This contract adds three public theming surfaces for
+existing anatomy.
+
+| Concept | Closed values or states | Meaning | Default | Owner | Stability |
+| --- | --- | --- | --- | --- | --- |
+| Header row target | present | Styles the row that arranges title content and controls | Existing row visuals | `module:Dialog/DialogHeader` | stable |
+| Title block target | present | Styles the title/subtitle grouping element | Existing title stack visuals | `module:Dialog/DialogHeader` | stable |
+| Close icon target | present when close action renders | Styles the close glyph itself | Existing medium Icon visuals | `module:Dialog/DialogHeader` | stable |
+
+## Behavioral contract
+
+| ID | Invariant | Basis | Review state |
+| --- | --- | --- | --- |
+| FR1 | The header row MUST carry `dialog-header` on the element that applies its row layout and gap. | Current implementation and owner decision | settled |
+| FR2 | The title block MUST carry `dialog-header-title-block` on the element that applies its title/subtitle layout and gap. | Current implementation and owner decision | settled |
+| FR3 | The rendered close Icon MUST carry `dialog-header-close-icon` on the glyph element that applies icon presentation. | Current implementation and owner decision | settled |
+| FR4 | Omitting `onOpenChange` MUST continue to omit the close action and its optional close-icon anatomy. | Released behavior | settled |
+
+### Transformation and precedence order
+
+- The module applies each target to its owning element before normal theme CSS
+ resolves through the shared theming pipeline.
+
+### Performance and resources
+
+- The additive class names and metadata introduce no listener, observer, timer,
+ measurement, or asynchronous resource.
+
+## Accessibility contract
+
+- Theme targets MUST NOT change the title's role, focus behavior, dialog naming,
+ or the close button's accessible name and operation.
+
+## Design relationships
+
+| Anatomy or state | Design requirement | Representation authority | Module contract |
+| --- | --- | --- | --- |
+| Header row | Owns arrangement and spacing among title content and controls. | This module | FR1 |
+| Title block | Owns title/subtitle grouping and spacing. | This module | FR2 |
+| Close icon | Owns the close glyph's visual box inside the Button-owned action. | This module with Icon rendering | FR3, FR4 |
+
+### Theming anatomy
+
+<!-- anatomy-theming:v1 -->
+
+```json
+{
+ "Header row": {"target": "dialog-header"},
+ "Title block": {"target": "dialog-header-title-block"},
+ "Close icon": {"target": "dialog-header-close-icon"}
+}
+```
+
+## Parent and system relationships
+
+- `component:Dialog` owns modal behavior and the aggregate Dialog contract.
+- `component:Layout` owns the composed LayoutHeader region outside the three
+ module-owned inner parts.
+- `component:Button` owns the close action's control behavior and outer button
+ presentation.
+- `component:Icon` renders the glyph; this module guarantees a distinct target
+ for the close icon's DialogHeader-specific visual contract.
+- `architecture:component-theming-surface` owns target qualification, anatomy
+ mapping, and the requirement that each target sits on its painter.
+
+## Verification map
+
+| Contract | Verification | Representative states | Mutation or failure expectation |
+| --- | --- | --- | --- |
+| FR1–FR3 | `DialogHeader.test.tsx`, target inventory, generated probe theme, and source inspection | title only, title/subtitle, close action | A target is missing, undocumented, or moved away from its owning painter. |
+| FR4 | Existing close-button presence tests | with and without `onOpenChange` | The optional target renders without the optional close action. |
+| Theming anatomy map | `scripts/check-knowledge.mjs` | all three module anatomy entries and targets | Anatomy, docs, runtime targets, and the module map drift. |
+
+## Decision log
+
+### DEC-1 — Header targets follow stable anatomy and visual ownership
+
+**Reference:** `module:Dialog/DialogHeader/DEC-1`
+**Decider:** cixzhang, 2026-09-14
+
+Each public target represents documented anatomy and is applied to the element
+that owns the corresponding visuals. The header row, title block, and close icon
+meet that admission rule and are approved as additive targets.
+
+## Open questions
+
+None.
+
+## Content boundary
+
+This record does not duplicate consumer signatures/examples, parent Dialog
+behavior, implementation steps, or shared theming rules. It links to their
+canonical owners.
diff --git a/packages/themes/probe/src/probeTheme.ts b/packages/themes/probe/src/probeTheme.ts
index e67c09d5fa..8f88b9d7d2 100644
--- a/packages/themes/probe/src/probeTheme.ts
+++ b/packages/themes/probe/src/probeTheme.ts
@@ -6,7 +6,7 @@
// test fixture. Regenerate with: pnpm visual:probe-theme
//
// defineTheme takes six things and this covers all six:
-// components 278 targets, 906 selectors (generated from the docs)
+// components 282 targets, 913 selectors (generated from the docs)
// tokens custom properties, read back off the themed element
// icons every registry entry swapped for a marked glyph
// indicators check / radio / checkbox swapped — the swap that reaches furthest
@@ -2052,6 +2052,30 @@ export const probeTheme = defineTheme({
outlineColor: 'hsl(240.3 74% 25%)',
},
},
+ 'dialog-header': {
+ base: {
+ backgroundColor: 'hsl(312.1 73% 56%)',
+ color: 'hsl(253.8 72% 12%)',
+ borderColor: 'hsl(79.0 70% 25%)',
+ outlineColor: 'hsl(252.5 77% 25%)',
+ },
+ },
+ 'dialog-header-close-icon': {
+ base: {
+ backgroundColor: 'hsl(90.9 85% 52%)',
+ color: 'hsl(55.2 71% 12%)',
+ borderColor: 'hsl(180.8 84% 25%)',
+ outlineColor: 'hsl(215.4 89% 25%)',
+ },
+ },
+ 'dialog-header-title-block': {
+ base: {
+ backgroundColor: 'hsl(279.3 88% 58%)',
+ color: 'hsl(210.9 80% 12%)',
+ borderColor: 'hsl(219.8 84% 25%)',
+ outlineColor: 'hsl(358.8 73% 25%)',
+ },
+ },
divider: {
base: {
backgroundColor: 'hsl(26.4 77% 53%)',
@@ -3973,6 +3997,32 @@ export const probeTheme = defineTheme({
outlineColor: 'hsl(58.8 73% 25%)',
},
},
+ 'scrollable-area': {
+ base: {
+ backgroundColor: 'hsl(170.2 82% 57%)',
+ color: 'hsl(26.0 76% 12%)',
+ borderColor: 'hsl(40.8 70% 25%)',
+ outlineColor: 'hsl(17.3 90% 25%)',
+ },
+ 'axis:inline': {
+ backgroundColor: 'hsl(118.1 92% 62%)',
+ color: 'hsl(340.0 75% 12%)',
+ borderColor: 'hsl(98.6 94% 25%)',
+ outlineColor: 'hsl(163.6 70% 25%)',
+ },
+ 'axis:block': {
+ backgroundColor: 'hsl(310.5 79% 45%)',
+ color: 'hsl(156.4 74% 12%)',
+ borderColor: 'hsl(34.4 81% 25%)',
+ outlineColor: 'hsl(180.6 89% 25%)',
+ },
+ 'axis:both': {
+ backgroundColor: 'hsl(170.0 84% 52%)',
+ color: 'hsl(112.4 74% 12%)',
+ borderColor: 'hsl(281.8 89% 25%)',
+ outlineColor: 'hsl(288.5 81% 25%)',
+ },
+ },
section: {
base: {
backgroundColor: 'hsl(337.5 74% 48%)',