An open source design system that's fully customizable and agent ready
schema_version: 3 template_version: 7 kind: component id: component:LayoutHeader authority: current archive_reason: null superseded_by: null approved_by: cixzhang approved_at: 2026-10-30 owners: [cixzhang] review_triggers: [public-api, behavior, layout, theming, accessibility] verified_by: [ packages/core/src/Layout/LayoutSlots.test.tsx, packages/core/src/Layout/Layout.test.tsx, 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/LayoutHeaderFooterEdges.a11y.browser.spec.ts, packages/core/src/Layout/tests/headerFooterXstyle.test.tsx, scripts/check-knowledge.mjs, ] modules: [] families: [family:layout-regions] design_specs: [] architecture: [ architecture:container-padding, architecture:component-theming-surface, architecture:public-component-api, ] contributing: []
system_specs: [spec:AST-038]
LayoutHeader component contract
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. 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. |
This table is a review projection; the body below is authoritative.
Intent
LayoutHeader is the optional header region a caller places in a Layout's
header slot. It owns the header's size, inset, divider, and caller-supplied
landmark semantics; the caller owns its content.
Consumer syntax and examples belong in LayoutHeader.doc.mjs.
Compatibility and migration
- Released default preserved:
yes— no divider unless a Layout default says so, automatic inset, no landmark role. - Compatibility class: records shipped behavior; no public prop, default, DOM, target, or styling output changes.
- Controlled/uncontrolled behavior: not applicable
- Migration decision: none
Consumer migration instructions belong in consumer docs and release notes.
Current-state impact
None.
Ownership boundary
Owns
- The header root, which carries the
layout-headertarget thatcomponent:Layoutmaps, and its inner padding wrapper. - Header height, divider, inset, and caller-supplied role and label.
Does not own / non-goals
- Slot placement, the Layout-edge inset, content width, and the divider
default — owned by
component:Layout. - Header content and its meaning — owned by the caller.
Public concepts
| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |
|---|---|---|---|---|---|---|---|
| Divider | true, false, unset |
Draws a line on the header's block-end edge. | Always | Layout default, else none | component:LayoutHeader |
Stable | — |
| Height | number (px); CSS length string; unset | Fixes the header's block size. | Always | content height | component:LayoutHeader |
Stable | — |
| Inset | spacing step; 0; unset |
Uniform padding that replaces the automatic inset; 0 is full bleed. |
Always | automatic | component:LayoutHeader |
Stable | Closed union; rejected by types. |
| Block-end inset | spacing step; unset | Replaces the block-end padding alone. | Always | automatic | component:LayoutHeader |
Stable | Closed union; rejected by types. |
| Landmark | caller role and label |
Exposes the header as the role the caller names, with that accessible name. | Always | none | caller | Stable | — |
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. 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: 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
- AV1 — Content. Any caller content may fill the header.
- AV2 — Landmark. The caller chooses whether the header is a landmark and which one.
Representative states
| State | Required invariant | Allowed variation |
|---|---|---|
| Default in Layout | Automatic inset, no divider, no role. | Content. |
| With divider | Block-end line and data-divider="true". |
— |
| Explicit padding | Uniform padding, published to children. | Step. |
paddingBlockEnd |
Only the block-end edge changes. | Step. |
| Banner landmark | role="banner" and the caller's name on the root. |
Name. |
Transformation and precedence order
- ORD1 — Divider.
hasDivider→ LayoutdefaultHasDividers→ none. - ORD2 — Padding.
paddingBlockEndfor block-end →padding→ the automatic inset.
Performance and resources
- PR1 — No external lifecycle. LayoutHeader reads the divider default from its Layout and adds no listener, observer, timer, or measurement.
Accessibility contract
- AR1 — Explicit landmarks only. The header is a landmark only when the
caller supplies
role, and it is named only by the caller'slabel(family:layout-regionsFR8).
Design relationships
| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
|---|---|---|---|---|
| Header | A fixed header band with an optional block-end divider. | Current source and docs | Supporting | FR1–FR3 |
Theming: the root carries the layout-header target, which Layout.doc.mjs
declares and component:Layout maps. LayoutHeader.doc.mjs declares no anatomy
of its own, so no anatomy-theming block is declared here.
Family and system relationships
family:layout-regionsowns region boundaries, padding replacement, divider spacing, and landmark rules; FR2–FR4 and AR1 apply them.architecture:container-paddingowns inset publication; FR2 applies it.component:Layoutowns slot placement, the Layout-edge inset, content width, the divider default, and thelayout-headertarget mapping.architecture:public-component-apiowns caller-input routing; FR5 applies it.
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; headerFooterXstyle.test.tsx keeps the own styles that xstyle does not set (non-shrinking root) |
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. A header root that shrinks fails. Gap: the content-width maximum and centering have no check. |
audit:LayoutHeader/layout |
| FR2, ORD2 | Layout.test.tsx paddingBlockEnd tests; LayoutHeaderFooterEdges.a11y.browser.spec.ts per-case insets and published values |
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. An inset that differs from the expected step on any edge (automatic, padding, full bleed, or a nested Layout), or a published value that differs from the applied padding, fails. Gap: the automatic inset taken from a surrounding Card, Section, Dialog, Drawer or BottomSheet has no named check; the edge spec renders each case in a plain frame. |
audit:LayoutHeader/layout |
| FR3, ORD1 | LayoutSlots.test.tsx and Layout.test.tsx divider tests, including stops the default at a layer boundary; LayoutHeaderFooterEdges.a11y.browser.spec.ts line paint and the collapse of the content below the header, including where it stops at a nested Layout |
Default; hasDivider; Layout default; explicit false |
A missing or unexpected data-divider, an ignored Layout default, or an explicit false that loses fails. A line that is not 1px solid --color-border, a line without data-divider="true", or content below the header that does not collapse without a divider, or collapses past a nested Layout, fails. |
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; headerFooterXstyle.test.tsx xstyle merge-order tests; LayoutHeaderFooterEdges.a11y.browser.spec.ts caller-attribute case |
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. An xstyle that loses to the header's own styles, or a caller data-divider that changes the spacing below the header, fails. |
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
None recorded. The record describes shipped behavior.
Open questions
None.
Content boundary
This file does not duplicate consumer prop tables/examples, current audit results, implementation steps, Layout slot rules, or container-padding mechanics. It links to their owners.