Skip to content

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

TypeScript

docs(specs): Layout and LayoutContent records match the closed slot and inset gaps (#10557)

Cindy Zhang64ca3b715632
diff --git a/docs/architecture/container-padding.md b/docs/architecture/container-padding.md
index eec8a4320b..f5c75fe40d 100644
--- a/docs/architecture/container-padding.md
+++ b/docs/architecture/container-padding.md
@@ -105,7 +105,7 @@ The protocol has four layers:
| Role | Participants | Contract responsibility |
| -------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Container publisher | Card, Section, Dialog, BottomSheet, ScrollableArea | Resolve component padding or publish explicit content-box padding as logical-edge and Layout inset variables |
-| Region publisher | LayoutHeader, LayoutContent, LayoutFooter, LayoutPanel | Publish baseline or explicit-padding geometry; automatic-edge publication has the conformance gap below |
+| Region publisher | LayoutHeader, LayoutContent, LayoutFooter, LayoutPanel | Publish baseline or explicit-padding geometry; LayoutPanel's automatic-edge publication has the conformance gap below |
| Bleed consumer | Section, ScrollableArea, Layout, Divider, Table, TabList, List | Subtract inherited inset on the edges each component is designed to escape; ScrollableArea does so only with `isFullBleed`, TabList and List only with `edge="bleed"` |
| Edge-compensation consumer | List/ListItem rows with `edge="outset"` | Move visible content toward the container content line while retaining component-owned interaction padding; exact alignment depends on each component's bounded geometry |
| Alignment consumer | Toolbar and edge-compensating child components | Read the current inline inset to align visible content rather than stacked touch-target padding |
@@ -296,23 +296,17 @@ without dropping the active theme's Section default.
### Known conformance gap
-LayoutContent and LayoutPanel do not currently publish the padding they apply
-on every automatic edge:
+LayoutPanel does not currently publish the padding it applies on every
+automatic edge: it changes padding on shell-facing inline and block edges while
+its baseline geometry variables remain on the inner values. LayoutContent
+publishes the padding it applies on every edge (`component:LayoutContent` FR2).
-- LayoutContent's no-start path changes inline-start padding and writes the outer
- value to both inline geometry variables, so with only an end panel the
- inline-end variable carries the outer value while the applied inline-end
- padding is the inner inset. Beside a header or footer without a divider, its
- block edge applies zero while publishing the inner inset.
-- LayoutPanel changes padding on shell-facing inline and block edges while its
- baseline geometry variables remain on the inner values.
-
-A full-bleed descendant in those states can therefore compensate against a value
+A full-bleed descendant of such a panel can therefore compensate against a value
that differs from the region's applied padding. Explicit region padding and
`padding={0}` do update/reset the geometry variables. No current browser matrix
covers every slot and descendant-bleed combination, so this record does not claim
exact region parity. Correcting the mismatch is runtime work with compatibility
-evidence, not part of this documentation stack.
+evidence.
## Change coupling
diff --git a/docs/families/layout-regions.md b/docs/families/layout-regions.md
index e9d1234a8b..323bc76d52 100644
--- a/docs/families/layout-regions.md
+++ b/docs/families/layout-regions.md
@@ -120,7 +120,7 @@ wrapper, or a header-like visual treatment.
inset where they meet another region. LayoutContent keeps its root as the
scroll, padding, and direct-child owner. Omitted slots do not leave an area
wrapper. The inherited geometry republished to full-bleed descendants is
- subject to the current LayoutContent/LayoutPanel conformance gap in
+ subject to the current LayoutPanel conformance gap in
`architecture:container-padding`.
- **FR4 — Explicit region padding replaces the automatic applied inset.**
Section publishes its component inset; Layout distributes outer and inner
@@ -208,7 +208,7 @@ wrapper, or a header-like visual treatment.
| -------------------- | ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Section | Generic region and container-padding publisher | Its nested escape is always inline but only first/last child on the block axis |
| Layout container | Five-slot region owner with slot contexts | Content-only LayoutContent stays full width and aligns direct children through insets. With exactly one panel, the panel remains aligned while content extends to the opposite open edge. With both panels or intrinsic content widths, the middle composition stays constrained. Tests cover topology; browser evidence covers mirrored alignment and scrollbar placement. |
-| LayoutContent | Reads slot presence and applies outer/inner inset | Its no-start path writes the outer value to both inline geometry variables, so with only an end panel the inline-end variable differs from the applied inner inset; beside a header or footer without a divider the block edge applies zero but publishes the inner inset |
+| LayoutContent | Reads slot presence and applies outer/inner inset | Each edge publishes the padding it applies; the per-edge insets and their publication have audit browser receipts only, not an always-run check |
| LayoutPanel | Applies position-aware padding and may accept resize-driven width | Automatic Layout-edge padding leaves baseline inner geometry variables; an adjacent `ResizeHandle hasDivider` can double the line unless the caller sets panel `hasDivider={false}` |
| LayoutHeader/Footer | Region-specific inset, boundary, and landmarks | Cross-region computed-style parity is not covered by one browser matrix |
| Toolbar | Section-backed surface plus toolbar behavior | Inline inset and edge compensation follow the composed Section's current padding context |
@@ -238,18 +238,18 @@ exceptions to silently change in a documentation pull request.
## Verification map
-| Contract | Verification | What the evidence proves | Missing evidence |
-| -------------------- | ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
-| FR1 | Section/Layout/Toolbar render and slot tests | Caller content renders inside the current region structure; Toolbar exposes its current lanes | Tests do not independently prove that product semantics remain caller-owned |
-| FR2 | Logical-property source review plus Layout area-context tests | Start/end slots are identified logically and source selects logical divider/padding properties | No real-browser LTR/RTL geometry matrix covers every region |
-| FR3 | `Layout.test.tsx` and `childrenAsContent.test.tsx` | Slot presence/context and content precedence are pinned; omitted slots do not render area providers | Tests do not assert computed outer/inner inset or exact descendant geometry; the published-variable mismatch is a named conformance gap |
-| FR4 | Section padding class-set tests and Layout region source | Section's explicit edge overrides move matching variables; region source has automatic, explicit, and zero-padding branches | Layout tests mostly assert acceptance/rendering, not computed padding or automatic-variable parity |
-| FR5, FR6 | `Layout.test.tsx` and `LayoutSlots.test.tsx` | Header/footer divider defaults and explicit false overrides are reflected in `data-divider`; source contains collapse styles | No rendered test prevents a LayoutPanel and adjacent ResizeHandle from both drawing a divider, or proves computed collapse spacing |
-| FR7 | LayoutContent/LayoutPanel source and local class/render tests | The two regions expose their current `isScrollable` branches; Layout exposes fill/auto state | No browser test proves scroll ownership across every shell/region composition |
-| FR8 | `LayoutSlots.test.tsx` landmark assertions | Supplied roles and labels reach Header, Content, Footer, and Panel elements | No family-wide accessibility-tree test covers repeated landmarks |
-| Layout content width | `contentWidth.test.tsx` and Storybook scrollbar-placement states | Header/footer retain aligned wrappers; no-panel LayoutContent owns a full-width scroll region; either single-panel state mirrors content through the opposite open edge; both panels keep the composition constrained | Real-browser evidence verifies computed content alignment and scrollbar placement across the four panel states |
-| Toolbar variation | `Toolbar.test.tsx` | Lanes, role/name/orientation, Section variant delegation, and current keyboard behavior have focused assertions | No computed inset/edge-compensation test covers non-default parent padding |
-| FR10 | LayoutPanel coverage in `LayoutSlots.test.tsx` | Hook-provided `_size` overrides the fixed width prop | Resize interaction, persistence, snapping, and collapse are verified only by Resizable's own tests |
+| Contract | Verification | What the evidence proves | Missing evidence |
+| -------------------- | ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| FR1 | Section/Layout/Toolbar render and slot tests | Caller content renders inside the current region structure; Toolbar exposes its current lanes | Tests do not independently prove that product semantics remain caller-owned |
+| FR2 | Logical-property source review plus Layout area-context tests | Start/end slots are identified logically and source selects logical divider/padding properties | No real-browser LTR/RTL geometry matrix covers every region |
+| FR3 | `Layout.test.tsx` and `childrenAsContent.test.tsx` | Slot presence/context and content precedence are pinned; omitted slots do not render area providers | Tests do not assert computed outer/inner inset or exact descendant geometry; LayoutPanel's published-variable mismatch is a named conformance gap |
+| FR4 | Section padding class-set tests and Layout region source | Section's explicit edge overrides move matching variables; region source has automatic, explicit, and zero-padding branches | Layout tests mostly assert acceptance/rendering, not computed padding or automatic-variable parity |
+| FR5, FR6 | `Layout.test.tsx` and `LayoutSlots.test.tsx` | Header/footer divider defaults and explicit false overrides are reflected in `data-divider`; source contains collapse styles | No rendered test prevents a LayoutPanel and adjacent ResizeHandle from both drawing a divider, or proves computed collapse spacing |
+| FR7 | LayoutContent/LayoutPanel source and local class/render tests | The two regions expose their current `isScrollable` branches; Layout exposes fill/auto state | No browser test proves scroll ownership across every shell/region composition |
+| FR8 | `LayoutSlots.test.tsx` landmark assertions | Supplied roles and labels reach Header, Content, Footer, and Panel elements | No family-wide accessibility-tree test covers repeated landmarks |
+| Layout content width | `contentWidth.test.tsx` and Storybook scrollbar-placement states | Header/footer retain aligned wrappers; no-panel LayoutContent owns a full-width scroll region; either single-panel state mirrors content through the opposite open edge; both panels keep the composition constrained | Real-browser evidence verifies computed content alignment and scrollbar placement across the four panel states |
+| Toolbar variation | `Toolbar.test.tsx` | Lanes, role/name/orientation, Section variant delegation, and current keyboard behavior have focused assertions | No computed inset/edge-compensation test covers non-default parent padding |
+| FR10 | LayoutPanel coverage in `LayoutSlots.test.tsx` | Hook-provided `_size` overrides the fixed width prop | Resize interaction, persistence, snapping, and collapse are verified only by Resizable's own tests |
The current tests prove selected structure, attributes, callbacks, and class/style
branches. They do not prove one computed visual alignment across every Section,
diff --git a/docs/specs/components/Layout/Layout.spec.md b/docs/specs/components/Layout/Layout.spec.md
index e1bddd41b2..b11a3a3d59 100644
--- a/docs/specs/components/Layout/Layout.spec.md
+++ b/docs/specs/components/Layout/Layout.spec.md
@@ -17,6 +17,7 @@ verified_by:
packages/core/src/Layout/__tests__/childrenAsContent.test.tsx,
packages/core/src/Layout/__tests__/contentWidth.test.tsx,
packages/core/src/Layout/__tests__/nestedPadding.test.tsx,
+ packages/core/src/Layout/__tests__/LayoutAudit.a11y.chromium.spec.ts,
packages/core/src/theme/themingTargets.test.ts,
.github/visual-baseline/manifest.json,
scripts/check-knowledge.mjs,
@@ -44,7 +45,7 @@ system_specs: [spec:AST-038]
| Behavior | Layout arranges caller content in five named slots, fills or grows with its container, and sets the inset and content width its region components use. |
| End-user impact | People see headers, side panels, content, and footers in stable positions that mirror in right-to-left, with content aligned to one readable width. |
| Builder impact | None; the record describes shipped behavior. |
-| Compatibility/readiness | Released behavior recorded as current; no API, default, or output changes. One implementation gap is listed under Current-state impact. |
+| Compatibility/readiness | Released behavior recorded as current; no API, default, or output changes. No implementation gap is open (Current-state impact). |
| Review checks | Reject a target added to arbitrary slot content, an inherited parent Layout padding, a content scrollbar moved off the open edge, or overridable `data-height`. |
| Governing rules | `family:layout-regions` FR1–FR12; `architecture:container-padding`; `architecture:component-theming-surface`; `architecture:public-component-api` INV5–INV8. |
@@ -71,15 +72,11 @@ Consumer migration instructions belong in consumer docs and release notes.
## Current-state impact
-- **A `false` slot still counts as present (FR1).** Slot presence is
- `!= null`, so `header={isOpen && <LayoutHeader />}` renders no header when
- `isOpen` is false, yet the content and panels keep the inner inset on their
- block-start edge instead of the outer inset `family:layout-regions` FR3 gives
- an edge on the Layout boundary. With `contentWidth`, a `false` start or end
- slot (the `showPanel && <LayoutPanel />` idiom) switches Layout to its
- one- or two-panel composition, so LayoutContent stops at the content-width frame on
- that side, and with a `false` end slot its scrollbar does too, instead of
- reaching the Layout edge (FR6).
+None. A slot whose value is `false`, `true`, or `''` (such as
+`isOpen && <LayoutHeader />` while `isOpen` is false) counts as absent, so
+its neighbours take the outer inset on that side, and with `contentWidth` a
+closed start or end slot gives the same FR6 composition as an omitted one
+(FR1).
## Ownership boundary
@@ -115,16 +112,16 @@ Consumer migration instructions belong in consumer docs and release notes.
## Behavioral and layout contract
-| ID | Invariant | Basis |
-| --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
-| FR1 | Layout renders an outer `div` carrying the `layout` target, which reflects `height`, around an inner vertical stack: the header slot, a middle row holding the start slot, the content slot, and the end slot, then the footer slot. An omitted header, start, end, or footer slot renders nothing; a slot that renders nothing is absent, so the neighbouring regions take the outer inset on that side (`family:layout-regions` FR3); the middle row and the content slot's fill wrapper always render. `content` fills the content slot, and `children` fill it when `content` is omitted. Slot position adds no element, region component, or target to the caller's content. Implementation gap: a slot counts as present unless it is `null` or `undefined`, so a `false` slot renders nothing yet leaves its neighbours on the inner inset, and with `contentWidth` a `false` start or end slot switches to the one- or two-panel composition of FR6 (Current-state impact). | Current source, docs, and tests; `family:layout-regions` FR1, FR3 |
-| FR2 | The outer `div` escapes the parent's published container padding on all four edges, and the inner stack publishes zero container padding before its regions publish their own. `fill` (the default) makes the Layout fill its container's height, including the escaped block padding; `auto` lets it grow with content, at least as tall as its container. | Current source and tests; `architecture:container-padding` |
-| FR3 | `padding` sets the inset that this Layout's own region components apply at its outer edges; `0` is full bleed. A nested Layout does not inherit a parent Layout's padding: without its own `padding`, its regions use the nearest padding container's padding (Card, Section, Dialog, Drawer, or BottomSheet), or spacing step 4. How each region applies and publishes that inset is owned by its record (`component:LayoutHeader`, `component:LayoutContent`, `component:LayoutFooter`, `component:LayoutPanel`). | Current source, docs, and tests; `family:layout-regions` FR4; `architecture:container-padding` |
-| FR4 | When the caller supplies LayoutHeader, LayoutContent, LayoutFooter, or LayoutPanel, that component carries its own `layout-header`, `layout-content`, `layout-footer`, or `layout-panel` target. LayoutPanel at logical start, end, or both is one Panel part and one `layout-panel` target. | Current source, docs, and tests; `family:layout-regions` FR11 |
-| FR5 | `defaultHasDividers` sets the divider default for LayoutHeader and LayoutFooter descendants; an explicit `hasDivider` wins, and when unset a nested Layout keeps its parent's default within the same layer; the default stops at a Dialog, Drawer, BottomSheet, or other layer boundary (`spec:AST-038` FR7), and at an AppShell root (`component:AppShell` FR18). LayoutPanel does not read the default (`component:LayoutPanel` FR4). | Current source, docs, and tests |
-| FR6 | With `contentWidth` and no panels, LayoutContent spans the middle area and aligns its direct children to the content width, so its scrollbar stays at the outer edge. With exactly one panel, the panel stays aligned while LayoutContent extends through the opposite open side; start and end mirror. With both panels, or a percentage (including percentage-bearing CSS math), intrinsic, or bare-variable width, the whole middle composition stays constrained; a length-valued variable uses `calc(var(...))`. Numbers are pixels. A nested Layout without `contentWidth` does not inherit its parent's. | Current source, docs, and tests; `family:layout-regions` FR12 |
-| FR7 | `ref`, DOM, data, ARIA, and event props, `xstyle`, `className`, and `style` reach or compose on the outer `div`; the reflected `data-height` replaces a caller's value. | Current source and tests; `architecture:public-component-api` INV5–INV8 |
-| FR8 | Layout owns the layout reset: one internal export, `layoutReset` (Core's `overlayPaddingReset` plus the values it leaves out), stops at the element it is applied to every layout custom property Layout, its region components, Section, and the container styles publish to descendants. It sets the published container padding to `0px` and the Layout insets and widths, flush values, Section padding propagation, and the container height cap to `initial`. A layout root applies it (`component:AppShell` FR18). It is internal, not theme API or a package export (`architecture:container-padding` INV1, `architecture:public-component-api` INV12). A surface outside Core that needs the same boundary keeps a mirror of its list under a parity test against it. | `component:AppShell` FR18; `architecture:container-padding` |
+| ID | Invariant | Basis |
+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| FR1 | Layout renders an outer `div` carrying the `layout` target, which reflects `height`, around an inner vertical stack: the header slot, a middle row holding the start slot, the content slot, and the end slot, then the footer slot. An omitted header, start, end, or footer slot renders nothing; a slot whose value is not renderable (`null`, `undefined`, a boolean, or `''`) is absent, so the neighbouring regions take the outer inset on that side (`family:layout-regions` FR3), while an element, fragment, or array counts as present even when it renders nothing; the middle row and the content slot's fill wrapper always render. `content` fills the content slot, and `children` fill it when `content` is omitted. Slot position adds no element, region component, or target to the caller's content. | Current source, docs, and tests; `family:layout-regions` FR1, FR3 |
+| FR2 | The outer `div` escapes the parent's published container padding on all four edges, and the inner stack publishes zero container padding before its regions publish their own. `fill` (the default) makes the Layout fill its container's height, including the escaped block padding; `auto` lets it grow with content, at least as tall as its container. | Current source and tests; `architecture:container-padding` |
+| FR3 | `padding` sets the inset that this Layout's own region components apply at its outer edges; `0` is full bleed. A nested Layout does not inherit a parent Layout's padding: without its own `padding`, its regions use the nearest padding container's padding (Card, Section, Dialog, Drawer, or BottomSheet), or spacing step 4. How each region applies and publishes that inset is owned by its record (`component:LayoutHeader`, `component:LayoutContent`, `component:LayoutFooter`, `component:LayoutPanel`). | Current source, docs, and tests; `family:layout-regions` FR4; `architecture:container-padding` |
+| FR4 | When the caller supplies LayoutHeader, LayoutContent, LayoutFooter, or LayoutPanel, that component carries its own `layout-header`, `layout-content`, `layout-footer`, or `layout-panel` target. LayoutPanel at logical start, end, or both is one Panel part and one `layout-panel` target. | Current source, docs, and tests; `family:layout-regions` FR11 |
+| FR5 | `defaultHasDividers` sets the divider default for LayoutHeader and LayoutFooter descendants; an explicit `hasDivider` wins, and when unset a nested Layout keeps its parent's default within the same layer; the default stops at a Dialog, Drawer, BottomSheet, or other layer boundary (`spec:AST-038` FR7), and at an AppShell root (`component:AppShell` FR18). LayoutPanel does not read the default (`component:LayoutPanel` FR4). | Current source, docs, and tests |
+| FR6 | With `contentWidth` and no panels, LayoutContent spans the middle area and aligns its direct children to the content width, so its scrollbar stays at the outer edge. With exactly one panel, the panel stays aligned while LayoutContent extends through the opposite open side; start and end mirror. With both panels, or a percentage (including percentage-bearing CSS math), intrinsic, or bare-variable width, the whole middle composition stays constrained; a length-valued variable uses `calc(var(...))`. Numbers are pixels. A nested Layout without `contentWidth` does not inherit its parent's. | Current source, docs, and tests; `family:layout-regions` FR12 |
+| FR7 | `ref`, DOM, data, ARIA, and event props, `xstyle`, `className`, and `style` reach or compose on the outer `div`; the reflected `data-height` replaces a caller's value. | Current source and tests; `architecture:public-component-api` INV5–INV8 |
+| FR8 | Layout owns the layout reset: one internal export, `layoutReset` (Core's `overlayPaddingReset` plus the values it leaves out), stops at the element it is applied to every layout custom property Layout, its region components, Section, and the container styles publish to descendants. It sets the published container padding to `0px` and the Layout insets and widths, flush values, Section padding propagation, and the container height cap to `initial`. A layout root applies it (`component:AppShell` FR18). It is internal, not theme API or a package export (`architecture:container-padding` INV1, `architecture:public-component-api` INV12). A surface outside Core that needs the same boundary keeps a mirror of its list under a parity test against it. | `component:AppShell` FR18; `architecture:container-padding` |
### Allowed variation
@@ -202,25 +199,25 @@ Panel stands for every LayoutPanel, at logical start, end, or both.
inset; FR2 and FR3 apply it.
- `component:LayoutHeader`, `component:LayoutContent`, `component:LayoutFooter`,
and `component:LayoutPanel` own each region's behavior, including the
- publication gaps LayoutContent and LayoutPanel record.
+ publication gap LayoutPanel records.
- `architecture:component-theming-surface` owns anatomy and target mapping.
- `architecture:public-component-api` owns caller-input routing; FR7 applies
it.
## Verification map
-| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
-| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- |
-| FR1, ORD1, AV1 | `Layout.test.tsx` slot and content tests; `childrenAsContent.test.tsx` | Every slot; omitted slots; `content` and `children` | A missing slot or `children` beating `content` fails. Gap: the omitted-slot test checks only the content text, so a wrapper rendered for an omitted slot passes, and no test asserts that slot content gains no target or element. No test covers a `false` slot. | `audit:Layout/anatomy` |
-| FR2 | `Layout.test.tsx` height-reflection tests | `fill`, `auto` | A lost `data-height` reflection fails. Gap: the escape margins, the zero publication, and the fill and auto heights have no automated check. | `audit:Layout/layout` |
-| FR3, ORD2 | `nestedPadding.test.tsx` | Inside AppShell, Card, Section; nested full-bleed and padded Layouts; explicit nested padding | A nested Layout inheriting a parent Layout's padding, or losing the enclosing Card or Section padding or the default inset, fails. Gap: `Layout.test.tsx` padding tests assert only that rendering succeeds. | `audit:Layout/layout` |
-| FR4 | `LayoutSlots.test.tsx` class tests; `themingTargets.test.ts` | Each region component; start and end panels | A lost region target fails. | `audit:Layout/theming` |
-| FR5, ORD3 | `Layout.test.tsx` divider-default tests | Default true; unset; explicit `false` | A header or footer that ignores the default, or an explicit `hasDivider={false}` that loses, fails. Gap: nested inheritance has no check. No test covers the default stopping at a layer boundary. | `audit:Layout/layout` |
-| FR6 | `contentWidth.test.tsx`; stable visual baseline `core-layout--content-width-scrollbar-placement` | No panels, start only, end only, both; zero padding; nested | A no-panel content region that is not full width, a both-panel middle that is not constrained, or a nested Layout inheriting content width fails; a scrollbar moved off its content edge comes back changed for review. No test covers a `false` start or end slot. | `audit:Layout/layout` |
-| FR7 | `Layout.test.tsx` ref, className, style, passthrough, and owned-metadata tests | Ref; caller inputs; colliding `data-height` | A ref on another element, a dropped caller input, or a caller `data-height` that wins fails. Gap: no test covers event props or the `xstyle` merge order. | `audit:Layout/api` |
-| FR8 | `layoutReset.test.tsx`, which fails when Layout or Section writes a layout custom property the reset does not stop, and reads each reset value back inside a padded Section; the docsite's `example-layout-root.test.ts`, which fails when the docsite example root's mirror differs from the reset | Every custom property Layout and Section write; a padded Section host | A property written but not reset, a reset value an ancestor still overrides, or a docsite mirror that differs from the reset, fails. | `audit:Layout/layout` |
-| AR1, AR2, PR1 | Source review | Every slot | Gap: no automated check fails if Layout adds a role, reorders slots, or adds a listener or measurement. | `audit:Layout/accessibility` |
-| Theming anatomy map | `scripts/check-knowledge.mjs` | Consumer anatomy and current targets | Missing, extra, or stale mappings fail repository validation. | `audit:Layout/theming` |
+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
+| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- |
+| FR1, ORD1, AV1 | `Layout.test.tsx` slot and content tests, including `reports a slot that renders nothing as empty`; `childrenAsContent.test.tsx`; `LayoutAudit.a11y.chromium.spec.ts` `closed-regions` receipts | Every slot; omitted slots; `false`, `true`, and `''` slots; `content` and `children` | A missing slot, `children` beating `content`, or a `false`, `true`, or `''` slot reported as filled fails. Gap: the omitted-slot test checks only the content text, so a wrapper rendered for an omitted slot passes, and no test asserts that slot content gains no target or element. The closed-region geometry has audit receipts only: the browser spec runs only for a Layout audit pull request. | `audit:Layout/anatomy` |
+| FR2 | `Layout.test.tsx` height-reflection tests; `LayoutAudit.a11y.chromium.spec.ts` escape-margin and zero-publication receipts | `fill`, `auto` | A lost `data-height` reflection fails. Gap: no always-run check covers the escape margins, the zero publication, or the fill and auto heights; the browser spec that measures the margins and the publication runs only for a Layout audit pull request, so they have audit receipts only. | `audit:Layout/layout` |
+| FR3, ORD2 | `nestedPadding.test.tsx` | Inside AppShell, Card, Section; nested full-bleed and padded Layouts; explicit nested padding | A nested Layout inheriting a parent Layout's padding, or losing the enclosing Card or Section padding or the default inset, fails. Gap: `Layout.test.tsx` padding tests assert only that rendering succeeds. | `audit:Layout/layout` |
+| FR4 | `LayoutSlots.test.tsx` class tests; `themingTargets.test.ts` | Each region component; start and end panels | A lost region target fails. | `audit:Layout/theming` |
+| FR5, ORD3 | `Layout.test.tsx` divider-default tests, including `a nested Layout without defaultHasDividers keeps its parent default` and `stops the default at a layer boundary` | Default true; unset; explicit `false`; nested Layout; inside a Dialog | A header or footer that ignores the default, an explicit `hasDivider={false}` that loses, a nested Layout that loses its parent's default, or a default that crosses a layer boundary fails. | `audit:Layout/layout` |
+| FR6 | `contentWidth.test.tsx`; stable visual baseline `core-layout--content-width-scrollbar-placement` | No panels, start only, end only, both; zero padding; nested | A no-panel content region that is not full width, a both-panel middle that is not constrained, or a nested Layout inheriting content width fails; a scrollbar moved off its content edge comes back changed for review. A closed start or end slot has audit receipts only (`LayoutAudit.a11y.chromium.spec.ts` `closed-regions`, run only for a Layout audit pull request). | `audit:Layout/layout` |
+| FR7 | `Layout.test.tsx` ref, className, style, passthrough, event-handler, and owned-metadata tests | Ref; caller inputs; event props; colliding `data-height` | A ref on another element, a dropped caller input or event handler, or a caller `data-height` that wins fails. Gap: no test pins the `xstyle` merge order. | `audit:Layout/api` |
+| FR8 | `layoutReset.test.tsx`, which fails when Layout or Section writes a layout custom property the reset does not stop, and reads each reset value back inside a padded Section; the docsite's `example-layout-root.test.ts`, which fails when the docsite example root's mirror differs from the reset | Every custom property Layout and Section write; a padded Section host | A property written but not reset, a reset value an ancestor still overrides, or a docsite mirror that differs from the reset, fails. | `audit:Layout/layout` |
+| AR1, AR2, PR1 | Source review | Every slot | Gap: no automated check fails if Layout adds a role, reorders slots, or adds a listener or measurement. | `audit:Layout/accessibility` |
+| Theming anatomy map | `scripts/check-knowledge.mjs` | Consumer anatomy and current targets | Missing, extra, or stale mappings fail repository validation. | `audit:Layout/theming` |
## Decision log
diff --git a/docs/specs/components/Layout/LayoutContent.spec.md b/docs/specs/components/Layout/LayoutContent.spec.md
index 3798b71e72..d28129d95b 100644
--- a/docs/specs/components/Layout/LayoutContent.spec.md
+++ b/docs/specs/components/Layout/LayoutContent.spec.md
@@ -16,6 +16,7 @@ verified_by:
packages/core/src/Layout/__tests__/contentWidth.test.tsx,
packages/core/src/Layout/__tests__/Layout.a11y.test.tsx,
packages/core/src/Layout/__tests__/Layout.a11y.chromium.spec.ts,
+ packages/core/src/Layout/__tests__/LayoutContentAudit.a11y.chromium.spec.ts,
packages/core/src/hooks/useScrollRegionProps.test.tsx,
packages/core/src/hooks/__tests__/scrollRegionName.a11y.chromium.spec.ts,
.github/visual-baseline/manifest.json,
@@ -39,15 +40,15 @@ system_specs: [spec:AST-038]
## Contract at a glance
-| Area | Contract |
-| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
-| Public contract | `children`, `isScrollable`, `padding`, `label`, `role`, root `BaseProps`, and a root `ref`. |
-| Behavior | The main content region fills the Layout's middle area, scrolls by default, and insets its children from neighbouring regions and open edges. |
-| End-user impact | People scroll the main content while headers, footers, and panels stay put, with the scrollbar at the content area's open edge. |
-| Builder impact | None: no API change; a scrolling region gains a role and a name with no code change (AR3). |
-| Compatibility/readiness | No API or default changes; the scrolling-region role and name (AR3) are a patch `[fix]`. Three gaps are listed under Current-state impact. |
-| Review checks | Reject an inner wrapper around the children, a scrollbar moved off the open edge, an inferred landmark, or a further publication mismatch. |
-| Governing rules | `family:layout-regions` FR1, FR3, FR4, FR7, FR8, FR12; `architecture:container-padding`; `architecture:public-component-api` INV5–INV8. |
+| Area | Contract |
+| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract | `children`, `isScrollable`, `padding`, `label`, `role`, root `BaseProps`, and a root `ref`. |
+| Behavior | The main content region fills the Layout's middle area, scrolls by default, and insets its children from neighbouring regions and open edges. |
+| End-user impact | People scroll the main content while headers, footers, and panels stay put, with the scrollbar at the content area's open edge. |
+| Builder impact | None: no API change; a scrolling region gains a role and a name with no code change (AR3). |
+| Compatibility/readiness | No API or default changes; the scrolling-region role and name (AR3) are a patch `[fix]`. No implementation gap is open (Current-state impact). |
+| Review checks | Reject an inner wrapper around the children, a scrollbar moved off the open edge, an inferred landmark, or a further publication mismatch. |
+| Governing rules | `family:layout-regions` FR1, FR3, FR4, FR7, FR8, FR12; `architecture:container-padding`; `architecture:public-component-api` INV5–INV8. |
This table is a review projection; the body below is authoritative.
@@ -74,26 +75,12 @@ Consumer migration instructions belong in consumer docs and release notes.
## Current-state impact
-- **Open inline-end edge keeps the inner inset beside a start panel (FR2).**
- With only a start panel, the open inline-end edge applies the inner inset
- (spacing step 4 by default) instead of the Layout-edge inset, even when the
- Layout sets `padding={0}`, so content stops short of an edge that should be
- full bleed (`family:layout-regions` FR3).
-- **Published padding differs from applied padding (FR2).** With only an end
- panel, the inline-end edge applies the inner inset beside the panel but
- publishes the Layout-edge inset. Beside a header or footer without a
- divider, the block edge applies zero but publishes the inner inset, so a
- nested full-bleed child or Layout starts one inner inset away from the
- content box. `architecture:container-padding` has a region publish its
- applied padding.
-- **Nested content inherits an outer collapse (FR2).** When an outer Layout's
- header or footer has no divider, its middle row zeroes the content's block
- spacing on that side, and a Layout nested inside that row inherits the zero,
- even inside a Dialog, Drawer, or BottomSheet opened from it, so its content
- sits flush against its own header's or footer's divider, where
- `family:layout-regions` FR6 collapses spacing only where the divider is
- absent and `spec:AST-038` FR7 stops inherited layout state at a layer
- boundary.
+None. Beside a single start panel the open inline-end edge takes the
+Layout-edge inset, so `padding={0}` on the Layout makes it full bleed; each
+edge publishes the padding it applies, so a full-bleed child lines up beside
+an end panel and beside a header or footer without a divider; and each Layout
+clears an outer header's or footer's collapse, so a nested Layout, including
+one inside a Dialog, Drawer, or BottomSheet, keeps its own block spacing (FR2).
## Ownership boundary
@@ -120,13 +107,13 @@ Consumer migration instructions belong in consumer docs and release notes.
## Behavioral and layout contract
-| ID | Invariant | Basis |
-| --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
-| FR1 | LayoutContent renders one `div` carrying the `layout-content` target that fills the middle area's height and remaining width and holds the children directly. It scrolls overflow by default; `isScrollable={false}` clips it. | Current source and tests; `family:layout-regions` FR7 |
-| FR2 | Without `padding`, each edge that faces another region (a panel, header, or footer) has the inner inset, and each open edge has the Layout-edge inset, where the Layout-edge inset comes from the Layout's `padding`, else the nearest padding container, and the inner inset from the nearest padding container (Card, Section, Dialog, Drawer, or BottomSheet), each spacing step 4 otherwise; a block edge beside a header or footer without a divider collapses to zero. A `padding` step replaces all four edges, and `0` removes them. The region publishes container-padding values equal to the padding it applies, excluding the content-width alignment gutter of FR3, which is applied but not published. Implementation gaps: with only a start panel the open inline-end edge applies the inner inset; the published values differ from the applied padding with only an end panel and beside a header or footer without a divider; and a nested Layout inherits an outer header's or footer's collapse, so its content sits flush against its own divider (Current-state impact). | Current source; `family:layout-regions` FR4, FR6; `architecture:container-padding` |
-| FR3 | When the Layout sets a content width, the region keeps its own box and scrollbar where `component:Layout` FR6 places them and aligns its children to that width through its inline padding, never less than its inset. With `padding={0}` it stays full bleed. | Current source and tests; `family:layout-regions` FR12 |
-| FR4 | `role` and `label` set the root's `role` and `aria-label`; LayoutContent adds a role and a name of its own only while it scrolls (AR3). | Current source and tests; `family:layout-regions` FR8 |
-| FR5 | `ref` reaches the root. Supported DOM, data, ARIA, and event props reach the root after the component's own attributes; `xstyle`, `className`, and `style` compose after component styles. | Current source and tests; `architecture:public-component-api` INV5–INV8 |
+| ID | Invariant | Basis |
+| --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| FR1 | LayoutContent renders one `div` carrying the `layout-content` target that fills the middle area's height and remaining width and holds the children directly. It scrolls overflow by default; `isScrollable={false}` clips it. | Current source and tests; `family:layout-regions` FR7 |
+| FR2 | Without `padding`, each edge that faces another region (a panel, header, or footer) has the inner inset, and each open edge has the Layout-edge inset, where the Layout-edge inset comes from the Layout's `padding`, else the nearest padding container, and the inner inset from the nearest padding container (Card, Section, Dialog, Drawer, or BottomSheet), each spacing step 4 otherwise; a block edge beside a header or footer without a divider collapses to zero. A `padding` step replaces all four edges, and `0` removes them. The region publishes container-padding values equal to the padding it applies, excluding the content-width alignment gutter of FR3, which is applied but not published. The collapse applies only to the Layout whose header or footer it sits beside; a nested Layout, including one across a layer boundary, does not inherit it. | Current source and audit receipts; `family:layout-regions` FR4, FR6; `architecture:container-padding`; `spec:AST-038` FR7 |
+| FR3 | When the Layout sets a content width, the region keeps its own box and scrollbar where `component:Layout` FR6 places them and aligns its children to that width through its inline padding, never less than its inset. With `padding={0}` it stays full bleed. | Current source and tests; `family:layout-regions` FR12 |
+| FR4 | `role` and `label` set the root's `role` and `aria-label`; LayoutContent adds a role and a name of its own only while it scrolls (AR3). | Current source and tests; `family:layout-regions` FR8 |
+| FR5 | `ref` reaches the root. Supported DOM, data, ARIA, and event props reach the root after the component's own attributes; `xstyle`, `className`, and `style` compose after component styles. | Current source and tests; `architecture:public-component-api` INV5–INV8 |
### Allowed variation
@@ -190,23 +177,22 @@ anatomy of its own, so no anatomy-theming block is declared here.
- `family:layout-regions` owns region scrolling, padding replacement, divider
spacing, landmarks, and content-width scrollbar placement; FR1–FR4 and AR1
apply them.
-- `architecture:container-padding` owns inset publication; FR2 applies it and
- records the gap.
+- `architecture:container-padding` owns inset publication; FR2 applies it.
- `component:Layout` owns slot placement, the Layout-edge inset, content
width, and the `layout-content` target mapping.
## Verification map
-| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
-| ------------ | -------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
-| FR1 | `LayoutSlots.test.tsx` class, scroll-owner, and Layout-slot tests | Alone; in a Layout | A lost `layout-content` class, a non-scrolling default, or an inner wrapper around the children fails. Gap: `isScrollable={false}` and the fill sizing have no check. | `audit:LayoutContent/layout` |
-| FR2, ORD1 | `LayoutSlots.test.tsx` padding test | `padding={0}`; numeric padding | Gap: the padding test checks only that the region renders, and no test covers the automatic per-edge inset, the start-panel inline-end inset, the collapse beside a header or footer without a divider, or the published values. | `audit:LayoutContent/layout` |
-| FR3 | `contentWidth.test.tsx`; stable visual baseline `core-layout--content-width-scrollbar-placement` | No panels, one panel, both; zero padding | A content region that is not full width without panels, children not aligned, or a lost full bleed fails; a scrollbar moved off its edge comes back changed for review. | `audit:LayoutContent/layout` |
-| FR4, AR1 | `LayoutSlots.test.tsx` landmark test; `Layout.a11y.test.tsx` and `Layout.a11y.chromium.spec.ts` `content-main` state | Caller `main` role and label | A lost role or name fails, including at the accessibility tree. Gap: no test asserts that a region without `role` exposes none. | `audit:LayoutContent/accessibility` |
-| FR5 | `LayoutSlots.test.tsx` ref and className/style tests | Ref; caller class and style | A ref on another element, or a dropped class or style, fails. Gap: no test covers DOM, data, or event props, or the `xstyle` merge order. | `audit:LayoutContent/api` |
-| AR2, PR1 | Source review | Scrolling region | Gap: no automated check covers keyboard scrolling or fails if LayoutContent adds a listener or measurement beyond AR3's. | `audit:LayoutContent/behavior` |
-| AR3 | `useScrollRegionProps.test.tsx` LayoutContent tests; `scrollRegionName.a11y.chromium.spec.ts` | Scrolling, fitting, labelled, `main`, not scrollable | A group role or name missing while it overflows, or present while it fits or cannot scroll, fails, in Chromium's accessibility tree too; a lost caller role or label, a default landmark name, or a tab index fails. | `audit:LayoutContent/accessibility` |
-| RTL relation | RTL audit curated D8 target (`apps/storybook/rtl-audit/targets.json`) on the `Content width with start panel` story | Start panel with a centered content width (logical padding 16px start, 144px end); LTR and RTL | A logical start/end padding pair that does not swap physical sides in RTL fails D8. | `audit:LayoutContent/i18n-rtl` |
+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
+| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
+| FR1 | `LayoutSlots.test.tsx` class, scroll-owner, and Layout-slot tests | Alone; in a Layout | A lost `layout-content` class, a non-scrolling default, or an inner wrapper around the children fails. Gap: `isScrollable={false}` and the fill sizing have no check. | `audit:LayoutContent/layout` |
+| FR2, ORD1 | `LayoutSlots.test.tsx` padding test; `LayoutContentAudit.a11y.chromium.spec.ts` `content-insets` receipts | `padding={0}`; numeric padding; start panel; end panel; header without a divider; full-bleed start panel; nested Layout; RTL | The audit receipts fail when an edge applies an inset other than the expected one, or publishes a value other than the padding it applies. Gap: no always-run check covers the automatic per-edge inset, the start-panel inline-end inset, the collapse beside a header or footer without a divider, the nested Layout, or the published values; the browser spec runs only for a LayoutContent audit pull request, so they have audit receipts only, and no receipt covers a nested Layout across a layer boundary. The padding unit test checks only that the region renders. | `audit:LayoutContent/layout` |
+| FR3 | `contentWidth.test.tsx`; stable visual baseline `core-layout--content-width-scrollbar-placement` | No panels, one panel, both; zero padding | A content region that is not full width without panels, children not aligned, or a lost full bleed fails; a scrollbar moved off its edge comes back changed for review. | `audit:LayoutContent/layout` |
+| FR4, AR1 | `LayoutSlots.test.tsx` landmark test and `exposes no role or name of its own when it does not scroll`; `Layout.a11y.test.tsx` and `Layout.a11y.chromium.spec.ts` `content-main` state | Caller `main` role and label; no caller role | A lost role or name fails, including at the accessibility tree; a role or name on a region without a caller `role` that does not scroll fails. | `audit:LayoutContent/accessibility` |
+| FR5 | `LayoutSlots.test.tsx` ref, className/style, and `forwards DOM, data, and event props to the root` tests | Ref; caller class and style; DOM, data, and event props | A ref on another element, or a dropped class, style, DOM, data, or event prop, fails. Gap: no test pins the `xstyle` merge order. | `audit:LayoutContent/api` |
+| AR2, PR1 | Source review | Scrolling region | Gap: no automated check covers keyboard scrolling or fails if LayoutContent adds a listener or measurement beyond AR3's. | `audit:LayoutContent/behavior` |
+| AR3 | `useScrollRegionProps.test.tsx` LayoutContent tests; `scrollRegionName.a11y.chromium.spec.ts` | Scrolling, fitting, labelled, `main`, not scrollable | A group role or name missing while it overflows, or present while it fits or cannot scroll, fails, in Chromium's accessibility tree too; a lost caller role or label, a default landmark name, or a tab index fails. | `audit:LayoutContent/accessibility` |
+| RTL relation | RTL audit curated D8 target (`apps/storybook/rtl-audit/targets.json`) on the `Content width with start panel` story | Start panel with a centered content width (logical padding 16px start, 144px end); LTR and RTL | A logical start/end padding pair that does not swap physical sides in RTL fails D8. | `audit:LayoutContent/i18n-rtl` |
## Decision log
diff --git a/docs/specs/components/Layout/LayoutFooter.spec.md b/docs/specs/components/Layout/LayoutFooter.spec.md
index 266be2737c..945ebf327e 100644
--- a/docs/specs/components/Layout/LayoutFooter.spec.md
+++ b/docs/specs/components/Layout/LayoutFooter.spec.md
@@ -36,15 +36,15 @@ system_specs: [spec:AST-038]
## Contract at a glance
-| Area | Contract |
-| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
-| Public contract | `children`, `hasDivider`, `height`, `padding`, `label`, `role`, root `BaseProps`, and a root `ref`. |
-| Behavior | A non-shrinking footer region whose inner wrapper applies and publishes the Layout inset and aligns to the Layout's content width. |
-| End-user impact | People see a footer that keeps its height below scrolling content, with content aligned to the page's readable width. |
-| Builder impact | None; the record describes shipped behavior. |
-| Compatibility/readiness | Released behavior recorded as current; no API, default, or output changes. Two implementation gaps are listed under Current-state impact. |
-| Review checks | Reject a footer that shrinks, a published inset that differs from the applied padding, an inferred landmark, or a lost divider default. |
-| Governing rules | `family:layout-regions` FR1, FR4–FR6, FR8; `architecture:container-padding`; `architecture:public-component-api` INV5–INV8. |
+| Area | Contract |
+| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract | `children`, `hasDivider`, `height`, `padding`, `label`, `role`, root `BaseProps`, and a root `ref`. |
+| Behavior | A non-shrinking footer region whose inner wrapper applies and publishes the Layout inset and aligns to the Layout's content width. |
+| End-user impact | People see a footer that keeps its height below scrolling content, with content aligned to the page's readable width. |
+| Builder impact | None; the record describes shipped behavior. |
+| Compatibility/readiness | Released behavior recorded as current; no API, default, or output changes. One implementation gap is listed under Current-state impact. |
+| Review checks | Reject a footer that shrinks, a published inset that differs from the applied padding, an inferred landmark, or a lost divider default. |
+| Governing rules | `family:layout-regions` FR1, FR4–FR6, FR8; `architecture:container-padding`; `architecture:public-component-api` INV5–INV8. |
This table is a review projection; the body below is authoritative.
@@ -74,11 +74,6 @@ Consumer migration instructions belong in consumer docs and release notes.
it: `data-divider="false"` draws no line yet stops the middle row above
from collapsing its spacing, where `architecture:public-component-api` INV5
keeps component-owned behavior from being overwritten.
-- **Nested Layouts inherit the collapse (FR3).** When this footer has no
- divider, Layouts nested in the middle row, including inside a Dialog,
- Drawer, or BottomSheet opened from it, inherit its spacing collapse and sit
- flush against their own dividers (`family:layout-regions` FR6;
- `spec:AST-038` FR7).
## Ownership boundary
@@ -105,13 +100,13 @@ Consumer migration instructions belong in consumer docs and release notes.
## Behavioral and layout contract
-| ID | Invariant | Basis |
-| --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
-| FR1 | LayoutFooter renders a root `div` carrying the `layout-footer` target that does not shrink, around an inner `div` that holds the children, has the Layout's content width as its maximum width, and centers within the root. `height` fixes the root's block size, with numbers as pixels. | Current source and tests |
-| FR2 | Without `padding`, the inner wrapper's inline and block-end padding is the Layout-edge inset and its block-start padding is the inner inset, where the Layout-edge inset comes from the Layout's `padding`, else the nearest padding container, and the inner inset from the nearest padding container (Card, Section, Dialog, Drawer, or BottomSheet), each spacing step 4 otherwise. A `padding` step replaces all four edges, and `0` removes them. The wrapper publishes container-padding values equal to the padding it applies. | Current source and tests; `family:layout-regions` FR4; `architecture:container-padding` |
-| FR3 | A divider draws a 1px solid `--color-border` line on the root's block-start edge and reflects `data-divider="true"`. `hasDivider` decides; when unset, the nearest Layout `defaultHasDividers` in the same layer decides (the default stops at a layer boundary, `spec:AST-038` FR7); otherwise there is no divider. A footer without a divider lets the middle row above it collapse its block-end spacing. Implementation gap: Layouts nested in that middle row, including inside a Dialog, Drawer, or BottomSheet opened from it, inherit the collapse (`component:LayoutContent` Current-state impact; `spec:AST-038` FR7). | Current source and tests; `family:layout-regions` FR6 |
-| FR4 | `role` and `label` set the root's `role` and `aria-label`; LayoutFooter adds no role of its own. | Current source and tests; `family:layout-regions` FR8 |
-| FR5 | `ref` reaches the root. Supported DOM, data, ARIA, and event props reach the root, `xstyle`, `className`, and `style` compose after component styles, and the reflected `data-divider` stays component-owned (`architecture:public-component-api` INV5). Implementation gap: caller props spread after `data-divider`, so a caller `data-divider` replaces the reflected value and changes the neighbouring spacing collapse (Current-state impact). | Current source and tests; `architecture:public-component-api` INV5–INV8 |
+| ID | Invariant | Basis |
+| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
+| FR1 | LayoutFooter renders a root `div` carrying the `layout-footer` target that does not shrink, around an inner `div` that holds the children, has the Layout's content width as its maximum width, and centers within the root. `height` fixes the root's block size, with numbers as pixels. | Current source and tests |
+| FR2 | Without `padding`, the inner wrapper's inline and block-end padding is the Layout-edge inset and its block-start padding is the inner inset, where the Layout-edge inset comes from the Layout's `padding`, else the nearest padding container, and the inner inset from the nearest padding container (Card, Section, Dialog, Drawer, or BottomSheet), each spacing step 4 otherwise. A `padding` step replaces all four edges, and `0` removes them. The wrapper publishes container-padding values equal to the padding it applies. | Current source and tests; `family:layout-regions` FR4; `architecture:container-padding` |
+| FR3 | A divider draws a 1px solid `--color-border` line on the root's block-start edge and reflects `data-divider="true"`. `hasDivider` decides; when unset, the nearest Layout `defaultHasDividers` in the same layer decides (the default stops at a layer boundary, `spec:AST-038` FR7); otherwise there is no divider. A footer without a divider lets the middle row above it collapse its block-end spacing. The collapse stops at each Layout, so a Layout nested in that middle row, including inside a Dialog, Drawer, or BottomSheet opened from it, keeps its own spacing (`spec:AST-038` FR7). | Current source and tests; `family:layout-regions` FR6 |
+| FR4 | `role` and `label` set the root's `role` and `aria-label`; LayoutFooter adds no role of its own. | Current source and tests; `family:layout-regions` FR8 |
+| FR5 | `ref` reaches the root. Supported DOM, data, ARIA, and event props reach the root, `xstyle`, `className`, and `style` compose after component styles, and the reflected `data-divider` stays component-owned (`architecture:public-component-api` INV5). Implementation gap: caller props spread after `data-divider`, so a caller `data-divider` replaces the reflected value and changes the neighbouring spacing collapse (Current-state impact). | Current source and tests; `architecture:public-component-api` INV5–INV8 |
### Allowed variation
@@ -166,14 +161,14 @@ of its own, so no anatomy-theming block is declared here.
## Verification map
-| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
-| --------- | -------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- |
-| FR1 | `LayoutSlots.test.tsx` class test; `contentWidth.test.tsx` LayoutFooter inner-wrapper and divider tests | Default; content width | A lost `layout-footer` class, children placed on the root instead of the inner wrapper, or a divider off the outer element fails. Gap: `height`, the non-shrinking root, the content-width maximum, and centering have no check. | `audit:LayoutFooter/layout` |
-| FR2, ORD2 | Source review | Automatic, explicit, and zero padding | Gap: no test covers the automatic inset, the `padding` replacement, full bleed, or the published values. | `audit:LayoutFooter/layout` |
-| FR3, ORD1 | `LayoutSlots.test.tsx` and `Layout.test.tsx` divider tests | Default; `hasDivider`; Layout default | A missing or unexpected `data-divider`, or an ignored Layout default, fails. Gap: no test covers an explicit `false` beating a Layout default on a footer. Gap: the line's paint and the collapsed spacing above a footer without a divider have no check. No test covers the default stopping at a layer boundary or the inherited nested collapse. | `audit:LayoutFooter/layout` |
-| FR4, AR1 | `LayoutSlots.test.tsx` landmark test; `Layout.a11y.test.tsx` and `Layout.a11y.chromium.spec.ts` `footer-contentinfo` state | Caller `contentinfo` role and label | A lost role or name fails, including at the accessibility tree. Gap: no test asserts that a footer without `role` exposes none. | `audit:LayoutFooter/accessibility` |
-| FR5 | `LayoutSlots.test.tsx` ref test | Ref | A ref on another element fails. Gap: no test covers `className`, `style`, DOM, data, or event props, or the `xstyle` merge order. No test covers a caller `data-divider`. | `audit:LayoutFooter/api` |
-| PR1 | Source review | Every state | Gap: no automated check fails if LayoutFooter adds a listener, timer, or measurement. | `audit:LayoutFooter/behavior` |
+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
+| --------- | -------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- |
+| FR1 | `LayoutSlots.test.tsx` class test; `contentWidth.test.tsx` LayoutFooter inner-wrapper and divider tests | Default; content width | A lost `layout-footer` class, children placed on the root instead of the inner wrapper, or a divider off the outer element fails. Gap: `height`, the non-shrinking root, the content-width maximum, and centering have no check. | `audit:LayoutFooter/layout` |
+| FR2, ORD2 | Source review | Automatic, explicit, and zero padding | Gap: no test covers the automatic inset, the `padding` replacement, full bleed, or the published values. | `audit:LayoutFooter/layout` |
+| FR3, ORD1 | `LayoutSlots.test.tsx` and `Layout.test.tsx` divider tests | Default; `hasDivider`; Layout default | A missing or unexpected `data-divider`, or an ignored Layout default, fails. Gap: no test covers an explicit `false` beating a Layout default on a footer. Gap: the line's paint and the collapsed spacing above a footer without a divider have no check. No test covers the default stopping at a layer boundary for a footer. The collapse stopping at a nested Layout has audit receipts only for a header (`LayoutContentAudit.a11y.chromium.spec.ts` `content-insets`), and none for a footer. | `audit:LayoutFooter/layout` |
+| FR4, AR1 | `LayoutSlots.test.tsx` landmark test; `Layout.a11y.test.tsx` and `Layout.a11y.chromium.spec.ts` `footer-contentinfo` state | Caller `contentinfo` role and label | A lost role or name fails, including at the accessibility tree. Gap: no test asserts that a footer without `role` exposes none. | `audit:LayoutFooter/accessibility` |
+| FR5 | `LayoutSlots.test.tsx` ref test | Ref | A ref on another element fails. Gap: no test covers `className`, `style`, DOM, data, or event props, or the `xstyle` merge order. No test covers a caller `data-divider`. | `audit:LayoutFooter/api` |
+| PR1 | Source review | Every state | Gap: no automated check fails if LayoutFooter adds a listener, timer, or measurement. | `audit:LayoutFooter/behavior` |
## Decision log
diff --git a/docs/specs/components/Layout/LayoutHeader.spec.md b/docs/specs/components/Layout/LayoutHeader.spec.md
index 93ba8031a0..330d0dc524 100644
--- a/docs/specs/components/Layout/LayoutHeader.spec.md
+++ b/docs/specs/components/Layout/LayoutHeader.spec.md
@@ -36,15 +36,15 @@ system_specs: [spec:AST-038]
## Contract at a glance
-| Area | Contract |
-| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
-| Public contract | `children`, `hasDivider`, `height`, `padding`, `paddingBlockEnd`, `label`, `role`, root `BaseProps`, and a root `ref`. |
-| Behavior | A non-shrinking header region whose inner wrapper applies and publishes the Layout inset and aligns to the Layout's content width. |
-| End-user impact | People see a header that keeps its height above scrolling content, with content aligned to the page's readable width. |
-| Builder impact | None; the record describes shipped behavior. |
-| Compatibility/readiness | Released behavior recorded as current; no API, default, or output changes. Two implementation gaps are listed under Current-state impact. |
-| Review checks | Reject a header that shrinks, a published inset that differs from the applied padding, an inferred landmark, or a lost divider default. |
-| Governing rules | `family:layout-regions` FR1, FR4–FR6, FR8; `architecture:container-padding`; `architecture:public-component-api` INV5–INV8. |
+| Area | Contract |
+| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract | `children`, `hasDivider`, `height`, `padding`, `paddingBlockEnd`, `label`, `role`, root `BaseProps`, and a root `ref`. |
+| Behavior | A non-shrinking header region whose inner wrapper applies and publishes the Layout inset and aligns to the Layout's content width. |
+| End-user impact | People see a header that keeps its height above scrolling content, with content aligned to the page's readable width. |
+| Builder impact | None; the record describes shipped behavior. |
+| Compatibility/readiness | Released behavior recorded as current; no API, default, or output changes. One implementation gap is listed under Current-state impact. |
+| Review checks | Reject a header that shrinks, a published inset that differs from the applied padding, an inferred landmark, or a lost divider default. |
+| Governing rules | `family:layout-regions` FR1, FR4–FR6, FR8; `architecture:container-padding`; `architecture:public-component-api` INV5–INV8. |
This table is a review projection; the body below is authoritative.
@@ -74,11 +74,6 @@ Consumer migration instructions belong in consumer docs and release notes.
it: `data-divider="false"` draws no line yet stops the middle row below
from collapsing its spacing, where `architecture:public-component-api` INV5
keeps component-owned behavior from being overwritten.
-- **Nested Layouts inherit the collapse (FR3).** When this header has no
- divider, Layouts nested in the middle row, including inside a Dialog,
- Drawer, or BottomSheet opened from it, inherit its spacing collapse and sit
- flush against their own dividers (`family:layout-regions` FR6;
- `spec:AST-038` FR7).
## Ownership boundary
@@ -106,13 +101,13 @@ Consumer migration instructions belong in consumer docs and release notes.
## Behavioral and layout contract
-| ID | Invariant | Basis |
-| --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
-| FR1 | LayoutHeader renders a root `div` carrying the `layout-header` target that does not shrink, around an inner `div` that holds the children, has the Layout's content width as its maximum width, and centers within the root. `height` fixes the root's block size, with numbers as pixels. | Current source and tests |
-| FR2 | Without `padding`, the inner wrapper's inline and block-start padding is the Layout-edge inset and its block-end padding is the inner inset, where the Layout-edge inset comes from the Layout's `padding`, else the nearest padding container, and the inner inset from the nearest padding container (Card, Section, Dialog, Drawer, or BottomSheet), each spacing step 4 otherwise. A `padding` step replaces all four edges, and `0` removes them. `paddingBlockEnd` replaces the block-end edge alone. The wrapper publishes container-padding values equal to the padding it applies. | Current source and tests; `family:layout-regions` FR4; `architecture:container-padding` |
-| FR3 | A divider draws a 1px solid `--color-border` line on the root's block-end edge and reflects `data-divider="true"`. `hasDivider` decides; when unset, the nearest Layout `defaultHasDividers` in the same layer decides (the default stops at a layer boundary, `spec:AST-038` FR7); otherwise there is no divider. A header without a divider lets the middle row below it collapse its block-start spacing. Implementation gap: Layouts nested in that middle row, including inside a Dialog, Drawer, or BottomSheet opened from it, inherit the collapse (`component:LayoutContent` Current-state impact; `spec:AST-038` FR7). | Current source and tests; `family:layout-regions` FR6 |
-| FR4 | `role` and `label` set the root's `role` and `aria-label`; LayoutHeader adds no role of its own. | Current source and tests; `family:layout-regions` FR8 |
-| FR5 | `ref` reaches the root. Supported DOM, data, ARIA, and event props reach the root, `xstyle`, `className`, and `style` compose after component styles, and the reflected `data-divider` stays component-owned (`architecture:public-component-api` INV5). Implementation gap: caller props spread after `data-divider`, so a caller `data-divider` replaces the reflected value and changes the neighbouring spacing collapse (Current-state impact). | Current source and tests; `architecture:public-component-api` INV5–INV8 |
+| ID | Invariant | Basis |
+| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
+| FR1 | LayoutHeader renders a root `div` carrying the `layout-header` target that does not shrink, around an inner `div` that holds the children, has the Layout's content width as its maximum width, and centers within the root. `height` fixes the root's block size, with numbers as pixels. | Current source and tests |
+| FR2 | Without `padding`, the inner wrapper's inline and block-start padding is the Layout-edge inset and its block-end padding is the inner inset, where the Layout-edge inset comes from the Layout's `padding`, else the nearest padding container, and the inner inset from the nearest padding container (Card, Section, Dialog, Drawer, or BottomSheet), each spacing step 4 otherwise. A `padding` step replaces all four edges, and `0` removes them. `paddingBlockEnd` replaces the block-end edge alone. The wrapper publishes container-padding values equal to the padding it applies. | Current source and tests; `family:layout-regions` FR4; `architecture:container-padding` |
+| FR3 | A divider draws a 1px solid `--color-border` line on the root's block-end edge and reflects `data-divider="true"`. `hasDivider` decides; when unset, the nearest Layout `defaultHasDividers` in the same layer decides (the default stops at a layer boundary, `spec:AST-038` FR7); otherwise there is no divider. A header without a divider lets the middle row below it collapse its block-start spacing. The collapse stops at each Layout, so a Layout nested in that middle row, including inside a Dialog, Drawer, or BottomSheet opened from it, keeps its own spacing (`spec:AST-038` FR7). | Current source and tests; `family:layout-regions` FR6 |
+| FR4 | `role` and `label` set the root's `role` and `aria-label`; LayoutHeader adds no role of its own. | Current source and tests; `family:layout-regions` FR8 |
+| FR5 | `ref` reaches the root. Supported DOM, data, ARIA, and event props reach the root, `xstyle`, `className`, and `style` compose after component styles, and the reflected `data-divider` stays component-owned (`architecture:public-component-api` INV5). Implementation gap: caller props spread after `data-divider`, so a caller `data-divider` replaces the reflected value and changes the neighbouring spacing collapse (Current-state impact). | Current source and tests; `architecture:public-component-api` INV5–INV8 |
### Allowed variation
@@ -169,14 +164,14 @@ of its own, so no anatomy-theming block is declared here.
## Verification map
-| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
-| --------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- |
-| FR1 | `LayoutSlots.test.tsx` class, height, and inner-wrapper tests; `contentWidth.test.tsx` LayoutHeader inner-wrapper and divider tests | Default; numeric height | A lost `layout-header` class, a missing pixel height, children placed directly on the root, or a divider off the outer element fails. Gap: the non-shrinking root, the content-width maximum, and centering have no check. | `audit:LayoutHeader/layout` |
-| FR2, ORD2 | `Layout.test.tsx` `paddingBlockEnd` tests | `paddingBlockEnd` alone and with `padding` | A `paddingBlockEnd` that adds no class, changes more than the block-end edge, or leaves the shared per-edge family fails. Gap: the automatic inset, the `padding` replacement, full bleed, and the published values have no check. | `audit:LayoutHeader/layout` |
-| FR3, ORD1 | `LayoutSlots.test.tsx` and `Layout.test.tsx` divider tests | Default; `hasDivider`; Layout default; explicit `false` | A missing or unexpected `data-divider`, an ignored Layout default, or an explicit `false` that loses fails. Gap: the line's paint and the collapsed spacing below a header without a divider have no check. No test covers the default stopping at a layer boundary or the inherited nested collapse. | `audit:LayoutHeader/layout` |
-| FR4, AR1 | `LayoutSlots.test.tsx` landmark test; `Layout.a11y.test.tsx` and `Layout.a11y.chromium.spec.ts` `header-banner` state | Caller `banner` role and label | A lost role or name fails, including at the accessibility tree. Gap: no test asserts that a header without `role` exposes none. | `audit:LayoutHeader/accessibility` |
-| FR5 | `LayoutSlots.test.tsx` ref and className tests | Ref; caller class | A ref on another element or a dropped class fails. Gap: no test covers DOM, data, or event props, `style`, or the `xstyle` merge order. No test covers a caller `data-divider`. | `audit:LayoutHeader/api` |
-| PR1 | Source review | Every state | Gap: no automated check fails if LayoutHeader adds a listener, timer, or measurement. | `audit:LayoutHeader/behavior` |
+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
+| --------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- |
+| FR1 | `LayoutSlots.test.tsx` class, height, and inner-wrapper tests; `contentWidth.test.tsx` LayoutHeader inner-wrapper and divider tests | Default; numeric height | A lost `layout-header` class, a missing pixel height, children placed directly on the root, or a divider off the outer element fails. Gap: the non-shrinking root, the content-width maximum, and centering have no check. | `audit:LayoutHeader/layout` |
+| FR2, ORD2 | `Layout.test.tsx` `paddingBlockEnd` tests | `paddingBlockEnd` alone and with `padding` | A `paddingBlockEnd` that adds no class, changes more than the block-end edge, or leaves the shared per-edge family fails. Gap: the automatic inset, the `padding` replacement, full bleed, and the published values have no check. | `audit:LayoutHeader/layout` |
+| FR3, ORD1 | `LayoutSlots.test.tsx` and `Layout.test.tsx` divider tests, including `stops the default at a layer boundary` | Default; `hasDivider`; Layout default; explicit `false` | A missing or unexpected `data-divider`, an ignored Layout default, or an explicit `false` that loses fails. Gap: the line's paint and the collapsed spacing below a header without a divider have no check. The collapse stopping at a nested Layout has audit receipts only (`LayoutContentAudit.a11y.chromium.spec.ts` `content-insets`), not an always-run check. | `audit:LayoutHeader/layout` |
+| FR4, AR1 | `LayoutSlots.test.tsx` landmark test; `Layout.a11y.test.tsx` and `Layout.a11y.chromium.spec.ts` `header-banner` state | Caller `banner` role and label | A lost role or name fails, including at the accessibility tree. Gap: no test asserts that a header without `role` exposes none. | `audit:LayoutHeader/accessibility` |
+| FR5 | `LayoutSlots.test.tsx` ref and className tests | Ref; caller class | A ref on another element or a dropped class fails. Gap: no test covers DOM, data, or event props, `style`, or the `xstyle` merge order. No test covers a caller `data-divider`. | `audit:LayoutHeader/api` |
+| PR1 | Source review | Every state | Gap: no automated check fails if LayoutHeader adds a listener, timer, or measurement. | `audit:LayoutHeader/behavior` |
## Decision log