@astryxdesign/core 0.6.2 → 0.6.3-canary.0899f21

package/src/Dialog/DialogHeader.doc.mjs

@@ -12,7 +12,9 @@ export const docs = {
     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: 'Start content', required: false, description: 'Wraps optional leading content.'},
       {name: 'Title block', required: true, description: 'Groups the title and optional subtitle.'},
+      {name: 'End content', required: false, description: 'Groups optional trailing content with the optional close control.'},
       {name: 'Close icon', required: false, description: 'Visual close glyph inside the close button.'},
     ],
   },
@@ -66,6 +68,11 @@ export const docs = {
         },
       ],
     },
+    {
+      name: 'endContentEdgeCompensation',
+      type: "'inline' | 'block' | 'all'",
+      description: 'Selects compensation axes for the end-content slot. Omit to preserve automatic close-action compensation.',
+    },
     {
       name: 'hasDivider',
       type: 'boolean',
@@ -83,7 +90,9 @@ export const docs = {
   theming: {
     targets: [
       {className: 'astryx-dialog-header'},
+      {className: 'astryx-dialog-header-start-content'},
       {className: 'astryx-dialog-header-title-block'},
+      {className: 'astryx-dialog-header-end-content'},
       {className: 'astryx-dialog-header-close-icon'},
     ],
   },
@@ -136,7 +145,9 @@ export const docsZh = {
     description: '使用 DialogHeader 为对话框提供带标签的标题区和可选的关闭控件。',
     anatomy: [
       {name: 'Header row', required: true, description: '排列标题区、可选的首尾内容和关闭控件。'},
+      {name: 'Start content', required: false, description: '包装可选的首部内容。'},
       {name: 'Title block', required: true, description: '组合标题和可选副标题。'},
+      {name: 'End content', required: false, description: '组合可选尾部内容和可选关闭控件。'},
       {name: 'Close icon', required: false, description: '关闭按钮内的关闭图标。'},
     ],
   },
@@ -166,6 +177,11 @@ export const docsZh = {
       type: 'ReactNode',
       description: '标题之后、关闭按钮之前的内容。',
     },
+    {
+      name: 'endContentEdgeCompensation',
+      type: "'inline' | 'block' | 'all'",
+      description: '选择尾部内容插槽的补偿轴；省略时保留关闭操作的自动补偿。',
+    },
     {
       name: 'hasDivider',
       type: 'boolean',
@@ -176,7 +192,9 @@ export const docsZh = {
   theming: {
     targets: [
       {className: 'astryx-dialog-header'},
+      {className: 'astryx-dialog-header-start-content'},
       {className: 'astryx-dialog-header-title-block'},
+      {className: 'astryx-dialog-header-end-content'},
       {className: 'astryx-dialog-header-close-icon'},
     ],
   },
@@ -191,7 +209,9 @@ export const docsDense = {
     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: 'Start content', required: false, description: 'wraps optional leading content'},
       {name: 'Title block', required: true, description: 'groups title + optional subtitle'},
+      {name: 'End content', required: false, description: 'groups optional trailing content + optional close control'},
       {name: 'Close icon', required: false, description: 'close glyph inside close button'},
     ],
   },
@@ -201,6 +221,8 @@ export const docsDense = {
     onOpenChange: 'close button callback (omit=no button)',
     startContent: 'content before title (e.g. back button)',
     endContent: 'content after title, before close button',
+    endContentEdgeCompensation:
+      'end-content slot axes: inline | block | all; omit=automatic close-action compensation',
     hasDivider: 'bottom border',
   },
 };

package/src/Dialog/DialogHeader.test.tsx

@@ -22,6 +22,17 @@ function generateThemeTestCSS(theme: Parameters<typeof generateThemeCSS>[0]) {
   return [prose, component].filter(Boolean).join('\n\n');
 }
 
+function getEndSlot(): HTMLElement {
+  const child =
+    screen.queryByRole('button', {name: 'Action'}) ??
+    screen.getByRole('button', {name: /close/i});
+  const slot = child.parentElement;
+  if (slot == null) {
+    throw new Error('Expected DialogHeader end slot');
+  }
+  return slot;
+}
+
 describe('DialogHeader', () => {
   it('renders the title', () => {
     render(<DialogHeader title="My Dialog Title" />);
@@ -60,35 +71,184 @@ describe('DialogHeader', () => {
 
   it('renders close button when onOpenChange is provided', () => {
     render(<DialogHeader title="Title" onOpenChange={() => {}} />);
-    expect(screen.getByRole('button', {name: /close/i})).toBeInTheDocument();
+    const closeButton = screen.getByRole('button', {name: /close/i});
+
+    expect(closeButton).toBeInTheDocument();
+    expect(closeButton.parentElement).toHaveClass(
+      'astryx-dialog-header-end-content',
+    );
+  });
+
+  it('preserves automatic end-slot compensation when the close action renders', () => {
+    const {rerender} = render(
+      <DialogHeader title="Title" onOpenChange={() => {}} />,
+    );
+    const automaticClassName = getEndSlot().className;
+
+    rerender(
+      <DialogHeader
+        title="Title"
+        endContent={<button type="button">Action</button>}
+        onOpenChange={() => {}}
+      />,
+    );
+    expect(getEndSlot().className).toBe(automaticClassName);
+
+    rerender(
+      <DialogHeader
+        title="Title"
+        endContent={<button type="button">Action</button>}
+      />,
+    );
+    expect(getEndSlot().className).not.toBe(automaticClassName);
   });
 
-  it('exposes theme targets for the header row, title block, and close icon', () => {
+  it('lets endContentEdgeCompensation select inline, block, or all', () => {
+    const {rerender} = render(
+      <DialogHeader
+        title="Title"
+        endContent={<button type="button">Action</button>}
+      />,
+    );
+    const noCompensationClassName = getEndSlot().className;
+
+    rerender(
+      <DialogHeader
+        title="Title"
+        endContent={<button type="button">Action</button>}
+        endContentEdgeCompensation="inline"
+      />,
+    );
+    const inlineClassName = getEndSlot().className;
+
+    rerender(
+      <DialogHeader
+        title="Title"
+        endContent={<button type="button">Action</button>}
+        endContentEdgeCompensation="block"
+      />,
+    );
+    const blockClassName = getEndSlot().className;
+
+    rerender(
+      <DialogHeader
+        title="Title"
+        endContent={<button type="button">Action</button>}
+        endContentEdgeCompensation="all"
+      />,
+    );
+    const allClassName = getEndSlot().className;
+
+    expect(inlineClassName).not.toBe(noCompensationClassName);
+    expect(blockClassName).not.toBe(noCompensationClassName);
+    expect(inlineClassName).not.toBe(blockClassName);
+    expect(allClassName).not.toBe(inlineClassName);
+    expect(allClassName).not.toBe(blockClassName);
+
+    rerender(
+      <DialogHeader
+        title="Title"
+        endContent={<button type="button">Action</button>}
+        onOpenChange={() => {}}
+      />,
+    );
+    expect(getEndSlot().className).toBe(allClassName);
+
+    rerender(
+      <DialogHeader
+        title="Title"
+        endContent={<button type="button">Action</button>}
+        endContentEdgeCompensation="inline"
+        onOpenChange={() => {}}
+      />,
+    );
+    expect(getEndSlot().className).toBe(inlineClassName);
+  });
+
+  it('exposes theme targets for the header row, title block, both content slots, and close icon', () => {
     const {container} = render(
       <DialogHeader
         title="Title"
         subtitle="Subtitle"
+        startContent={<button type="button">Back</button>}
+        endContent={<button type="button">Custom Action</button>}
         onOpenChange={() => {}}
       />,
     );
 
     expect(container.querySelector('.astryx-dialog-header')).not.toBeNull();
+    expect(
+      screen.getByRole('button', {name: 'Back'}).parentElement,
+    ).toHaveClass('astryx-dialog-header-start-content');
     expect(screen.getByRole('heading', {level: 2}).parentElement).toHaveClass(
       'astryx-dialog-header-title-block',
     );
 
+    const endContent = screen.getByRole('button', {
+      name: 'Custom Action',
+    }).parentElement;
+    expect(endContent).toHaveClass('astryx-dialog-header-end-content');
+    expect(screen.getByRole('button', {name: /close/i}).parentElement).toBe(
+      endContent,
+    );
+
     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', () => {
+  it('exposes the start-content target when startContent renders', () => {
+    const {container} = render(
+      <DialogHeader
+        title="Title"
+        startContent={<button type="button">Back</button>}
+      />,
+    );
+
+    expect(
+      screen.getByRole('button', {name: 'Back'}).parentElement,
+    ).toHaveClass('astryx-dialog-header-start-content');
+    expect(
+      container.querySelectorAll('.astryx-dialog-header-start-content'),
+    ).toHaveLength(1);
+  });
+
+  it('exposes the end-content target when endContent renders without a close button', () => {
+    const {container} = render(
+      <DialogHeader
+        title="Title"
+        endContent={<button type="button">Custom Action</button>}
+      />,
+    );
+
+    expect(
+      screen.getByRole('button', {name: 'Custom Action'}).parentElement,
+    ).toHaveClass('astryx-dialog-header-end-content');
+    expect(
+      container.querySelectorAll('.astryx-dialog-header-end-content'),
+    ).toHaveLength(1);
+  });
+
+  it('omits the content-slot targets when their content does not render', () => {
+    const {container} = render(<DialogHeader title="Title" />);
+
+    expect(
+      container.querySelector('.astryx-dialog-header-start-content'),
+    ).toBeNull();
+    expect(
+      container.querySelector('.astryx-dialog-header-end-content'),
+    ).toBeNull();
+  });
+
+  it('lets themes set the internal gaps and close-icon size', () => {
     const theme = defineTheme({
       name: 'dialog-header-targets-test',
       components: {
         'dialog-header': {base: {gap: '8px'}},
+        'dialog-header-start-content': {base: {gap: '5px'}},
         'dialog-header-title-block': {base: {gap: '4px'}},
+        'dialog-header-end-content': {base: {gap: '6px'}},
         'dialog-header-close-icon': {
           base: {width: '16px', height: '16px', fontSize: '16px'},
         },
@@ -98,8 +258,12 @@ describe('DialogHeader', () => {
 
     expect(css).toContain('.astryx-dialog-header {');
     expect(css).toContain('gap: 8px');
+    expect(css).toContain('.astryx-dialog-header-start-content {');
+    expect(css).toContain('gap: 5px');
     expect(css).toContain('.astryx-dialog-header-title-block {');
     expect(css).toContain('gap: 4px');
+    expect(css).toContain('.astryx-dialog-header-end-content {');
+    expect(css).toContain('gap: 6px');
     expect(css).toContain('.astryx-dialog-header-close-icon {');
     expect(css).toContain('width: 16px');
     expect(css).toContain('height: 16px');

package/src/Dialog/DialogHeader.tsx

@@ -37,9 +37,11 @@ const styles = stylex.create({
     justifyContent: 'space-between',
     gap: spacingVars['--spacing-3'],
   },
-  // Compensate for the icon button's visual padding on the actions area
-  actionsCompensation: {
+  // Compensate for the medium icon button's visual padding on the end slot.
+  endBlockEdgeCompensation: {
     marginBlock: `calc(-1 * ${spacingVars['--spacing-2']})`,
+  },
+  endInlineEdgeCompensation: {
     marginInlineEnd: `calc(-1 * ${spacingVars['--spacing-2']})`,
   },
   titleWrapper: {
@@ -98,6 +100,14 @@ export interface DialogHeaderProps extends BaseProps<HTMLDivElement> {
    */
   endContent?: ReactNode;
 
+  /**
+   * Overrides automatic end-slot compensation. When omitted, the slot keeps its
+   * existing behavior: rendering the close action applies block and logical
+   * inline-end compensation. Use `inline`, `block`, or `all` to select the axes
+   * explicitly.
+   */
+  endContentEdgeCompensation?: 'inline' | 'block' | 'all';
+
   /**
    * Adds a themed border at the bottom edge.
    * When false, spacing collapse is applied automatically for seamless visual flow.
@@ -134,6 +144,7 @@ export function DialogHeader({
   onOpenChange,
   startContent,
   endContent,
+  endContentEdgeCompensation,
   hasDivider,
   xstyle,
   className,
@@ -146,6 +157,16 @@ export function DialogHeader({
   const dialogContext = useDialogContext();
   const shouldAutoFocus = dialogContext?.isInline !== true;
   const titleId = dialogContext?.titleId;
+  const shouldCompensateEndBlock =
+    endContentEdgeCompensation == null
+      ? onOpenChange != null
+      : endContentEdgeCompensation === 'block' ||
+        endContentEdgeCompensation === 'all';
+  const shouldCompensateEndInline =
+    endContentEdgeCompensation == null
+      ? onOpenChange != null
+      : endContentEdgeCompensation === 'inline' ||
+        endContentEdgeCompensation === 'all';
 
   // Auto-focus the title when mounted for screen reader accessibility.
   // Inline dialogs are documentation/showcase previews, so suppress focus to
@@ -172,7 +193,13 @@ export function DialogHeader({
           stylex.props(styles.container),
         )}>
         {startContent && (
-          <div {...stylex.props(styles.actions)}>{startContent}</div>
+          <div
+            {...mergeProps(
+              themeProps('dialog-header-start-content'),
+              stylex.props(styles.actions),
+            )}>
+            {startContent}
+          </div>
         )}
         <div
           {...mergeProps(
@@ -195,9 +222,13 @@ export function DialogHeader({
         </div>
         {(endContent || onOpenChange) && (
           <div
-            {...stylex.props(
-              styles.actions,
-              onOpenChange && styles.actionsCompensation,
+            {...mergeProps(
+              themeProps('dialog-header-end-content'),
+              stylex.props(
+                styles.actions,
+                shouldCompensateEndBlock && styles.endBlockEdgeCompensation,
+                shouldCompensateEndInline && styles.endInlineEdgeCompensation,
+              ),
             )}>
             {endContent}
             {onOpenChange && (

package/src/Dialog/modules/DialogHeader.spec.md

@@ -7,17 +7,19 @@ authority: current
 archive_reason: null
 superseded_by: null
 approved_by: cixzhang
-approved_at: 2026-09-14
+approved_at: 2026-09-23
 owners: [cixzhang, imdreamrunner]
-review_triggers: [theming, layout]
+review_triggers: [theming, layout, public-api]
 verified_by:
   [
     packages/core/src/Dialog/DialogHeader.test.tsx,
     packages/core/src/theme/themingTargets.test.ts,
+    packages/cli/foundation/discovery/theming-targets.test.mjs,
     scripts/check-knowledge.mjs,
   ]
 parent_component: component:Dialog
-references: [architecture:component-theming-surface]
+references:
+  [architecture:component-theming-surface, architecture:container-padding]
 ---
 
 # DialogHeader module contract
@@ -25,14 +27,15 @@ references: [architecture:component-theming-surface]
 ## 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.
+control. This record owns the stable header-row, start-content, title-block,
+end-content, and close-icon anatomy, their public theming targets, and the fixed
+compensation applied to the existing end-content slot.
 
 ## Compatibility and migration
 
 - Released default preserved: `yes`
-- Compatibility class: additive theme targets only; default layout, paint,
-  interaction, accessibility, and public props remain unchanged
+- Compatibility class: two additive theme targets and one additive prop; omitted
+  layout, paint, interaction, accessibility, and theming remain unchanged
 - Migration decision: none
 
 Consumer migration instructions belong in consumer docs and release notes.
@@ -41,10 +44,16 @@ Consumer migration instructions belong in consumer docs and release notes.
 
 **Owns**
 
-- The header row that arranges title content and trailing controls.
+- The header row that arranges title content and controls.
+- The start-content wrapper for optional leading content.
 - The title block that groups the title and optional subtitle.
+- The existing end-content wrapper that groups optional trailing content with
+  the close action.
+- The fixed end-slot compensation derived from the medium close action's
+  transparent inset.
 - The close icon rendered for the optional close action.
-- The `dialog-header`, `dialog-header-title-block`, and
+- The `dialog-header`, `dialog-header-start-content`,
+  `dialog-header-title-block`, `dialog-header-end-content`, and
   `dialog-header-close-icon` targets.
 
 **Does not own / non-goals**
@@ -53,50 +62,70 @@ Consumer migration instructions belong in consumer docs and release notes.
   `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.
+- List-style inherited container-padding compensation, caller-supplied margin
+  values, or a general alignment primitive.
 
 ## Public API and concepts
 
-No component prop changes. This contract adds three public theming surfaces for
-existing anatomy.
+This contract preserves the three existing theming surfaces, adds two content-
+slot targets, and adds one slot-targeted compensation override.
 
-| 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 |
+| 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    |
+| Start-content target         | present when start content renders               | Styles the wrapper for optional leading content                                       | Existing start-content layout                         | `module:Dialog/DialogHeader` | stable    |
+| Title block target           | present                                          | Styles the title/subtitle grouping element                                            | Existing title stack visuals                          | `module:Dialog/DialogHeader` | stable    |
+| End-content target           | present when end content or close action renders | Styles the wrapper that groups trailing content with the close action                 | Existing end-content layout                           | `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    |
+| `endContentEdgeCompensation` | `inline`, `block`, `all`                         | Selects which axes of the existing end-content wrapper receive its fixed compensation | omitted; preserve automatic close-action compensation | `module:Dialog/DialogHeader` | stable    |
+
+For this slot-targeted prop, `inline` means the slot's logical inline-end edge,
+`block` means both block edges, and `all` combines them.
 
 ## 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 |
+| 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      |
+| FR5  | The existing end wrapper MUST continue to group optional `endContent` with the optional close action; this change MUST NOT add another wrapper.                                                                                                             | Current implementation                           | settled      |
+| FR6  | When `endContentEdgeCompensation` is omitted, rendering the close action MUST preserve the released fixed negative block and logical inline-end inset, whether or not `endContent` is present. Without the close action, no automatic compensation applies. | Released behavior and owner decision             | settled      |
+| FR7  | Explicit `inline` MUST apply only logical inline-end compensation; `block` MUST apply only both block edges; `all` MUST apply both. The explicit value overrides the automatic close-action selection.                                                      | `module:Dialog/DialogHeader/DEC-2`               | settled      |
+| FR8  | Compensation MUST use logical inline properties, preserve title, slot, and close-action semantics and hit targets, and expose no caller-controlled margin amount.                                                                                           | `architecture:container-padding`; owner decision | settled      |
+| FR9  | The leading content wrapper MUST carry `dialog-header-start-content` whenever optional start content renders.                                                                                                                                               | `module:Dialog/DialogHeader/DEC-3`               | settled      |
+| FR10 | The existing trailing content wrapper MUST carry `dialog-header-end-content` whenever optional end content or the close action renders.                                                                                                                     | `module:Dialog/DialogHeader/DEC-3`               | settled      |
 
 ### Transformation and precedence order
 
-- The module applies each target to its owning element before normal theme CSS
-  resolves through the shared theming pipeline.
+1. If `endContentEdgeCompensation` is present, its closed value selects the
+   compensated axes.
+2. Otherwise, a rendered close action selects `all`; omission of the close
+   action selects no compensation.
+3. The module applies each theme 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.
+- The additive closed-value branch and class selection 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.
+- Compensation and theme targets MUST NOT change the title's role, focus
+  behavior, dialog naming, the close button's accessible name and operation, or
+  any slot child's hit target.
 
 ## 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 |
+| Anatomy or state | Design requirement                                                                                                                       | Representation authority        | Module contract |
+| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- | --------------- |
+| Header row       | Owns arrangement and spacing among title content and controls.                                                                           | This module                     | FR1             |
+| Start content    | Owns the leading wrapper for optional start content.                                                                                     | This module                     | FR9             |
+| Title block      | Owns title/subtitle grouping and spacing.                                                                                                | This module                     | FR2             |
+| End content      | Owns the existing trailing wrapper containing optional end content and the close action, including its fixed slot-targeted compensation. | This module                     | FR4–FR8, FR10   |
+| Close icon       | Owns the close glyph's visual box inside the Button-owned action.                                                                        | This module with Icon rendering | FR3, FR4        |
 
 ### Theming anatomy
 
@@ -105,7 +134,9 @@ existing anatomy.
 ```json
 {
   "Header row": {"target": "dialog-header"},
+  "Start content": {"target": "dialog-header-start-content"},
   "Title block": {"target": "dialog-header-title-block"},
+  "End content": {"target": "dialog-header-end-content"},
   "Close icon": {"target": "dialog-header-close-icon"}
 }
 ```
@@ -113,22 +144,27 @@ existing anatomy.
 ## Parent and system relationships
 
 - `component:Dialog` owns modal behavior and the aggregate Dialog contract.
-- `component:Layout` owns the composed LayoutHeader region outside the three
+- `component:Layout` owns the composed LayoutHeader region outside the five
   module-owned inner parts.
-- `component:Button` owns the close action's control behavior and outer button
-  presentation.
+- `component:Button` owns the close action's control behavior, hit target, and
+  outer 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.
+- `architecture:container-padding` defines the retained-inset edge-compensation
+  intent and distinguishes this slot-targeted projection from List-style
+  inherited-inset self-compensation and full bleed.
 
 ## 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. |
+| Contract            | Verification                                                                    | Representative states                                                     | Mutation or failure expectation                                                              |
+| ------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
+| FR1–FR3, FR9–FR10   | Target tests, target inventory, generated probe theme, and source inspection    | title only, title/subtitle, start content, end content, close action      | A target is missing, undocumented, duplicated, or moved away from its owning painter.        |
+| FR4–FR5             | Existing content and close-button tests                                         | end content only; close only; both                                        | The close action or slot content disappears, reorders, or gains another wrapper.             |
+| FR6–FR7             | Focused end-slot class-selection assertions                                     | close only; end content only; both; explicit `inline`, `block`, and `all` | An omitted prop changes released geometry, or an explicit value selects the wrong axes.      |
+| FR8                 | Source inspection, RTL CI, interaction tests, and focused real-browser geometry | LTR and RTL; custom end control; close action                             | Physical margins, caller-controlled amounts, or hit-target changes enter the implementation. |
+| Theming anatomy map | `scripts/check-knowledge.mjs`                                                   | all five module anatomy entries and targets                               | Anatomy, docs, runtime targets, and the module map drift.                                    |
 
 ## Decision log
 
@@ -141,6 +177,29 @@ 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.
 
+### DEC-2 — End-content compensation is slot-targeted and explicit
+
+**Reference:** `module:Dialog/DialogHeader/DEC-2`
+**Decider:** cixzhang, 2026-09-22
+
+DialogHeader preserves its released automatic compensation whenever the close
+action renders. `endContentEdgeCompensation` targets the existing end-content
+slot and selects `inline`, `block`, or `all` without exposing a margin amount.
+This is a slot-targeted projection of the retained-inset edge-compensation
+intent; it does not make DialogHeader a List-style inherited-padding consumer.
+
+### DEC-3 — Content-slot wrappers are approved target destinations
+
+**Reference:** `module:Dialog/DialogHeader/DEC-3`
+**Decider:** cixzhang, 2026-09-23
+
+The existing wrappers for `startContent` and `endContent` are approved as stable
+visible anatomy. Their target destinations are
+`dialog-header-start-content` and `dialog-header-end-content`; implementation
+must add no wrapper and must preserve default layout, paint, interaction,
+accessibility, and public props. The end-content name follows the public prop
+even though that slot also contains the optional close action.
+
 ## Open questions
 
 None.

package/src/DropdownMenu/DropdownMenu.test.tsx

@@ -3,7 +3,7 @@
 /**
  * @file DropdownMenu.test.tsx
  * @input Uses vitest, @testing-library/react, DropdownMenu component
- * @output Unit tests for DropdownMenu component behavior
+ * @output Unit tests for DropdownMenu behavior and derived bottom-sheet item padding
  * @position Testing; validates DropdownMenu.tsx implementation
  *
  * SYNC: When DropdownMenu.tsx changes, update tests to match new behavior
@@ -165,7 +165,10 @@ describe('DropdownMenu', () => {
     });
     expect(
       screen.getByRole('button', {name: 'Edit project'}).closest('li'),
-    ).toHaveStyle({paddingInline: 'var(--spacing-3)'});
+    ).toHaveStyle({
+      paddingInline: 'var(--_item-inset-inline)',
+      '--_item-inset-inline': 'var(--spacing-3)',
+    });
   });
 
   it('drills into nested data items in bottom-sheet presentation', async () => {