An open source design system that's fully customizable and agent ready
TypeScript
docs(layout): clarify AppShell page-shell ownership (#5777)
Cindy Zhangfa93107ff715
diff --git a/docs/architecture/container-padding.md b/docs/architecture/container-padding.mdindex 25b28656bb..817d1a01c5 100644--- a/docs/architecture/container-padding.md+++ b/docs/architecture/container-padding.md@@ -82,6 +82,11 @@ The protocol has four layers:| Alignment consumer | Toolbar and edge-compensating child components | Read the current inline inset to align visible content rather than stacked touch-target padding || Boundary owner | Layer surfaces and dialog-based overlay roots | Apply `overlayPaddingReset` before descendants read inherited page geometry |+The participant list is the shared container system, not a Layout-owned family:+Section and Layout publish or redistribute insets, Table and Divider consume+bleed geometry, and Toolbar consumes alignment geometry. Participation here does+not by itself make Table or Divider a member of `family:layout-regions`.+`--_section-padding-propagated` is separate from the public`--astryx-section-padding` property. The private value carries one ancestorSection's explicit padding. An overlay can therefore drop ancestor geometrydiff --git a/docs/families/layout-primitives.md b/docs/families/layout-primitives.mdindex b42f07d308..6320cfade5 100644--- a/docs/families/layout-primitives.md+++ b/docs/families/layout-primitives.md@@ -58,11 +58,14 @@ its parent when it changes one child's participation in that arrangement.StackItem style utilities; `padding.stylex.ts`; the container-paddingarchitecture; component `.doc.mjs` theming metadata and runtime`themeProps()` emission.-- **Excluded:** Section, Layout and its regions, and Toolbar own structural- regions rather than general composition. FormLayout owns field arrangement- and form-level optionality. AspectRatio constrains one child's box rather than- arranging arbitrary children. Card and Dialog are surfaces. AppShell and- navigation components compose higher-level structure.+- **Excluded:** Section, Layout, its named regions, and Toolbar own structural+ region contracts rather than this family's arbitrary-child flow, grid, and+ centering vocabulary. Layout is a general-purpose primitive, but its public+ model is five named slots rather than unrestricted child arrangement.+ FormLayout owns field arrangement and form-level optionality. AspectRatio+ constrains one child's box rather than arranging arbitrary children. Card and+ Dialog are surfaces. AppShell owns the page shell and application navigation+ composition.Membership follows public responsibility, not implementation mechanism. Acomponent does not join merely because its source uses flexbox or grid.diff --git a/docs/families/layout-regions.md b/docs/families/layout-regions.mdindex 0e73142941..64410d983e 100644--- a/docs/families/layout-regions.md+++ b/docs/families/layout-regions.md@@ -7,7 +7,7 @@ authority: currentarchive_reason: nullsuperseded_by: nullapproved_by: cixzhang-approved_at: 2026-08-30+approved_at: 2026-08-31owners: [cixzhang, imdreamrunner]review_triggers: [public-api, behavior, layout, accessibility, theming]verified_by:@@ -40,28 +40,34 @@ deciding_specs: []## IntentA 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.+its product content is added. Builders can use a generic Section, a five-slot+Layout primitive, or a contextual Toolbar without each surface inventing its+own inset, boundary, region direction, or content ownership. AppShell owns the+page shell that composes these lower-level regions with application navigation.## Membership ruleA 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.+structural region: a generic page/content region, a named position in Layout's+five-slot topology, 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.+- **Collaborators:** `family:layout-primitives` supplies arbitrary-child+ arrangement utilities; `architecture:container-padding` supplies the broader+ inset and bleed system used by Section, Layout and its regions, Table, Toolbar,+ and Divider; useResizable and ResizeHandle may drive a panel's size; AppShell+ owns the page shell and composes Layout with application navigation; component+ theming owns visual targets.- **Excluded:** Stack, Grid, Center, and their modifiers arrange arbitrarychildren 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.+ arrangement and optionality. Card is a discrete-item surface. AppShell owns+ page-shell and navigation semantics rather than this reusable region grammar.+ Table owns structured data, and Divider owns separation; their participation+ in `architecture:container-padding` does not make either a layout-region+ member.A component does not join because it happens to render a flex row, a paddedwrapper, or a header-like visual treatment.@@ -70,9 +76,9 @@ wrapper, or a header-like visual treatment.- 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.+- Layout owns its five-slot topology, slot presence, region position, shared+ outer/inner inset, height mode, content-width propagation, and default+ header/footer divider context. It does not own the page shell.- LayoutHeader, LayoutContent, LayoutFooter, and LayoutPanel own their regionelement, optional landmark role/name, local padding, and region-specific sizeor scrolling behavior.@@ -88,9 +94,9 @@ wrapper, or a header-like visual treatment.| 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 |+| five-slot 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 |+| outer and inner inset | Layout 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 |@@ -105,16 +111,16 @@ wrapper, or a header-like visual treatment.- **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+ and Panel apply outer inset where they touch the Layout boundary 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.+ Section publishes its component inset; Layout distributes outer and inner+ inset across its named slots; 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 twoowners.** LayoutHeader and LayoutFooter each own their implied edge. Sectionand Toolbar expose selected edges. LayoutPanel may draw its content-facing@@ -148,13 +154,14 @@ wrapper, or a header-like visual treatment.## Allowed component variation- **AV1 — Region strength.** Section is a generic region; Layout members are- position-aware shell zones; Toolbar is a semantic action bar.+ position-aware slots in the five-slot primitive; Toolbar is a semantic action+ bar.- **AV2 — Surface treatment.** Section and Toolbar may use Section variants andselected edges. Layout regions use their existing divider and paddingtreatments. Family membership does not unify their visual API.- **AV3 — Region content.** Header, footer, panel, content, and toolbar lanes mayhold any content allowed by their component contracts.-- **AV4 — Size model.** Layout owns fill/auto shell height and content-width+- **AV4 — Size model.** Layout owns fill/auto container height and content-widthpropagation; individual regions own applicable height, width, padding, andscroll props; Section owns its box-size props.- **AV5 — Interaction.** Toolbar owns roving focus and keyboard hints. Other@@ -170,7 +177,7 @@ wrapper, or a header-like visual treatment.| 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 / content only | Slot presence selects Layout-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 |@@ -182,9 +189,9 @@ wrapper, or a header-like visual treatment.| 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 |+| Layout container | Five-slot 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}` |+| 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 || Responsive regions | Caller/AppShell composition | LayoutPanel has no current shared responsive visibility contract |@@ -242,6 +249,15 @@ family. Stack, Grid, Center, and their modifiers have a separatelayout-primitives owner. This keeps shared region rules focused on structuralboundaries without turning every flex/grid container into a page region.+### DEC-2 — AppShell owns the page shell++**Decider:** `cixzhang`, `2026-08-31`++AppShell owns the page shell and application-navigation composition. Layout is+the general five-slot primitive used to arrange `header`, `start`, `content`,+`end`, and `footer` regions within a page or bounded container. The broader+container-padding participants retain their own component ownership.+## Open questionsNone. The adoption table contains checkable source and browser work, notdiff --git a/packages/core/src/AppShell/AppShell.doc.mjs b/packages/core/src/AppShell/AppShell.doc.mjsindex 64051c4c09..81c496e54b 100644--- a/packages/core/src/AppShell/AppShell.doc.mjs+++ b/packages/core/src/AppShell/AppShell.doc.mjs@@ -10,7 +10,7 @@ export const docs = {keywords: ["appshell","layout","scaffold","sidebar","sidenav","topnav","header","navigation","dashboard","shell","page","frame"],usage: {description:- 'The outermost layout for an application. Provides slots for top navigation, side navigation, banners, and main content. Use it as the root wrapper for every page. It handles responsive mobile navigation and skip-to-content automatically. Configure side nav collapse on SideNav with its collapsible prop.',+ 'AppShell is the page shell for an application. It provides slots for top navigation, side navigation, banners, and main content. Use it as the root wrapper for every page. It handles responsive mobile navigation and skip-to-content automatically. Configure side nav collapse on SideNav with its collapsible prop.',bestPractices: [{guidance: true, description: 'Choose the right height: use "fill" for dashboards with internal scrolling and "auto" for pages that grow with content.'},{guidance: true, description: 'Set `contentPadding` based on content type: 4 for forms and settings, 0 for tables and dashboards.'},@@ -21,6 +21,7 @@ export const docs = {{guidance: false, description: 'Add your own skip link or <main> element. AppShell already renders both, and a second main landmark makes the first ambiguous.'},],anatomy: [+ {name: 'Page shell', required: true, description: 'Outermost application frame that owns page-level navigation, responsive shell behavior, and the main content landmark.'},{name: 'Skip link', required: true, description: 'First focusable element on the page. Visually hidden until focused, then moves focus to the main content area.'},{name: 'Banner', required: false, description: 'The banner slot, for system-wide announcements. Renders above the top nav, inside the banner landmark.'},{name: 'Top navigation', required: false, description: 'The topNav slot, typically TopNav. Below the mobile breakpoint it becomes a compact bar carrying the nav toggle.'},@@ -137,7 +138,7 @@ export const docsZh = {displayName: 'App Shell',usage: {description:- 'The outermost layout for an application. Provides slots for top navigation, side navigation, banners, and main content. Use it as the root wrapper for every page. It handles responsive mobile navigation and skip-to-content automatically. Configure side nav collapse on SideNav with its collapsible prop.',+ 'AppShell is the page shell for an application. It provides slots for top navigation, side navigation, banners, and main content. Use it as the root wrapper for every page. It handles responsive mobile navigation and skip-to-content automatically. Configure side nav collapse on SideNav with its collapsible prop.',bestPractices: [{guidance: true, description: 'Choose the right height: use "fill" for dashboards with internal scrolling and "auto" for pages that grow with content.'},{guidance: true, description: 'Set `contentPadding` based on content type: 4 for forms and settings, 0 for tables and dashboards.'},@@ -199,7 +200,7 @@ export const docsDense = {'app-level layout shell w/ header, side nav, main content; composes Layout internally, replaces Page+PageLayout',usage: {description:- 'The outermost layout for an application. Provides slots for top navigation, side navigation, banners, and main content. Use it as the root wrapper for every page. It handles responsive mobile navigation and skip-to-content automatically. Configure side nav collapse on SideNav with its collapsible prop.',+ 'AppShell is the page shell for an application. It provides slots for top navigation, side navigation, banners, and main content. Use it as the root wrapper for every page. It handles responsive mobile navigation and skip-to-content automatically. Configure side nav collapse on SideNav with its collapsible prop.',bestPractices: [{guidance: true, description: 'Choose the right height: use "fill" for dashboards with internal scrolling and "auto" for pages that grow with content.'},{guidance: true, description: 'Set `contentPadding` based on content type: 4 for forms and settings, 0 for tables and dashboards.'},diff --git a/packages/core/src/AppShell/AppShell.tsx b/packages/core/src/AppShell/AppShell.tsxindex 69cf839289..320feadfd0 100644--- a/packages/core/src/AppShell/AppShell.tsx+++ b/packages/core/src/AppShell/AppShell.tsx@@ -8,7 +8,7 @@ import React from 'react';* @file AppShell.tsx* @input Uses React, Layout, LayoutHeader, LayoutPanel, LayoutContent, StyleX* @output Exports AppShell component and AppShellProps type- * @position Application-level layout shell — the top-level wrapper for any app.+ * @position Page shell for an application — the top-level wrapper for any app.* Composes Layout internally to provide header, sideNav, and main content areas.* Use for any app that needs a top nav, side navigation, and scrollable content.*@@ -430,7 +430,7 @@ const styles = stylex.create({// =============================================================================/**- * Application-level layout shell. Provides the structural frame for an app:+ * Page shell for an application. Provides the structural frame for an app:* top navigation, side navigation, and main content area.** Slot-based API with `topNav`, `sideNav`, `banner`, and `children`.diff --git a/packages/core/src/Divider/Divider.spec.md b/packages/core/src/Divider/Divider.spec.mdindex 1f310f0453..ccd6891c66 100644--- a/packages/core/src/Divider/Divider.spec.md+++ b/packages/core/src/Divider/Divider.spec.md@@ -14,7 +14,8 @@ verified_by:[packages/core/src/Divider/Divider.test.tsx, scripts/check-knowledge.mjs]families: []design_specs: []-architecture: [architecture:component-theming-surface]+architecture:+ [architecture:component-theming-surface, architecture:container-padding]contributing: []system_specs: []---@@ -46,10 +47,12 @@ Consumer migration instructions belong in consumer docs and release notes.**Does not own / non-goals**-- The meaning of the content regions separated by the divider — owned by the- product callsite.-- Whether Rule or Label should gain public targets — unresolved by this factual- backfill.+- The meaning of the content regions separated by the divider, which is owned by+ the product callsite.+- Container inset publication or structural page regions. Divider only reads+ inherited container geometry when `isFullBleed` is enabled.+- Whether Rule or Label should gain public targets, which is unresolved by this+ factual backfill.## Public concepts@@ -121,9 +124,12 @@ public targets.## Family and system relationships-- `architecture:component-theming-surface` owns anatomy qualification, target- mapping, and the difference between factual reachability and intended public- theming API.+`family:layout-regions` does not own Divider: separating content is not a+structural page-region contract. `architecture:container-padding` owns the+inherited inset geometry that Divider reads only when `isFullBleed` is enabled.+`architecture:component-theming-surface` owns anatomy qualification, target+mapping, and the difference between factual reachability and intended public+theming API.## Verification mapdiff --git a/packages/core/src/Layout/Layout.doc.mjs b/packages/core/src/Layout/Layout.doc.mjsindex 48f01de909..e4488dd911 100644--- a/packages/core/src/Layout/Layout.doc.mjs+++ b/packages/core/src/Layout/Layout.doc.mjs@@ -3,30 +3,34 @@/** @type {import('@astryxdesign/cli/authoring').ComponentAnatomyElement[]} */const anatomy = [{- name: 'Page shell',+ name: 'Layout container',required: true,- description: 'Outer Layout container that arranges the named page regions.',+ description:+ 'General layout primitive that places the header, start, content, end, and footer slots.',},{name: 'Header',required: false,- description: 'Optional top region for page or application header content.',+ description:+ 'Optional LayoutHeader region supplied by the caller, typically in the header slot.',},{name: 'Panel',required: false,description:- 'Optional start or end side region; both positions use the same LayoutPanel part.',+ 'Optional LayoutPanel region supplied by the caller in the start or end slot.',},{name: 'Content area',required: false,- description: 'Optional central region for the page content.',+ description:+ 'Optional LayoutContent region supplied by the caller in the content slot.',},{name: 'Footer',required: false,- description: 'Optional bottom region for page footer content.',+ description:+ 'Optional LayoutFooter region supplied by the caller, typically in the footer slot.',},];@@ -37,7 +41,7 @@ export const docs = {displayName: 'Layout',group: 'Layout',category: 'Layout',- keywords: ["layout","container","content","flex","box","wrapper","scaffold","page","shell"],+ keywords: ["layout","container","content","flex","box","wrapper","page","regions"],playground: {defaults: {header: {__element: 'LayoutHeader', props: {}, children: {__element: 'Heading', props: {level: 3}, children: 'Page Title'}},@@ -54,13 +58,13 @@ export const docs = {{className: 'astryx-layout-panel'},],},- description: 'Page shell with header, sidebar(s), content, and footer slots for building full app layouts.',+ description: 'General five-slot layout primitive for arranging header, start, content, end, and footer regions.',props: [{name: 'content',type: 'ReactNode',description:- 'Main content area (center). Children passed to `<Layout>` render here too: `<Layout>{main}</Layout>` is shorthand for `<Layout content={main} />`.',+ 'Content slot (center). Accepts any ReactNode; use LayoutContent when a content region is needed. Children passed to `<Layout>` render here too: `<Layout>{main}</Layout>` is shorthand for `<Layout content={main} />`.',slotElements: [{__element: 'LayoutContent',@@ -72,7 +76,8 @@ export const docs = {{name: 'header',type: 'ReactNode',- description: 'Header slot.',+ description:+ 'Header slot. Accepts any ReactNode; use LayoutHeader when a header region is needed.',slotElements: [{__element: 'LayoutHeader',@@ -84,7 +89,8 @@ export const docs = {{name: 'footer',type: 'ReactNode',- description: 'Footer slot.',+ description:+ 'Footer slot. Accepts any ReactNode; use LayoutFooter when a footer region is needed.',slotElements: [{__element: 'LayoutFooter',@@ -96,7 +102,8 @@ export const docs = {{name: 'start',type: 'ReactNode',- description: 'Start panel (left in LTR).',+ description:+ 'Logical-start slot (left in LTR). Accepts any ReactNode; use LayoutPanel when a panel region is needed.',slotElements: [{__element: 'LayoutPanel',@@ -108,7 +115,8 @@ export const docs = {{name: 'end',type: 'ReactNode',- description: 'End panel (right in LTR).',+ description:+ 'Logical-end slot (right in LTR). Accepts any ReactNode; use LayoutPanel when a panel region is needed.',slotElements: [{__element: 'LayoutPanel',@@ -152,12 +160,12 @@ export const docs = {],usage: {description:- 'Layout provides composable components for building structured page shells with header, sidebar, content, and footer slots. Use Layout for full app layouts and HStack/VStack for simple directional stacking.',+ 'Layout is a general five-slot primitive for arranging header, start, content, end, and footer regions within a page or bounded container. AppShell owns the page shell and app-wide navigation behavior; use HStack or VStack for simple directional stacking.',bestPractices: [- { guidance: true, description: 'Use Layout for page shells that need distinct zones like header, sidebar(s), content, and footer.' },+ { guidance: true, description: 'Use Layout when content needs named header, start, content, end, or footer regions.' },{ guidance: true, description: 'Use HStack and VStack for simple directional stacking within a content area.' },{ guidance: false, description: 'Use Layout for simple stacking layouts; use HStack or VStack instead.' },- { guidance: false, description: 'Nest multiple Layout components; use one per page shell and compose content within its slots.' },+ { guidance: false, description: 'Use Layout as the page shell or for app-wide navigation; use AppShell for that responsibility.' },],anatomy,},@@ -167,12 +175,12 @@ export const docs = {export const docsZh = {usage: {description:- 'Layout provides composable components for building structured page shells with header, sidebar, content, and footer slots. Use Layout for full app layouts and HStack/VStack for simple directional stacking.',+ 'Layout is a general five-slot primitive for arranging header, start, content, end, and footer regions within a page or bounded container. AppShell owns the page shell and app-wide navigation behavior; use HStack or VStack for simple directional stacking.',bestPractices: [- { guidance: true, description: 'Use Layout for page shells that need distinct zones like header, sidebar(s), content, and footer.' },+ { guidance: true, description: 'Use Layout when content needs named header, start, content, end, or footer regions.' },{ guidance: true, description: 'Use HStack and VStack for simple directional stacking within a content area.' },{ guidance: false, description: 'Use Layout for simple stacking layouts; use HStack or VStack instead.' },- { guidance: false, description: 'Nest multiple Layout components; use one per page shell and compose content within its slots.' },+ { guidance: false, description: 'Use Layout as the page shell or for app-wide navigation; use AppShell for that responsibility.' },],},};@@ -180,15 +188,15 @@ export const docsZh = {/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */export const docsDense = {description:- 'Composable utilities + components for structured layouts w/ container/content separation pattern.',+ 'General five-slot primitive for arranging header, start, content, end, and footer regions. AppShell owns the page shell.',usage: {description:- 'Layout provides composable components for building structured page shells with header, sidebar, content, and footer slots. Use Layout for full app layouts and HStack/VStack for simple directional stacking.',+ 'Layout is a general five-slot primitive for arranging header, start, content, end, and footer regions within a page or bounded container. AppShell owns the page shell and app-wide navigation behavior; use HStack or VStack for simple directional stacking.',bestPractices: [- { guidance: true, description: 'Use Layout for page shells that need distinct zones like header, sidebar(s), content, and footer.' },+ { guidance: true, description: 'Use Layout when content needs named header, start, content, end, or footer regions.' },{ guidance: true, description: 'Use HStack and VStack for simple directional stacking within a content area.' },{ guidance: false, description: 'Use Layout for simple stacking layouts; use HStack or VStack instead.' },- { guidance: false, description: 'Nest multiple Layout components; use one per page shell and compose content within its slots.' },+ { guidance: false, description: 'Use Layout as the page shell or for app-wide navigation; use AppShell for that responsibility.' },],anatomy,},diff --git a/packages/core/src/Layout/Layout.spec.md b/packages/core/src/Layout/Layout.spec.mdindex c75d32fd8b..9a50dc7b43 100644--- a/packages/core/src/Layout/Layout.spec.md+++ b/packages/core/src/Layout/Layout.spec.md@@ -35,10 +35,12 @@ system_specs: []## Intent-Layout provides the page shell that arranges optional Header, Panel, Content-area, and Footer regions. This draft records the current aggregate consumer-anatomy and theming ownership without changing runtime behavior, DOM, styling,-targets, or public API.+Layout is a general layout primitive that arranges five optional named slots:+Header, logical-start Panel, Content area, logical-end Panel, and Footer. It can+structure regions within a page or bounded container, while AppShell owns the+page shell. This draft records the current aggregate consumer anatomy and+theming ownership without changing runtime behavior, DOM, styling, targets, or+public API.## Compatibility and migration@@ -54,17 +56,23 @@ Consumer migration instructions belong in consumer docs and release notes.**Owns**-- The Page shell and its current `layout` target.-- The aggregate Header, Panel, Content area, and Footer anatomy and their current+- The Layout container and its current `layout` target.+- The five named slot positions: `header`, `start`, `content`, `end`, and+ `footer`; each accepts caller-provided ReactNode content.+- The aggregate optional Header, Panel, Content area, and Footer anatomy when the+ caller composes the corresponding Layout region components, and their current`layout-header`, `layout-panel`, `layout-content`, and `layout-footer` targets.-- One Panel concept for both logical start and end positions.+- One LayoutPanel concept and `layout-panel` target shared by instances supplied+ to the logical-start and logical-end slots.**Does not own / non-goals**-- Product meaning or content supplied to any region — owned by the caller.-- Automatic responsive substitution of regions — owned by the caller, AppShell,- or another higher-level composition.-- Resize interaction — owned by useResizable and ResizeHandle.+- The page shell, app-wide navigation, responsive shell substitution, skip link,+ or main landmark, which are owned by AppShell.+- Product meaning or content supplied to any slot, which is owned by the caller.+- Automatic responsive substitution of regions outside AppShell, which is owned+ by the caller or another higher-level composition.+- Resize interaction, which is owned by useResizable and ResizeHandle.- Correcting current container-padding publication mismatches or preventing twoadjacent divider owners from both painting; those remain current gaps andcaller obligations recorded below.@@ -72,27 +80,37 @@ Consumer migration instructions belong in consumer docs and release notes.## Public concepts-No new public concept is introduced. Consumer props, slots, defaults, and usage-remain documented in `Layout.doc.mjs` and the region subcomponent docs.-`family:layout-regions` owns the shared region vocabulary.+The current public topology has five independent ReactNode slots. Slot position+is not rendered anatomy and does not add a target to arbitrary content.++| Concept | Current values | Meaning |+| ------------- | --------------------------------------------- | -------------------------------------------------------------------------------------------- |+| slot topology | `header`, `start`, `content`, `end`, `footer` | Positions caller content in the five-slot arrangement; omitted slots render no area wrapper. |+| slot content | any ReactNode | The caller may supply Layout region components or unrelated content. |+| panel anatomy | LayoutPanel in `start` and/or `end` | Both positions use one optional Panel anatomy concept and one `layout-panel` target. |++Consumer syntax, defaults, and recommended region components remain documented+in `Layout.doc.mjs` and the region subcomponent docs. `family:layout-regions`+owns the shared region vocabulary, while `architecture:container-padding` owns+the broader container system shared with Section, Table, Toolbar, and Divider.## Behavioral and layout contract-| ID | Candidate invariant | Basis | Draft review state |-| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- | -------------------------------------------------- |-| FR1 | Layout renders one Page shell carrying the current `layout` target and places each supplied named region according to the existing shell topology. | Current source, docs, tests, and family | Verified current behavior; no new behavior decided |-| FR2 | Header, Content area, and Footer use their current `layout-header`, `layout-content`, and `layout-footer` targets on the corresponding Layout region components. | Current source and target metadata | Verified current inventory; no target change |-| FR3 | A Panel in either logical start or end position is the same aggregate Panel part and uses the current `layout-panel` target; position does not create a second anatomy row or target. | Current source, docs, tests, and family | Verified current ownership; no API change |-| FR4 | `Layout.doc.mjs` is the canonical aggregate consumer document for all five current `layout*` targets; region subcomponent docs continue to document their own props and usage without duplicating the aggregate target inventory. | Current documentation organization | Verified current ownership |-| FR5 | LayoutContent and LayoutPanel retain their shipped automatic container-padding publication behavior, including the mismatches recorded by `architecture:container-padding`; this documentation does not claim exact parity. | Current source and architecture record | Current conformance gap; not fixed here |-| FR6 | When an adjacent ResizeHandle owns a panel divider, the caller must keep `LayoutPanel hasDivider={false}`; current composition does not prevent both components from painting the same boundary. | Current source, docs, and family contract | Current caller obligation; not fixed here |+| ID | Candidate invariant | Basis | Draft review state |+| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- | -------------------------------------------------- |+| FR1 | Layout renders one general Layout container carrying the current `layout` target and places arbitrary caller-provided ReactNode content in the `header`, `start`, `content`, `end`, and `footer` slots. Slot placement alone adds no region component or target. | Current source, docs, and tests | Verified current behavior; no new behavior decided |+| FR2 | When the caller supplies LayoutHeader, LayoutContent, or LayoutFooter, that component carries its current `layout-header`, `layout-content`, or `layout-footer` target; Layout does not add those targets to arbitrary slot content. | Current source and target metadata | Verified current inventory; no target change |+| FR3 | LayoutPanel instances supplied to logical start or end share one aggregate Panel anatomy part and the current `layout-panel` target; slot position does not create a second anatomy part or target. | Current source, docs, tests, and family | Verified current ownership; no API change |+| FR4 | `Layout.doc.mjs` is the canonical aggregate consumer document for the five current `layout*` targets and maps each target once; region subcomponent docs continue to document their own props and usage. | Current documentation organization | Verified current ownership |+| FR5 | LayoutContent and LayoutPanel retain their shipped automatic container-padding publication behavior, including the mismatches recorded by `architecture:container-padding`; this documentation does not claim exact parity. | Current source and architecture record | Current conformance gap; not fixed here |+| FR6 | When an adjacent ResizeHandle owns a panel divider, the caller must keep `LayoutPanel hasDivider={false}`; current composition does not prevent both components from painting the same boundary. | Current source, docs, and family contract | Current caller obligation; not fixed here |### Current evidence and gaps- LayoutContent does not republish a matching inline-end container-padding valueon its automatic no-end path, and its no-start path writes the outer inlinevalue to both inline geometry variables. LayoutPanel applies automatic outer- shell-edge padding while retaining baseline inner geometry variables. A+ Layout-edge padding while retaining baseline inner geometry variables. Afull-bleed descendant can therefore compensate against a published value thatdiffers from the region's applied padding. This is shipped evidence and aruntime conformance gap, not behavior corrected or approved by this draft.@@ -103,22 +121,25 @@ remain documented in `Layout.doc.mjs` and the region subcomponent docs.### Allowed variation-- **AV1 — Slot presence.** Header, start Panel, Content area, end Panel, and Footer- may be independently present or absent within the existing shell topology.-- **AV2 — Panel position.** A Panel may occupy logical start or end, or Panels may- occupy both positions; all use the same conceptual part and target owner.-- **AV3 — Region content.** Caller-provided region content retains its own- semantics and theming ownership.+- **AV1 — Slot presence and content.** Header, start, content, end, and footer may+ be independently present or absent and may contain any caller-provided+ ReactNode. Slot content does not become Layout anatomy by position alone.+- **AV2 — Region composition.** Callers may supply LayoutHeader, LayoutContent,+ LayoutFooter, or LayoutPanel in the matching slot when they need those region+ components and targets; Layout does not insert them automatically.+- **AV3 — Panel position.** LayoutPanel may occupy logical start or end, or both+ positions may be supplied; all instances remain one Panel anatomy concept and+ target.### Representative states-| State | Required invariant | Allowed variation |-| --------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------ |-| Content-only shell | Page shell and Content area use their current targets. | Caller content and current height/width configuration. |-| Header/content/footer | Each supplied region uses its corresponding aggregate part and target. | Divider selection, size, padding, and caller content. |-| Start or end Panel | Either logical position uses the one Panel part and `layout-panel` target. | Position, width, scrolling, padding, and caller role. |-| Two Panels | Both instances remain one repeated conceptual Panel part. | Independent content, width, and local configuration. |-| ResizeHandle-adjacent | Divider ownership follows the current caller obligation in FR6. | Resize state remains owned by the resize components. |+| State | Required invariant | Allowed variation |+| ------------------------------ | ------------------------------------------------------------------------------------------ | ------------------------------------------------------ |+| Arbitrary content only | Layout container carries `layout`; arbitrary content gains no region target from its slot. | Caller content and current height/width configuration. |+| Composed header/content/footer | Supplied Layout region components retain their own anatomy and targets. | Any region may instead be absent or arbitrary content. |+| Start or end LayoutPanel | Either logical position uses the one Panel anatomy part and `layout-panel` target. | Position, width, scrolling, padding, and caller role. |+| Two LayoutPanels | Both instances remain repetitions of the same Panel anatomy part and target. | Independent content, width, and local configuration. |+| ResizeHandle-adjacent | Divider ownership follows the current caller obligation in FR6. | Resize state remains owned by the resize components. |### Transformation and precedence order@@ -137,13 +158,16 @@ caller-supplied role and label behavior.## Design relationships-| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |-| ---------------- | -------------------------------------------------------------- | ----------------------------------------- | -------------- | ------------------ |-| Page shell | Arranges the named page regions. | Current source, docs, and family contract | Supporting | FR1 |-| Header | Presents optional top-region content. | Current source, docs, and family contract | Supporting | FR1, FR2 |-| Panel | Presents optional side-region content at logical start or end. | Current source, docs, and family contract | Supporting | FR1, FR3, FR6 |-| Content area | Presents optional central page content. | Current source, docs, and family contract | Prominent | FR1, FR2, FR5 |-| Footer | Presents optional bottom-region content. | Current source, docs, and family contract | Supporting | FR1, FR2 |+| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |+| ---------------- | ---------------------------------------------------------------------------------------- | ----------------------------------------- | -------------- | ------------------ |+| Layout container | Places arbitrary caller content in the five named slots without becoming the page shell. | Current source, docs, and family contract | Supporting | FR1 |+| Header | Presents an optional caller-supplied LayoutHeader region. | Current source, docs, and family contract | Supporting | FR2 |+| Panel | Presents a caller-supplied LayoutPanel at logical start or end. | Current source, docs, and family contract | Supporting | FR3, FR6 |+| Content area | Presents an optional caller-supplied LayoutContent region. | Current source, docs, and family contract | Prominent | FR2, FR5 |+| Footer | Presents an optional caller-supplied LayoutFooter region. | Current source, docs, and family contract | Supporting | FR2 |++Slot position is topology, not anatomy. Arbitrary ReactNode content supplied to+a slot does not acquire the corresponding region part or target.### Theming anatomy@@ -151,7 +175,7 @@ caller-supplied role and label behavior.```json{- "Page shell": {"target": "layout"},+ "Layout container": {"target": "layout"},"Header": {"target": "layout-header"},"Panel": {"target": "layout-panel"},"Content area": {"target": "layout-content"},@@ -159,15 +183,19 @@ caller-supplied role and label behavior.}```-The exact map records the five current public targets. Start and end Panels are-instances of the same stable conceptual part and therefore share one map row.+The exact map records each current public target once. Panel represents every+caller-supplied LayoutPanel instance, whether placed at logical start, logical+end, or both. It does not map the `start` and `end` slots themselves.## Family and system relationships-- `family:layout-regions` owns the shared shell-region topology, logical- direction, boundaries, scrolling, and component ownership.-- `architecture:container-padding` owns Layout inset publication and the current- LayoutContent/LayoutPanel conformance gap.+- `family:layout-regions` owns the shared named-region topology, logical+ direction, boundaries, scrolling, and component ownership. Layout adopts that+ vocabulary without owning the page shell.+- `architecture:container-padding` owns the broader container system shared by+ Section, Layout and its regions, Table, Toolbar, and Divider, including the+ current LayoutContent/LayoutPanel conformance gap. Participation in that+ system does not make Table or Divider Layout regions.- `architecture:component-theming-surface` owns anatomy qualification and exacttarget mapping rules.- `architecture:public-component-api` owns the stable slots, props, exports, and@@ -175,18 +203,25 @@ instances of the same stable conceptual part and therefore share one map row.## Verification map-| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |-| ------------- | ----------------------------------------------------------------------------- | --------------------------------------------------- | --------------------------------------------------------------------------------------------------- | ---------------------------- |-| FR1–FR3 | Layout render, slot, children-as-content, and target inventory tests | Content-only, all regions, logical start/end Panels | Removing a region or target fails existing structure, context, or target inventory assertions. | `audit:Layout/anatomy` |-| FR4 | `scripts/check-knowledge.mjs` | Canonical aggregate doc and exact five-target map | Duplicated, missing, extra, prefixed, or stale target mappings fail repository validation. | `audit:Layout/theming` |-| FR5 | Source inspection plus `architecture:container-padding` verification evidence | Automatic outer-edge Content area and Panel paths | This draft adds no parity assertion; a runtime correction requires separate compatibility evidence. | `audit:Layout/layout` |-| FR6 | LayoutPanel source/docs plus `family:layout-regions` verification evidence | Panel beside a divider-owning ResizeHandle | This draft adds no prevention assertion; changing ownership requires separate runtime coverage. | `audit:Layout/layout` |-| Accessibility | `LayoutSlots.test.tsx` landmark assertions | Header, Content area, Footer, and Panel roles | Supplied role or label no longer reaches the region element. | `audit:Layout/accessibility` |+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |+| ------------- | ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- |+| FR1–FR3 | Layout render, slot-context, children-as-content, region-component, and target inventory tests | Arbitrary slot content, optional region components, logical start/end LayoutPanels | Removing slot placement, a composed region, or a current target fails existing structure, context, or target assertions; arbitrary slot content is not asserted to gain a target. | `audit:Layout/anatomy` |+| FR4 | `scripts/check-knowledge.mjs` | Canonical aggregate doc and exact five-target map | Missing, extra, prefixed, or stale target mappings fail repository validation. | `audit:Layout/theming` |+| FR5 | Source inspection plus `architecture:container-padding` verification evidence | Automatic outer-edge Content area and Panel paths | This draft adds no parity assertion; a runtime correction requires separate compatibility evidence. | `audit:Layout/layout` |+| FR6 | LayoutPanel source/docs plus `family:layout-regions` verification evidence | Panel beside a divider-owning ResizeHandle | This draft adds no prevention assertion; changing ownership requires separate runtime coverage. | `audit:Layout/layout` |+| Accessibility | `LayoutSlots.test.tsx` landmark assertions | Header, Content area, Footer, and Panel roles | Supplied role or label no longer reaches the region element. | `audit:Layout/accessibility` |## Decision log-None. This draft records current facts and introduces no component-local design,-layout, API, target, or behavior decision.+### DEC-1 — AppShell owns the page shell; Layout owns five-slot arrangement++**Reference:** `component:Layout/DEC-1`+**Decider:** `cixzhang`, `2026-08-31`++AppShell is the page shell. Layout is the general layout primitive for arranging+the `header`, `start`, `content`, `end`, and `footer` slots within a page or+bounded container. Container-padding participation by Section, Table, Toolbar,+and Divider does not make those components Layout-owned anatomy.## Open questionsdiff --git a/packages/core/src/Layout/Layout.test.tsx b/packages/core/src/Layout/Layout.test.tsxindex db1ef12395..32bd34b6f1 100644--- a/packages/core/src/Layout/Layout.test.tsx+++ b/packages/core/src/Layout/Layout.test.tsx@@ -3,7 +3,7 @@/*** @file Layout.test.tsx* @input Uses vitest, @testing-library/react, Layout + layout contexts- * @output Characterization tests for the Layout page-shell component+ * @output Characterization tests for the five-slot Layout primitive* @position Testing; validates slot rendering, context provisioning, and* divider/padding/height wiring*diff --git a/packages/core/src/Layout/Layout.tsx b/packages/core/src/Layout/Layout.tsxindex dfa1bf2bea..8ea3a9c0f3 100644--- a/packages/core/src/Layout/Layout.tsx+++ b/packages/core/src/Layout/Layout.tsx@@ -6,10 +6,10 @@* @file Layout.tsx* @input Uses React, stack/stackItem utilities, LayoutAreaContext, LayoutSlotsContext* @output Exports Layout component and LayoutProps, LayoutHeight types- * @position Page shell and app layout — use for any page with a header, sidebar, or content area.- * Building a page with a sidebar? Use Layout with start/end slots.+ * @position General five-slot layout primitive for arranging header, start, content, end, and footer regions.+ * Building a page area with a side panel? Use Layout with start/end slots.* Need a header + scrollable content? Use Layout with header + content slots.- * Manages padding collapse, scroll containment, and responsive slot sizing automatically.+ * AppShell owns the page shell and app-wide navigation behavior.** SYNC: When modified, update these files to stay in sync:* - /packages/core/src/Layout/Layout.doc.mjs@@ -178,11 +178,10 @@ function AreaProvider({}/**- * Page shell with header, sidebar(s), content, and footer slots.- * Use this for full-page layouts, app shells, dashboard layouts, or any UI- * that needs a header bar, side navigation, scrollable content area, or action footer.- * Can be used standalone for page-level layouts, or inside a container- * (Card, Section) for content-level layouts.+ * General layout primitive with header, start, content, end, and footer slots.+ * Use it to arrange regions within a page or bounded container. AppShell owns+ * the page shell, app-wide navigation, responsive shell behavior, skip link,+ * and main landmark.** Handles padding collapse between adjacent slots, scroll containment in the* content area, and automatic RTL support via CSS logical properties.diff --git a/packages/core/src/Table/Table.spec.md b/packages/core/src/Table/Table.spec.mdindex 5dc74e9525..95aeabe5c0 100644--- a/packages/core/src/Table/Table.spec.md+++ b/packages/core/src/Table/Table.spec.md@@ -239,7 +239,9 @@ aggregate ownership.target mapping, delegation, inheritance, factual `none` classifications, andthe rule that deprecated aliases do not count as anatomy.- `architecture:container-padding` owns the inherited inset protocol consumed by- the Scroll region and Cell edge compensation.+ the Scroll region and Cell edge compensation. This container-system+ participation does not make Table a structural member of+ `family:layout-regions`.- `architecture:interaction-modality` owns shared keyboard and pointer modality;Table and its plugins retain their current local interactions.- `architecture:public-component-api` owns the stable props, components, hooks,