Skip to content

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

TypeScript

docs: define anatomy-targeted edge compensation (#6464)

Cindy Zhangd19588c0bef4
diff --git a/docs/architecture/container-padding.md b/docs/architecture/container-padding.md
index 387a8f764b..32ed88f2ad 100644
--- a/docs/architecture/container-padding.md
+++ b/docs/architecture/container-padding.md
@@ -7,7 +7,7 @@ authority: current
archive_reason: null
superseded_by: null
approved_by: cixzhang
-approved_at: 2026-09-21
+approved_at: 2026-09-22
owners: [cixzhang, imdreamrunner]
applies_to:
[
@@ -141,6 +141,15 @@ does not read inherited container padding or give those children a
caller-controlled compensation API. This revision leaves that mechanism
unchanged.
+A component with a documented anatomy container that applies edge compensation
+MAY expose an anatomy-targeted `<anatomy>EdgeCompensation` prop to modify that
+container's compensation. The prop MUST use the shared axis values `inline`,
+`block`, or `all`, preserve the component's documented omission behavior, and
+keep the compensation amount component-owned. `inline` means the named
+container's logical inline edge, `block` means both block edges, and `all`
+combines them. These values do not extend the self-compensation vocabulary below.
+`endContentEdgeCompensation` is DialogHeader's projection of this rule.
+
`edgeCompensation` names the caller's intent: reduce component-owned inset at
selected ancestor container content edges while keeping the component's own paint
or interaction inset. The component contract states when that bounded adjustment
@@ -154,8 +163,9 @@ value vocabulary is:
A component exposes only the values its current contract and evidence support.
This mode does not promise that the component box reaches the container's outer
edge. Reserve `isFullBleed` for components such as ScrollableArea whose visible
-surface consumes the full inherited container inset. New edge-alignment APIs use
-`edgeCompensation` rather than exposing margin values or inventing a second name.
+surface consumes the full inherited container inset. New self-compensation APIs
+use `edgeCompensation` rather than exposing margin values or inventing a second
+name.
### Edge-compensation ledger
diff --git a/packages/core/src/Dialog/modules/DialogHeader.spec.md b/packages/core/src/Dialog/modules/DialogHeader.spec.md
index 14d3ed51d2..c45c41f6a8 100644
--- a/packages/core/src/Dialog/modules/DialogHeader.spec.md
+++ b/packages/core/src/Dialog/modules/DialogHeader.spec.md
@@ -7,9 +7,9 @@ authority: current
archive_reason: null
superseded_by: null
approved_by: cixzhang
-approved_at: 2026-09-14
+approved_at: 2026-09-22
owners: [cixzhang, imdreamrunner]
-review_triggers: [theming, layout]
+review_triggers: [theming, layout, public-api]
verified_by:
[
packages/core/src/Dialog/DialogHeader.test.tsx,
@@ -17,7 +17,8 @@ verified_by:
scripts/check-knowledge.mjs,
]
parent_component: component:Dialog
-references: [architecture:component-theming-surface]
+references:
+ [architecture:component-theming-surface, architecture:container-padding]
---
# DialogHeader module contract
@@ -26,13 +27,14 @@ references: [architecture:component-theming-surface]
`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.
+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: 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.
@@ -43,6 +45,10 @@ Consumer migration instructions belong in consumer docs and release notes.
- The header row that arranges title content and trailing controls.
- 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
`dialog-header-close-icon` targets.
@@ -53,50 +59,65 @@ 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 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 |
+| 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 |
+| `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 |
### 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 existing 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 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 |
+| 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 |
+| Close icon | Owns the close glyph's visual box inside the Button-owned action. | This module with Icon rendering | FR3, FR4 |
### Theming anatomy
@@ -115,20 +136,25 @@ existing anatomy.
- `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: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 | Existing target tests, target inventory, generated probe theme, and source inspection | title only, title/subtitle, close action | An existing target is removed 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 three module anatomy entries and targets | Anatomy, docs, runtime targets, and the module map drift. |
## Decision log
@@ -141,6 +167,17 @@ 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.
+
## Open questions
None.