An open source design system that's fully customizable and agent ready
TypeScript
docs(specs): LayoutHeader and LayoutFooter records state that a caller data-divider never replaces the divider state (#10714)
Cindy Zhangc86484dc5784
diff --git a/docs/specs/components/Layout/LayoutFooter.spec.md b/docs/specs/components/Layout/LayoutFooter.spec.mdindex 945ebf327e..768797a93f 100644--- a/docs/specs/components/Layout/LayoutFooter.spec.md+++ b/docs/specs/components/Layout/LayoutFooter.spec.md@@ -42,7 +42,7 @@ system_specs: [spec:AST-038]| 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. |+| 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 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. |@@ -69,11 +69,7 @@ Consumer migration instructions belong in consumer docs and release notes.## Current-state impact-- **Caller `data-divider` overrides the reflected divider (FR5).** Caller- props spread after the component's `data-divider`, so a caller value replaces- 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.+None.## Ownership boundary@@ -106,7 +102,7 @@ Consumer migration instructions belong in consumer docs and release notes.| 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 |+| 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: a caller's `data-divider` never replaces it, so the neighbouring spacing collapse always follows the divider state (`architecture:public-component-api` INV5). | Current source and tests; `architecture:public-component-api` INV5–INV8 |### Allowed variation@@ -161,14 +157,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 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` |+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |+| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- |+| FR1 | `LayoutSlots.test.tsx` class and `applies a numeric height as pixels on the root` tests; `contentWidth.test.tsx` LayoutFooter inner-wrapper and divider tests | Default; numeric height; content width | A lost `layout-footer` class, a missing pixel height, children placed on the root instead of the inner wrapper, or a divider off the outer element fails. Gap: 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, including `an explicit hasDivider={false} on a footer overrides the context default` and `stops the footer default at a layer boundary` | Default; `hasDivider`; Layout default; explicit `false`; Layout default across a layer boundary | A missing or unexpected `data-divider`, an ignored Layout default, an explicit `false` that loses, or a Layout default that crosses a layer boundary fails. Gap: the line's paint and the collapsed spacing above a footer without a divider have no check. The collapse stopping at a nested Layout has audit receipts only (`LayoutFooterAudit.a11y.chromium.spec.ts` `nested` case), not an always-run check. | `audit:LayoutFooter/layout` |+| FR4, AR1 | `LayoutSlots.test.tsx` landmark and `exposes no role or name without a caller role` tests; `Layout.a11y.test.tsx` and `Layout.a11y.chromium.spec.ts` `footer-contentinfo` state | Caller `contentinfo` role and label; no caller role | A lost role or name fails, including at the accessibility tree. A footer without a caller `role` that exposes a role or name fails. | `audit:LayoutFooter/accessibility` |+| FR5 | `LayoutSlots.test.tsx` ref, `passes className, style, DOM, data, and event props to the root`, and `keeps data-divider when a caller passes its own value` tests | Ref; caller class, style, DOM, data, and event props; caller `data-divider` | A ref on another element, a dropped caller prop, or a caller `data-divider` that replaces or removes the reflected value fails. Gap: no test covers the `xstyle` merge order. The spacing above a footer with a caller `data-divider` has audit receipts only (`LayoutFooterAudit.a11y.chromium.spec.ts` `caller-attribute` case), not an always-run check. | `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 logdiff --git a/docs/specs/components/Layout/LayoutHeader.spec.md b/docs/specs/components/Layout/LayoutHeader.spec.mdindex 330d0dc524..bad9b582b0 100644--- a/docs/specs/components/Layout/LayoutHeader.spec.md+++ b/docs/specs/components/Layout/LayoutHeader.spec.md@@ -42,7 +42,7 @@ system_specs: [spec:AST-038]| 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. |+| 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 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. |@@ -69,11 +69,7 @@ Consumer migration instructions belong in consumer docs and release notes.## Current-state impact-- **Caller `data-divider` overrides the reflected divider (FR5).** Caller- props spread after the component's `data-divider`, so a caller value replaces- 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.+None.## Ownership boundary@@ -107,7 +103,7 @@ Consumer migration instructions belong in consumer docs and release notes.| 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 |+| 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: a caller's `data-divider` never replaces it, so the neighbouring spacing collapse always follows the divider state (`architecture:public-component-api` INV5). | Current source and tests; `architecture:public-component-api` INV5–INV8 |### Allowed variation@@ -164,14 +160,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, 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` |+| 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 and `exposes no role or name without a caller role` tests; `Layout.a11y.test.tsx` and `Layout.a11y.chromium.spec.ts` `header-banner` state | Caller `banner` role and label; no caller role | A lost role or name fails, including at the accessibility tree. A header without a caller `role` that exposes a role or name fails. | `audit:LayoutHeader/accessibility` |+| FR5 | `LayoutSlots.test.tsx` ref, className, `passes style, DOM, data, and event props to the root`, and `keeps data-divider when a caller passes its own value` tests | Ref; caller class, style, DOM, data, and event props; caller `data-divider` | A ref on another element, a dropped class or caller prop, or a caller `data-divider` that replaces or removes the reflected value fails. Gap: no test covers the `xstyle` merge order. The spacing below a header with a caller `data-divider` has audit receipts only (`LayoutHeaderAudit.a11y.chromium.spec.ts` `caller-attribute` case), not an always-run check. | `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