Astryx Layout Regions 家族契约：Section、Layout 五槽位与 Toolbar 的页面结构化区域体系

Astryx Layout Regions 家族契约Section、Layout 五槽位与 Toolbar 的页面结构化区域体系【免费下载链接】astryxAn open source design system thats fully customizable and agent ready项目地址: https://gitcode.com/GitHub_Trending/as/astryx导读Astryx 将页面或受限工作区在填充产品内容之前应当具备可预测的结构化区域沉淀为一条独立的组件家族契约。本文围绕 docs/families/layout-regions.md 展开系统讲解三个核心成员——通用区域Section、五槽位原语Layout及其 Header/Content/Footer/Panel 区域与上下文动作栏Toolbar——的成员资格边界、所有权划分、十二条跨组件不变量FR1–FR12以及可验证的采纳现状。读完本文你将掌握哪些组件有权声称结构性区域、内边距与分隔线在区域之间如何归属、contentWidth在无面板/单面板/双面板三种组合下的几何行为、滚动与地标语义为何必须显式声明以及如何用仓库中的测试文件验证每一项契约。一、契约意图先定区域骨架再填充产品内容契约的核心意图只有一句话页面结构应该先于产品内容存在。构建者可以使用通用的Section、五槽位的Layout原语、或带语义的Toolbar而无需为每个页面自造一套 inset内缩、边界boundary、区域方向region direction或内容归属content ownership规则。从 Layout.tsx 的实现 可以清楚地看到这条意图的落地方式Layout通过AreaProvider把header/start/content/end/footer五个区域分别包裹在LayoutAreaContext中区域类型定义在 LayoutAreaContext.tsexport type LayoutArea | header | footer | content | start | end | null;任何渲染在槽位内的子组件都能通过use(LayoutAreaContext)感知自己身处哪个区域从而自动决定分隔线朝向与内边距。而页面外壳page shell本身不属于 Layout——契约明确约定AppShell负责将低层级区域与应用导航组合成完整页面外壳。Layout只是一块可复用的区域语法不拥有页面语义。二、成员资格规则什么才配叫结构化区域成员、协作者与排除项类别组件判定理由成员SectionLayout及其Header、Content、Footer、Panel区域Toolbar主要公开用途就是定义一个稳定的结构性区域通用页面/内容区域、五槽位拓扑中的具名位置、或上下文动作区域协作者family:layout-primitives任意子排列工具、architecture:container-paddinginset 与 bleed 系统、useResizable/ResizeHandle面板尺寸、AppShell页面外壳、组件主题视觉目标提供排列、内缩、缩放、组合与视觉能力但不改变区域所有权排除项Stack、Grid、Center及其修饰符FormLayoutCardAppShellTableDivider它们要么只是排列任意子元素不声称区域要么拥有独立的语义离散条目表面、页面外壳、结构化数据、分隔契约给出了一条极其明确的判定准则值得单独划重点A component does not join because it happens to render a flex row, a padded wrapper, or a header-like visual treatment.也就是说仅仅因为一个组件渲染了 flex 行、带内边距的包裹层、或长得像 header它不因此加入本家族。这与 docs/families/layout-primitives.md任意子排列工具和 docs/architecture/container-padding.md共享 inset 系统形成清晰分工排列归排列、内缩归内缩、区域归区域。为什么这个边界重要DEC-1决策记录DEC-1Decider:cixzhang,2026-08-30指出Section、Layout 及其具名区域、Toolbar 组成 layout-regions 家族而 Stack/Grid/Center 及其修饰符由独立的 layout-primitives 所有者管理。这样做的意义是让共享区域规则聚焦于结构性边界而不是把每一个 flex/grid 容器都变成页面区域。三、所有权划分每个成员管什么所有者管辖内容Section通用绘制型页面/内容区域variant、选中的分隔线边缘、组件内边距、嵌套 Section 行为Layout五槽位拓扑、槽位存在性、区域位置、共享外/内 inset、高度模式、内容宽度传播、默认 header/footer 分隔线上下文。不拥有页面外壳LayoutHeader/LayoutContent/LayoutFooter/LayoutPanel各自的区域元素、可选地标角色/名称、局部内边距、区域特定的尺寸或滚动行为Toolbar上下文动作区域start/center/end 泳道、toolbar 语义、键盘移动、尺寸级联。其绘制表面、variant 与选中分隔线边缘委托给 Sectionarchitecture:container-padding继承的 inset 与 bleed 机制useResizable/ResizeHandle缩放状态与交互LayoutPanel只接受它们提供的当前尺寸作为替代宽度所有者从源码看Toolbar 委托绘制表面给 Section是字面级的真委托Toolbar.tsx 直接以Section为根节点渲染把variant、dividers透传给 Section同时把paddingBlock按尺寸映射为紧凑的垂直间距Section ref{ref} variant{variant} paddingBlock{defaultBlockPaddingForSize[size]} dividers{dividers} xstyle{xstyle} className{className} style{style}而 Section.tsx 的实现 则展示了它的三重职责外层div负责嵌套逃逸负 margin 抵消父容器 padding、内层div通过container()解析出逻辑边缘变量、variant 与 dividers 决定绘制。Section 的三种 variant 对应三种背景见 Section.tsxsection--color-background-surface表面色transparent完全透明muted--color-background-muted弱化色四、规范概念表区域语法的七个维度契约用一张表定义了所有成员共享的规范概念concepts及其稳定级别概念值/状态默认语义稳定性generic regionSection相关的页面/内容区域带可选绘制处理currentfive-slot topologyheader, start, content, end, footerLayout 按逻辑阅读方向放置已提供的区域currentcontextual actionsstart, 可选 center, endToolbar 在受限内容区域内分组控件currentouter and inner insetLayout 边缘或相邻区域边缘Layout 区域使用与其接触边缘相匹配的 insetcurrentboundary无或分隔线成员只能绘制其组件契约暴露的边缘currentregion scrollclipped、scrollable、或页面所有在暴露处LayoutContent 与 LayoutPanel 拥有各自的当前 overflow 选择component-ownedlandmark无显式角色或调用方提供的角色与标签区域不会从视觉位置推断页面级地标语义currentregion sizeintrinsic、fixed、fill/auto、capped、或 resize 驱动在暴露处每个成员拥有其适用的尺寸轴component-ownedresponsive adaptation保留、省略、或由调用方组合替换不存在共享的自动区域切换caller/component-owned这张表最重要的信号是区域滚动、区域尺寸、响应式适配三者都是 component-owned / caller-owned家族本身不设置任何断点、不自动切换区域、不把滚动容器强加给所有成员FR7、FR9。五、跨组件不变量FR1–FR12区域行为的十二条宪法这是契约的绝对主体任何成员行为都不得违反。以下逐条展开并附上仓库实现证据。FR1 — 区域拥有结构而非产品含义成员建立空间边界并渲染调用方内容但不采纳内容的产品语义、状态或组件契约。也就是说把购物车、消息流或设置表单放进LayoutContentLayout 不会因此知道它们是购物车、消息流或设置表单。这是结构区域与业务组件的分水岭。FR2 — 区域方向是逻辑的start 与 end 跟随书写方向LTR 时 start 在左、RTL 时在右。分隔线放置与面板相邻性使用同一个逻辑区域位置。源码中这一条体现得非常彻底LayoutPanel的分隔线样式使用borderInlineEnd/borderInlineStart见 LayoutPanel.tsxSection 的边分隔使用borderInlineStart/borderInlineEnd见 Section.tsx全部是 CSS 逻辑属性而非物理 left/right。FR3 — Layout 依据槽位存在性选择几何Header/Content/Footer/Panel 在接触 Layout 边界处应用外 inset在接触另一个区域处应用内 inset。LayoutContent保持其根节点作为 scroll、padding 与直接子元素的唯一所有者。被省略的槽位不渲染区域包裹层——这一点由 Layout.test.tsx 直接验证does not render an area wrapper for an omitted slot。Layout 根节点的内层结构见 Layout.tsx是理解 FR3 的关键div layoutOuter fill/auto ← 负 margin 逃逸容器 padding div layoutInner stack vertical ← 重置容器 padding 变量 AreaProvider areaheader{header}/AreaProvider div middle stack horizontal ← 中间行start content end AreaProvider areastart{start}/AreaProvider div stackItem fill{content}/div AreaProvider areaend{end}/AreaProvider /div AreaProvider areafooter{footer}/AreaProvider /div /divlayoutOuter用calc(-1 * var(--container-padding-*))的负 margin 逃逸外层容器 paddinglayoutInner把四个--container-padding-*变量归零保证后代不会继承错误的 inset。需要说明的是FR3 同时记录了一个已命名的符合性缺口conformance gap——继承几何重新发布republish给全出血full-bleed后代的完整一致性仍受限于 docs/architecture/container-padding.md 中描述的 LayoutContent/LayoutPanel 现状。FR4 — 显式区域内边距取代自动 insetSection 发布其组件 insetLayout 把外/内 inset 分发到具名槽位区域的显式 padding 或零 padding 路径选择各自的局部样式。这一条并不宣称每个自动 Layout 边缘当前都精确地重新发布了一条匹配的后代变量——这是刻意为之的诚实边界。从 LayoutContent.tsx 可以清楚看到 inset 的外/内切换无 start 面板时noStart把paddingInlineStart与两个 inline 容器变量设为--layout-padding-outer-x无 header 时noHeader把paddingBlockStart设为--layout-padding-outer-y。padding{0}则走fullBleed路径把所有边与变量归零。FR5 — 边界所有权由调用方选择组合允许两个所有者时LayoutHeader与LayoutFooter各自拥有自己的隐含边缘Section 与 Toolbar 暴露所选边缘LayoutPanel可以绘制其面向内容侧的边缘而相邻的ResizeHandle也可能绘制同一条线——当前代码并不阻止两者同时绘制。因此契约给出硬性组合规则可缩放面板组合必须在相邻ResizeHandle拥有分隔线时设置LayoutPanel hasDivider{false}否则会出现双线伪影。这一规则在 LayoutPanel.tsx 的 hasDivider 注释 中有完全一致的提示验证映射表也承认尚无渲染测试阻止 LayoutPanel 与相邻 ResizeHandle 同时绘制分隔线。FR6 — 分隔线缺失可能改变间距Layout 区域当前会折叠与缺失 header/footer/panel 分隔线关联的内部间距显式分隔线则保留围栏边界。实测依据是 LayoutContent.tsx 中的祖先选择器paddingBlockStart: { default: var(--layout-padding-inner-y, ...), [stylex.when.ancestor(:has( .astryx-layout-header:not([data-divider])))]: 0, }当 header 没有分隔线时内容区顶部内边距折叠为 0实现无缝视觉衔接footer 同理。LayoutPanel的无分隔线路径还会通过collapseEnd/collapseStart负 margin 向内容侧折叠间距见 LayoutPanel.tsx。FR7 — 滚动是显式且局部的LayoutContent与LayoutPanel拥有各自的isScrollable行为Section 与 Toolbar不会因为家族成员身份而成为滚动容器。Layout heightfill容纳区域滚动heightauto让所在页面增长。两个组件的滚动默认值都是true且都支持isScrollable{false}以支持父级/页面滚动与 sticky 后代例如StickyElement。高度模式的实现位于 Layout.tsx 的 fill/auto 样式fill通过calc(100% 2x block padding)补偿负 block marginauto仅设minHeight: 100%。FR8 — 地标语义保持显式视觉上的具名位置不会自动分配banner、main、navigation、complementary、contentinfo角色。调用方必须提供受支持的角色与标签。源码中这些角色只是透传的 propsLayoutContent的role/label见 LayoutContent.tsx、LayoutPanel的role注释明确建议顶层布局才用navigation/complementary、LayoutHeader的role建议仅全站级 header 用banner、LayoutFooter的role建议仅全站级 footer 用contentinfo。LayoutSlots.test.tsx对提供的角色与标签能到达 Header/Content/Footer/Panel 元素有专门断言。FR9 — 响应式替换不是自动的Section 与 Toolbar 保持当前呈现Layout 渲染调用方提供的区域。当宽度变窄时由 AppShell、产品组合或其他组件特定的所有者决定省略或替换哪个区域。家族不设置任何断点与 AV7 一致。FR10 — 缩放所有权保持委托带resizable的LayoutPanel使用 hook 提供的当前尺寸而不是自己的widthprop。区域家族不重新定义 snapping、持久化、折叠、键盘或指针行为。实现只有一行LayoutPanel.tsx 第 227 行const effectiveWidth resizable ? resizable._size : width;配合useResizable({ defaultSize: 250, minSize: 200 })与相邻ResizeHandle resizable{sidebar.props} /的组合模式即可获得可拖拽侧栏。FR11 — 主题保持组件所有结构性成员身份不会自动创建家族级主题目标。当前.doc.mjs元数据记录已发布的 targets 与能力运行时themeProps()输出它们跨组件规则由 docs/architecture/component-theming-surface.md 拥有。组件 spec 在存在时可添加可选的 anatomy-mapping 元数据。FR12 — 内容宽度把滚动条保持在开放的 content 边缘这是关于contentWidth的完整几何规则也是契约中实现最精细的一条无面板时LayoutContent横跨可用中间区域并通过上下文感知的 inline inset 对齐直接子元素恰好一个面板时该面板保持对齐居中框架而LayoutContent延伸穿过对侧开放边缘start/end 镜像情形使用同一条规则两个面板都有时完整中间组合保持受约束constrained百分比与 intrinsic 宽度、以及裸变量因为它们无法安全共享同一个对齐基础所以保持受约束组合calc(var(...))是显式的长度值变量路径可据此选择进入边缘滚动。实现侧的判定函数supportsInternalContentWidthAlignment位于 Layout.tsx数字与无单位0直接支持内部对齐字符串中一旦出现%即拒绝calc|min|max|clamp前缀和数字单位的形式支持内部对齐。与之配套LayoutContent.tsx 的 constrained 系列样式 通过max(容器内边距, (100cqi - 对齐宽度)/2 容器内边距)这样的 gutter 计算在内容区自己仍是 scroll/padding 所有者的前提下把直接子元素对齐到contentWidth。六、允许的组件差异AV1–AV7家族内的合理变化编号差异维度内容AV1区域强度Section 是通用区域Layout 成员是五槽位原语中的位置感知槽位Toolbar 是语义动作栏AV2表面处理Section 与 Toolbar 可用 Section variants 与选中边缘Layout 区域用现有分隔线与 padding 处理。家族成员身份不统一它们的视觉 APIAV3区域内容header、footer、panel、content 与 toolbar 泳道可容纳其组件契约允许的任何内容AV4尺寸模型Layout 拥有 fill/auto 容器高度与内容宽度传播单个区域拥有适用的 height/width/padding/scroll propsSection 拥有 box-size propsAV5交互Toolbar 拥有 roving focus 与键盘提示其他成员不增加 toolbar 行为Resizable 拥有缩放交互AV6组合机制成员可使用 Stack 工具、直接 CSS 布局、context 或组件组合。可观察的区域契约是拥有的表面AV7响应式策略调用方可省略、替换或外部适配区域。家族不设断点AV5 的 Toolbar 键盘行为在 Toolbar.tsx 中落地useListFocus提供 roving tabindex 与方向键导航itemSelector: button, input, [tabindex]、hasRovingTabIndex: true、hasCaretGuard: trueuseKeyboardHint提供键盘提示同时通过SizeProvider把sizesm/md/lg级联给 Button、TextInput、TabList、Selector 等子组件使sm28px 元素、md32px、lg36px的控件尺寸自动对齐。Toolbar 的泳道布局也值得展开见 Toolbar.tsx 的样式只有 start/end两槽位flexspace-between只有 start 时让它flex: 1 1 0%填充只有 end 时用marginInlineStart: auto推到末尾提供 centerContent三槽位切换为 CSS GridgridTemplateColumns: 1fr auto 1frstart/end 泳道附加edgeCompSlot.inset(...)边缘补偿使 ghost 按钮、tab 等在容器边缘对齐时保持均匀视觉间距。七、代表性矩阵成员状态 × 共享不变量 × 刻意差异成员与状态共享不变量刻意差异Section / default, transparent, muted拥有一个通用区域并发布其应用的 insetvariant 与选中分隔线边缘是 Section 局部的Layout / 仅内容槽位存在性选择 Layout 边缘 inset有contentWidth时LayoutContent 横跨中间区域、内部对齐子元素、滚动条保持在 Layout 边缘Layout / 全部区域start/end 保持逻辑方向具名区域接收外/内 inset恰好一个面板时内容延伸到对侧开放边缘双面板时完整组合保持受约束LayoutHeader / LayoutFooter / 继承分隔线一个边界所有者 显式地标语义父级defaultHasDividers提供默认值局部false可覆盖它LayoutContent / scrollable 或 page-owned区域拥有当前 overflow 选择isScrollable{false}支持父级/页面滚动与 sticky 后代LayoutPanel / fixed 或 resize 驱动面板位置选择边缘处理useResizable 可取代宽度所有权ResizeHandle 保留交互所有权Toolbar / 两或三泳道上下文动作区域将其表面委托给 Sectioncenter 内容切换内部排列toolbar 独自拥有键盘行为Header/Footer 的分隔线解析顺序值得给出精确规则见 LayoutHeader.tsx 与 LayoutFooter.tsxconst resolvedHasDivider hasDivider ?? dividerCtx?.defaultHasDividers ?? false;即显式hasDivider优先 → 父 Layout 的defaultHasDividers其次 → 默认false最终结果还会写入data-divider属性供 FR6 的祖先选择器做间距折叠判断。八、采纳与例外当前现状与已知缺口契约用一张现状 缺口表记录每个成员的实际采纳程度。这张表里列出的都是已发布行为与验证缺口不是可以在文档 PR 中静默修改的已批准例外组件或关注点采纳情况当前缺口或例外Section通用区域与 container-padding 发布者嵌套逃逸始终是 inline 方向但 block 轴仅作用于 first/last childLayout 容器五槽位区域所有者带槽位 contexts仅内容的 LayoutContent 保持全宽并通过 inset 对齐直接子元素单面板时面板保持对齐而内容延伸到对侧开放边缘双面板或 intrinsic 宽度时中间组合保持受约束。测试覆盖拓扑浏览器证据覆盖镜像对齐与滚动条位置LayoutContent读取槽位存在性并应用外/内 inset无 start 路径把外值写入两个 inline 几何变量而无 end 路径只改 padding 不更新匹配变量LayoutPanel应用位置感知 padding可接受 resize 驱动宽度自动 Layout 边缘 padding 遗留基线内几何变量相邻ResizeHandle hasDivider可能双线除非调用方设置面板hasDivider{false}LayoutHeader/Footer区域特定 inset、边界与地标跨区域计算样式对等性未由单一浏览器矩阵覆盖ToolbarSection 支撑的表面 toolbar 行为inline inset 与边缘补偿跟随所组合 Section 的当前 padding 上下文响应式区域调用方/AppShell 组合LayoutPanel 目前没有共享的响应式可见性契约九、变更耦合改动一个区域时该碰哪里契约明确规定了变更联动范围防止家族契约被随意膨胀新增或修改结构区域组件检查成员资格仅当共享边界改变时才更新本契约改 Layout 槽位存在性、区域上下文、inset 分发、分隔线继承、高度模式或内容宽度传播更新对应区域测试与浏览器证据改 Section padding、嵌套逃逸、variant 或分隔线行为更新其组件契约并在继承几何变化时评审 docs/architecture/container-padding.md改 Toolbar 泳道、语义、键盘行为或尺寸级联属于 Toolbar 自身工作若改变其 Section 支撑表面或 inset 关系还需评审本家族与 container-padding 架构改 LayoutPanel 缩放集成评审 Resizable 的组件契约即packages/core/src/Resizable/useResizable.ts但不把缩放机制复制进本家族新增响应式隐藏/替换行为需要组件或更高级别所有者与兼容性证据——家族成员身份并不授权新增断点 prop。十、验证映射每条不变量由什么证据背书契约对每条不变量给出了具体的验证证据与缺失证据这是事实准确的最高体现。核心要点如下契约验证手段证据证明了什么缺失证据FR1Section/Layout/Toolbar 渲染与槽位测试调用方内容渲染在区域结构内Toolbar 暴露当前泳道测试未独立证明产品语义仍归调用方所有FR2逻辑属性源码审查 Layout 区域上下文测试start/end 槽位按逻辑识别源码选择逻辑分隔线/padding 属性无真实浏览器 LTR/RTL 几何矩阵覆盖每个区域FR3Layout.test.tsx 与 childrenAsContent.test.tsx槽位存在性与内容优先级被固定省略的槽位不渲染区域提供者测试未断言计算后的外/内 inset 或精确后代几何发布变量不匹配是已命名的符合性缺口FR4Section padding 类集测试 Layout 区域源码Section 的显式边缘覆盖移动匹配变量区域源码有自动/显式/零 padding 分支Layout 测试多数断言接受/渲染而非计算 padding 或自动变量对等性FR5, FR6Layout.test.tsx 与 LayoutSlots.test.tsxheader/footer 分隔线默认与显式 false 覆盖反映在data-divider源码含折叠样式无渲染测试阻止 LayoutPanel 与相邻 ResizeHandle 双线或证明计算折叠间距FR7LayoutContent/LayoutPanel 源码与局部类/渲染测试两个区域暴露当前isScrollable分支Layout 暴露 fill/auto 状态无浏览器测试证明每个 shell/区域组合下的滚动所有权FR8LayoutSlots.test.tsx 地标断言提供的角色与标签到达 Header/Content/Footer/Panel 元素无家族级无障碍树测试覆盖重复地标Layout content widthcontentWidth.test.tsx 与 Storybook 滚动条位置状态header/footer 保留对齐包装器无面板 LayoutContent 拥有全宽滚动区域单面板任一侧镜像内容穿过对侧开放边缘双面板保持组合受约束真实浏览器证据验证四种面板状态下的计算内容对齐与滚动条位置Toolbar 差异Toolbar.test.tsx泳道、role/name/orientation、Section variant 委托、当前键盘行为有聚焦断言无计算 inset/边缘补偿测试覆盖非默认父 paddingFR10LayoutSlots.test.tsx 中的 LayoutPanel 覆盖hook 提供的_size覆盖固定 width prop缩放交互、持久化、snapping、折叠仅由 Resizable 自身测试验证契约同时给出了一个诚实的总结论当前测试证明的是选定的结构、属性、回调与类/样式分支并不证明每种 Section/Layout/Toolbar/ResizeHandle 组合下的单一计算视觉对齐——采纳表明确命名了这些限制。十一、关键决策记录DEC-1 / DEC-2 / DEC-3三条决策分别锁定了家族边界、外壳归属与内容宽度几何DEC-1 — 结构区域与组合原语分属不同所有者cixzhang,2026-08-30Section、Layout 及其具名区域、Toolbar 构成 layout-regions 家族Stack/Grid/Center 及修饰符由独立的 layout-primitives 所有者管理。目的是把共享区域规则聚焦于结构性边界避免每个 flex/grid 容器都变成页面区域。DEC-2 — AppShell 拥有页面外壳cixzhang,2026-08-31AppShell 拥有页面外壳与应用导航组合Layout 是在页面或有界容器内排列header、start、content、end、footer的通用五槽位原语container-padding 参与者保留各自组件所有权。DEC-3 — 仅内容的宽度对齐保持在内容滚动口内cixzhang,2026-09-09无面板时 LayoutContent 横跨中间区域并通过上下文 inline inset 对齐直接子元素单面板时面板保持对齐居中框架而内容穿过对侧开放边缘start/end 逻辑镜像双面板或百分比/intrinsic/未解析裸变量无法安全共享同一个 CSS 算术基础时完整中间组合保持受约束保证能解析为长度值的变量用calc(var(...))选择进入边缘滚动。十二、开放问题与内容边界契约的开放问题Open questions为空——采纳表中的可检查源码与浏览器工作属于工程任务而非未解决的家族策略。内容边界Content boundary本记录只拥有共享的结构性区域行为。它不重复组件 prop 表、不定定义任意子排列、不拥有产品或导航语义、不规定视觉设计、不分配响应式断点、不重新定义缩放交互、不拥有组件主题的 anatomy 与 targets。理解这条边界才能正确地把它当作区域语法来使用而不是当作万能布局引擎。延伸阅读区域 inset 的底层协议docs/architecture/container-padding.md任意子排列工具排除项docs/families/layout-primitives.md组件公共 API 规范docs/architecture/public-component-api.md跨组件主题规则docs/architecture/component-theming-surface.md核心实现Layout.tsx、Section.tsx、Toolbar.tsx关键测试Layout.test.tsx、LayoutSlots.test.tsx、contentWidth.test.tsx、Section.test.tsx、Toolbar.test.tsx【免费下载链接】astryxAn open source design system thats fully customizable and agent ready项目地址: https://gitcode.com/GitHub_Trending/as/astryx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考