An open source design system that's fully customizable and agent ready
TypeScript
docs: define layout regions family (#5744)
Cindy Zhang3828a31d5b73
diff --git a/docs/families/layout-regions.md b/docs/families/layout-regions.mdnew file mode 100644index 0000000000..0e73142941--- /dev/null+++ b/docs/families/layout-regions.md@@ -0,0 +1,255 @@+---+schema_version: 1+template_version: 1+kind: family+id: family:layout-regions+authority: current+archive_reason: null+superseded_by: null+approved_by: cixzhang+approved_at: 2026-08-30+owners: [cixzhang, imdreamrunner]+review_triggers: [public-api, behavior, layout, accessibility, theming]+verified_by:+ [+ packages/core/src/Section/Section.test.tsx,+ packages/core/src/Layout/Layout.test.tsx,+ packages/core/src/Layout/LayoutSlots.test.tsx,+ packages/core/src/Layout/__tests__/childrenAsContent.test.tsx,+ packages/core/src/Layout/__tests__/contentWidth.test.tsx,+ packages/core/src/Toolbar/Toolbar.test.tsx,+ ]+members:+ [+ component:Section,+ component:Layout,+ component:LayoutHeader,+ component:LayoutContent,+ component:LayoutFooter,+ component:LayoutPanel,+ component:Toolbar,+ ]+architecture:+ [architecture:container-padding, architecture:public-component-api]+contributing: []+deciding_specs: []+---++# Layout regions contract++## Intent++A page or bounded work area should have predictable structural regions before+its product content is added. Builders can use a generic Section, a named Layout+shell, or a contextual Toolbar without each surface inventing its own inset,+boundary, region direction, or content ownership.++## Membership rule++A component belongs when its primary public purpose is defining a stable+structural region: a generic page/content region, a named shell region, or a+contextual action region. Members may compose shared layout primitives, but they+own a stronger boundary than arbitrary-child arrangement alone.++- **Members:** Section; Layout and its Header, Content, Footer, and Panel regions;+ Toolbar.+- **Collaborators:** `family:layout-primitives` supplies arrangement utilities;+ `architecture:container-padding` supplies inset and bleed geometry;+ useResizable and ResizeHandle may drive a panel's size; AppShell composes page+ regions; component theming owns visual targets.+- **Excluded:** Stack, Grid, Center, and their modifiers arrange arbitrary+ children without claiming a structural region. FormLayout owns field-specific+ arrangement and optionality. Card is a discrete-item surface. AppShell and+ navigation components own application/navigation semantics rather than this+ region grammar.++A component does not join because it happens to render a flex row, a padded+wrapper, or a header-like visual treatment.++## Shared owner++- Section owns the generic painted page/content region, including its variant,+ selected divider edges, component padding, and nested Section behavior.+- Layout owns shell topology, slot presence, region position, shared outer/inner+ inset, height mode, content-width propagation, and default header/footer+ divider context.+- LayoutHeader, LayoutContent, LayoutFooter, and LayoutPanel own their region+ element, optional landmark role/name, local padding, and region-specific size+ or scrolling behavior.+- Toolbar owns the contextual action region, its start/center/end lanes,+ toolbar semantics, keyboard movement, and size cascade. It delegates its+ painted surface, variant, and selected divider edges to Section.+- `architecture:container-padding` owns inherited inset and bleed mechanics.+- useResizable and ResizeHandle own resize state and interaction. LayoutPanel+ only accepts their current size as an alternative width owner.++## Canonical concepts++| Concept | Values or states | Default semantics | Stability |+| --------------------- | ------------------------------------------------------------------- | --------------------------------------------------------------------------- | ---------------------- |+| generic region | Section | Related page/content area with an optional painted treatment | current |+| shell topology | header, start, content, end, footer | Layout places provided regions in logical reading direction | current |+| contextual actions | start, optional center, end | Toolbar groups controls within a bounded content region | current |+| outer and inner inset | shell edge or adjacent-region edge | A Layout region uses the inset appropriate to the edges it touches | current |+| boundary | absent or divider | A member may draw only the edges its component contract exposes | current |+| region scroll | clipped, scrollable, or page-owned where exposed | LayoutContent and LayoutPanel own their current overflow choice | component-owned |+| landmark | no explicit role, or caller-supplied role and label | A region does not infer page-level landmark semantics from visual placement | current |+| region size | intrinsic, fixed, fill/auto, capped, or resize-driven where exposed | Each member owns its applicable size axis | component-owned |+| responsive adaptation | retained, omitted, or replaced by caller composition | No shared automatic region swap exists | caller/component-owned |++## Cross-component invariants++- **FR1 — A region owns structure, not product meaning.** A member establishes a+ spatial boundary and renders caller content without adopting the content's+ product semantics, state, or component contracts.+- **FR2 — Region direction is logical.** Start and end follow writing direction.+ Divider placement and panel adjacency use the same logical region position.+- **FR3 — Layout selects geometry from slot presence.** Header, Content, Footer,+ and Panel apply outer inset where they touch the shell and inner inset where+ they meet another region. 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+ `architecture:container-padding`.+- **FR4 — Explicit region padding replaces the automatic applied inset.**+ Section publishes its component inset; Layout distributes shell inset to+ named regions; a region's explicit padding or zero-padding path selects its+ local styles. This does not claim that every automatic Layout edge currently+ republishes an exact matching descendant variable.+- **FR5 — Boundary ownership is caller-selected where composition permits two+ owners.** LayoutHeader and LayoutFooter each own their implied edge. Section+ and Toolbar expose selected edges. LayoutPanel may draw its content-facing+ edge, and ResizeHandle may also draw it; current code does not prevent both.+ A resizable panel composition must set `LayoutPanel hasDivider={false}` when+ the adjacent ResizeHandle owns the divider.+- **FR6 — Divider absence may change spacing.** Layout regions currently collapse+ the interior spacing associated with an absent header, footer, or panel+ divider; an explicit divider preserves the fenced boundary.+- **FR7 — Scrolling is explicit and local.** LayoutContent and LayoutPanel own+ their current `isScrollable` behavior. Section and Toolbar do not become+ scroll containers through family membership. Layout `height="fill"` contains+ region scrolling; `height="auto"` lets the containing page grow.+- **FR8 — Landmark semantics remain explicit.** Named visual placement does not+ automatically assign `banner`, `main`, `navigation`, `complementary`, or+ `contentinfo`. A caller supplies a supported role and label for the context.+- **FR9 — Responsive substitution is not automatic.** Section and Toolbar keep+ their current presentation. Layout renders the regions supplied by the+ caller. AppShell, product composition, or another component-specific owner+ decides when a region is omitted or replaced at a narrower width.+- **FR10 — Resize ownership remains delegated.** A LayoutPanel with `resizable`+ uses the hook-provided current size instead of its `width` prop. The region+ family does not redefine snapping, persistence, collapse, keyboard, or pointer+ behavior.+- **FR11 — Theming remains component-owned.** Structural membership does not+ create family targets. Current `.doc.mjs` metadata documents shipped targets+ and capabilities, runtime `themeProps()` emits them, and+ `architecture:component-theming-surface` owns the cross-component rules. A+ component spec may add optional anatomy-mapping metadata when one exists.++## Allowed component variation++- **AV1 — Region strength.** Section is a generic region; Layout members are+ position-aware shell zones; Toolbar is a semantic action bar.+- **AV2 — Surface treatment.** Section and Toolbar may use Section variants and+ selected edges. Layout regions use their existing divider and padding+ treatments. Family membership does not unify their visual API.+- **AV3 — Region content.** Header, footer, panel, content, and toolbar lanes may+ hold any content allowed by their component contracts.+- **AV4 — Size model.** Layout owns fill/auto shell height and content-width+ propagation; individual regions own applicable height, width, padding, and+ scroll props; Section owns its box-size props.+- **AV5 — Interaction.** Toolbar owns roving focus and keyboard hints. Other+ members add no toolbar behavior. Resizable owns resize interaction.+- **AV6 — Composition mechanism.** Members may use Stack utilities, direct CSS+ layout, contexts, or component composition. The observable region contract is+ the owned surface.+- **AV7 — Responsive policy.** Callers may omit, replace, or externally adapt+ regions. The family sets no breakpoint.++## Representative matrix++| Member and state | Shared invariant | Deliberate variation |+| ------------------------------------------------ | --------------------------------------------------------------- | ------------------------------------------------------------------------------------ |+| Section / default, transparent, or muted | Owns one generic region and publishes its applied inset | Variant and selected divider edges are Section-local |+| Layout / content only | Slot presence selects shell-edge inset | Children are a shorthand for the content slot; explicit content wins |+| Layout / all regions | Start/end stay logical; named regions receive outer/inner inset | Header, content, footer, and panels expose different size/scroll controls |+| LayoutHeader or LayoutFooter / divider inherited | One boundary owner and explicit landmark semantics | Parent `defaultHasDividers` supplies the default; local false may override it |+| LayoutContent / scrollable or page-owned | Region owns current overflow choice | `isScrollable={false}` supports parent/page scrolling and sticky descendants |+| LayoutPanel / fixed or resize-driven | Panel position selects edge treatment | useResizable may replace width ownership; ResizeHandle retains interaction ownership |+| Toolbar / two or three lanes | Contextual action region delegates its surface to Section | Center content switches internal arrangement; toolbar alone owns keyboard behavior |++## Adoption and exceptions++| Component or concern | Adoption | Current gap or exception |+| -------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |+| Section | Generic region and container-padding publisher | Its nested escape is always inline but only first/last child on the block axis |+| Layout shell | Named region owner with slot contexts | Source applies `contentWidth` to the middle row and propagates it to header/footer wrappers, but tests do not prove contentWidth-specific style or rendered panel/content allocation |+| LayoutContent | Reads slot presence and applies outer/inner inset | Its no-start path writes the outer value to both inline geometry variables, while no-end changes padding without the matching variable update |+| LayoutPanel | Applies position-aware padding and may accept resize-driven width | Automatic shell-facing 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 |+| Responsive regions | Caller/AppShell composition | LayoutPanel has no current shared responsive visibility contract |++These rows describe shipped behavior and verification gaps. They are not approved+exceptions to silently change in a documentation pull request.++## Change coupling++- Adding or changing a structural-region component checks membership and updates+ this contract only when the shared boundary changes.+- Changing Layout slot presence, area context, inset distribution, divider+ inheritance, height mode, or content-width propagation updates the+ corresponding region tests and browser evidence.+- Changing Section padding, nested escape, variant, or divider behavior updates+ its component contract and reviews `architecture:container-padding` when+ inherited geometry changes.+- Changing Toolbar lanes, semantics, keyboard behavior, or size cascade remains+ Toolbar work; changing its Section-backed surface or inset relationship also+ reviews this family and the container-padding architecture.+- Changing LayoutPanel resize integration reviews Resizable's component contract+ without copying resize mechanics into this family.+- Adding responsive hide/swap behavior requires a component or higher-level+ owner and compatibility evidence; family membership does not authorize a new+ breakpoint prop.++## 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` | Header/footer always have distinct inner wrappers, and divider state remains on their outer region elements | The middle-row assertion checks only for a truthy class and does not prove contentWidth-specific style; computed width, panel/content allocation, and consumer-doc wording remain unverified |+| 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,+Layout, Toolbar, and ResizeHandle composition; the adoption table names those+limits explicitly.++## Decision links++### DEC-1 — Structural regions and composition primitives have separate owners++**Decider:** `cixzhang`, `2026-08-30`++Section, Layout and its named regions, and Toolbar form the layout-regions+family. Stack, Grid, Center, and their modifiers have a separate+layout-primitives owner. This keeps shared region rules focused on structural+boundaries without turning every flex/grid container into a page region.++## Open questions++None. The adoption table contains checkable source and browser work, not+unresolved family policy.++## Content boundary++This record owns only shared structural-region behavior. It does not repeat+component prop tables, define arbitrary-child composition, own product or+navigation semantics, prescribe visual design, assign responsive breakpoints,+redefine resize interaction, or own component theming anatomy and targets.