图层继承文本与分组边界系统规范¶
目的¶
打开对话框、菜单、工具提示或其他浮动阅读表面的人,绝不能仅仅因为其触发器位于格式化的段落、标题、表格单元格或代码区域中,就收到居中、斜体、大写、缩进或不可换行的正文文本。图层在保留周围主题和语言上下文的同时,开启一项新的阅读任务。原生顶层提升改变的是绘制方式,而不是 CSS 继承,因此边界必须是显式的。该图层也不是某个祖先视觉组的另一成员:其内部的按钮和输入框不得继承该组的连接边框、尺寸、密度或其他呈现默认值。触发器保留其组样式;新打开的表面开启自身的作用域。在 FR7/FR8 下,表面/组成员关系整体停止;不相关的上下文以及显式编写的属性和无障碍语义均予以保留。
原始契约已由 cixzhang 于 2026-09-23 批准(DEC-1–DEC-3)。同日,cixzhang 将其范围修正为仅限文本/布局/视觉隔离(DEC-4)。已批准的 DEC-5 移除了分离视觉字段的要求:在 FR7/FR8 下,表面/组成员关系整体停止。不相关的 ARIA、焦点、键盘所有权、关闭、语义/数据/交互上下文,以及编写的 DOM/无障碍树语义保持不变。cixzhang 批准了 DEC-4,并于 2026-09-23 授权其仅限规范的合并。实现 PR #6457 可能与本已接受的契约保持一致。本记录和测试成功均不授权实现合并。架构对该决策进行投射,而非独立批准它。
所有权¶
AST-038 拥有已关闭的继承文本基线、祖先视觉组边界、参与规则、优先级和兼容性决策。它与 AST-003 不同,后者的非目标明确排除了视觉处理。AST-003 仍是已接受的托管与交互变更的所有者;本规范既不重复这些需求,也不使其未实现的变更生效。
图层运行时 描述了已发布的托管机制,并在实现后投射已批准的文本边界。其现有批准不能授权这一新的跨组件样式决策。组件样式编写、主题应用 和公共组件 API 分别继续拥有降级、实时主题上下文和现有覆盖接缝。已检查受影响图层路径、layerTextReset、inherited text 和 AST-038 的当前记录与进行中的工作;重叠实现是 PR #6457,而非独立的已批准契约。
非目标¶
- 重新设计托管、门户、定位、模态语义、焦点、关闭、选择、滚动、动效,或哪些图层出现在原生对话框之上。在 FR8 下停止祖先视觉样式和整体成员关系属于范围内;不相关的交互、集合成员关系、禁用/选中状态、标签/描述和无障碍语义不改变。特别是,不要中和
aria-disabled、改变无障碍树禁用继承、添加语义角色,或引入纠正性门户托管来满足本样式契约。 - 标准化图层内部的前景、背景、几何、组件类型角色或有意的排版;改变全局文档重置或非 Astryx 元素;中和祖先文本装饰传播。
- 新的组件属性、重置退出机制、公共重置工具、主题目标、令牌、包装器或运行时样式复制。现有的显式样式接缝仍然是请求有意格式化的方式。
- 新的无障碍契约、视觉测试产品或测试基础设施。验证证明的是此样式契约;它不授权工作流新增或修改,也不授权对不相关集成评估器的更改。
- 等效的内部实现仍然有效。私有模块名称和共享机制属于架构或实现,而非本契约。
需求¶
已关闭基线¶
FR1 — 中性阅读基线。 每个参与的内容边界在组件和调用方样式之前,必须精确建立以下继承属性默认值。未列出的继承文本属性不由 FR1 重置。
| 属性 | 基线 | 原因 |
|---|---|---|
font-family |
var(--font-family-body) |
不借用代码或标题字体。 |
font-size |
var(--text-body-size) |
在活动主题的正文角色中开始普通内容。 |
line-height |
var(--text-body-leading) |
保留主题的正文阅读节奏。 |
font-weight |
var(--text-body-weight) |
不借用触发器的强调。 |
font-style |
normal |
被强调的祖先不得使该任务变为斜体。 |
text-align |
start |
从阅读边缘开始,包括 RTL。 |
text-align-last |
auto |
不继承末行对齐。 |
text-indent |
0 |
不继承段落或图标替换缩进。 |
text-transform |
none |
保留编写的字符大小写。 |
letter-spacing |
normal |
不继承标题字距。 |
word-spacing |
normal |
不扭曲阅读或固有尺寸。 |
text-shadow |
none |
不借用装饰性文本阴影。 |
white-space |
normal |
允许在 preformatted/nowrap 祖先下进行常规换行。 |
word-break |
normal |
将特殊的断词留给内容所有者。 |
overflow-wrap |
normal |
将长 token 的换行留给内容所有者。 |
hyphens |
manual |
不继承自动断字。 |
FR2 — 主题与书写上下文得以保留。 边界 MUST 保留
direction、writing-mode、text-orientation、语言、主题/自定义属性
值、color-scheme、字体特性/变化设置以及无障碍偏好。
即使由自定义属性携带,局部布局/呈现值也属于 FR7;这并不授权按前缀清除属性或重置语义主题标记。
主题不是祖先布局提供者。
当局部主题发生变化时,Theme body tokens MUST 保持有效。
这并不承诺比现有宿主契约提供更多的上下文恢复。
FR3 — 表面、行为和无障碍所有权得以保留。 颜色/背景配对、
几何、显示、定位、动画、不透明度、可见性、光标、
pointer-events、touch-action 和 user-select MUST 保留其现有所有者。
ARIA 属性、焦点、选择、禁用/只读状态、回调、
键盘所有权、关闭、语义/数据/交互上下文以及 DOM/AX
语义 MUST 保持不变,除非是成员所有的值在 FR8 下随其整个上下文一起终止。
不要因为内容在视觉上独立而更改事件路由或漫游焦点。
反转的 Tooltip 和 Toast 颜色、Lightbox 标题以及点击穿透的
通知/非模态主机不得被文本基线更改。
container-padding 边界 是独立的。
text-decoration 不会被继承;后代的 none 无法移除从祖先传播的装饰,且不属于 FR1 的一部分。
参与台账¶
FR4 — 阅读表面,而非关闭角色。 纳入要求一个 承载内容的 Astryx 表面,通过 Layer、原生 Dialog 或等效的 layer 宿主呈现在其所有者正常流之外。 同一表面的模态、非模态、回退和行内预览呈现 MUST 共享该基线。 组合组件在其现有内容边界处接收它,而不是在触发器处。 嵌套层会建立自己的边界。
| 表面系列 | 参与路径 | 原因/完成标准 |
|---|---|---|
| Layer 承载的内容 | Context/anchor, context/custom, and fixed Layer; Popover/usePopover; Tooltip/useTooltip; HoverCard/useHoverCard; ContextMenu; DropdownMenu submenus | 公共边界在每个渲染器中中和环境格式,而不改变几何或宿主方式。 |
| Popover 组合组件 | DropdownMenu, MoreMenu, NavHeadingMenu, TabMenu, TopNav menus, collapsed SideNav items and heading menus, BreadcrumbItem menus; Selector/MultiSelector/ComplexSelector, Typeahead/BaseTypeahead, date inputs, PowerSearch, ChatComposerInput menus, Table filtering; Lab TourStep, ChatEmojiPicker, InfoTip | 继承公共重置;不重复重置或更改触发器/API。 |
| Layer 工具类表面 | Keyboard hints, Carousel controls, Tokenizer overflow, chart/radial tooltips, ListInput/TransferList drag previews | 共享宿主提供基线;作者编写的提示/图表 nowrap 和组件排版仍然优先。 |
| Dialog 系列 | Modal and inline Dialog, AlertDialog, imperative Dialog/AlertDialog, CommandPalette | 原生和预览路径保持一致;组件和调用方样式保持更强。 |
| 独立查看器/导航 | Lightbox, MobileNav including AppShell, Lab Drawer in modal and non-modal modes | 每个独立根节点都参与;媒体/标题处理与交互保持不变。 |
| Sheets | 独立与切换的 BottomSheet,包括自适应菜单/输入呈现形式 | 绘制的内容面板拥有边界,而非其透明外壳或每个子元素。 |
| Notifications | 提升层与非顶层 ToastViewport;LayerProvider 与命令式回退方案 | 该 viewport 提供默认/自定义 toast 文本,而不重置页面子元素,也不改变颜色和指针行为。 |
Tooltip/HoverCard 的使用者(包括 Button、Link、Text、Timestamp、Avatar、 StatusDot 和字段说明)无需独立的触发器变更。 排除项:文档流内的 ChatComposerDrawer、Overlay/OverlayScrim、本地图表的 十字准线和缩放控件、空 Tour 高亮/遮罩,以及仅通过 portal 挂载的 Token 或 Stepper。Tour Popover 的标注气泡参与其中。仅移动 DOM 并不会将普通内容变成阅读层。
优先级与兼容性¶
FR5 — 显式样式优先。 仅将基线应用于承载内容(content-bearing)的根节点,且须在组件样式以及受支持的主题/使用者覆盖之前应用。切勿重置后代元素。有意的标题、代码、居中说明文字、粗体强调、不换行提示,以及 Tooltip/Toast 的断词规则 MUST 保持有效。现有的 xstyle、className 和 style 优先级顺序 MUST 不得重排。
FR6 — 不新增选项或公共表面。 不提供重置的选择退出 prop、公共重置辅助函数/导出、新的主题目标或 token。有意依赖继承格式的调用方,必须在现有的根样式接缝或自身内容上表达这一意图(包括在支持处显式使用 inherit)。对这些调用方而言,这是一项可见的兼容性变更,必须在使用者指南和发布说明中说明。普通主题正文内容不得获得无关的视觉变化;所选组件类型角色仍归组件所有。
祖先布局与分组边界¶
FR7 — 祖先布局与呈现止于层边界。 所有提供方的作用域内布局、视觉、密度、尺寸、分组或呈现调整 MUST 默认在内容边界处停止;surface/group 成员上下文在 FR8 下整体停止。这包括通用 SizeProvider,而不仅仅是 ButtonGroup/InputGroup 提供的尺寸,并且按职责适用于未来提供方,而非固定的名称允许列表或当前证据台账。该方向已在 DEC-2 中获批。
触发器/控件仍保留在其祖先作用域内。层内容不得仅因 DOM 或 React 祖先关系而获得祖先组连接的圆角/边框/分隔线处理、视觉方向、密度或尺寸。无论呈现方式是由上下文、选择器/标记还是作用域结构自定义属性承载,该边界均适用。仅靠 CSS 文本重置并不能满足要求。主题和书写上下文仍由 FR2 覆盖。语义角色与方向、禁用/选中状态、可访问命名、集合成员关系、回调和交互行为 MUST 保留其现有的归属和值,但 FR8 下停止的整体 surface/group 成员关系除外。
FR8 — 整体 surface/group 成员关系;无关归属仍然保留。 无关的语义、数据、交互和可访问性提供方 MUST 保留其现有的继承和归属协议。
有意针对层内内容的布局/视觉/呈现提供方 MUST 在其内容边界内部/跨内容边界单独建立。这些提供方管辖其后代,直至下一个层边界。显式的子级 props 继续有效;主题和书写上下文仍由 FR2 保留。这些规则按职责而非名称适用于未来提供方。
当 FR7 适用于由某个上下文承载的 surface/group 成员关系时,该现有整体值停止;视觉字段不会被分离。成员所属的状态(包括禁用/只读状态)随之停止。无关的上下文、显式编写的 props 以及现有公共 Context/Provider 形态保持不变。这并不意味着存在公共选择退出机制或特定的私有机制。
仅凭上下文字段类型并不能证明它是纯呈现性的。AvatarGroup 存储视觉尺寸/形状/重叠值,但它的存在也决定了 Avatar 的 tooltip tabIndex 和可聚焦性。该组成员关系在 FR7/FR8 下整体停止。LayoutArea 选择语义 DOM 元素以及分隔线和间距;其语义元素选择保持不变。
该层不会清除所有 React 上下文,也不会覆盖每个后代的几何属性。分组的触发器保持视觉分组,显式的内部视觉组正常工作。无关的语义归属保持不变。
这些示例说明了所接受的通用区分,而不是一个封闭的例外列表:
| 表面所有者 | 能够存续的显式所有者协议 | 不再生效的祖先呈现 |
|---|---|---|
| DropdownMenu 和 子菜单 | 该菜单的 radio 选择、其关闭链以及为其项目/子菜单表面显式建立的菜单自有尺寸。当前菜单在渲染内容周围建立自己的上下文;子菜单将其关闭回调与父级组合。 | 外层 ButtonGroup 的视觉样式以及环境 SizeProvider/视觉默认值。菜单自有尺寸由表面所有者有意建立,而非通用尺寸提供者的豁免。 |
| Selector / Typeahead | 所有者的选项/结果、活动选项、搜索查询和选择回调仍与其自己的弹出层保持连接。当前代码通过本地状态/闭包以及组件 props 携带这些内容;此示例不需要新的上下文。 | 外层 InputGroup 的尺寸、相连边框/圆角以及其他组视觉不会作用于弹出控件。输入框/触发器本身保持分组。 |
| 表格筛选 | 列身份、筛选值/草稿以及应用/清除行为属于筛选表面。当前代码在弹出层内建立草稿 FilterStoreContext,并显式传递列 key。 | 外层的表格/行密度、分隔线、对齐方式以及其他局部作用域的呈现不会成为筛选面板的默认值。筛选表面可以建立自己的本地布局。 |
表格筛选的显式内部 store 是一个内容提供者示例。故意放置在层内的 SizeProvider 或 ButtonGroup 同样适用于该内容,但围绕其触发器的同一提供者则不会。嵌套层会开启另一个边界,并需要自己的显式内容提供。图表数据、表单模型和层关闭协调保留其现有的继承和所有者协议;完整表面/组成员关系遵循 FR8。
分组证据与范围台账¶
审计检查了提议的纯文本实现中的分组提供者/消费者,并与基础版本 1d940e032cab3c45d404a40f0ce8502db5b98059 进行了源码交叉核对。ToggleButton 较新的操作处理被单独检查,并保留相同的组成员关系路径。只读静态渲染探针使用了 12991d841df03c6455ba669a026373d55c68bc45 处的纯文本实现及其移除作用域的进行中更改。静态渲染证明了所陈述的 props/关联,而非浏览器几何信息。本次审计不声称实现任何分组边界;实现遵循下文所接受规则。台账记录的是证据,而非限制 FR7 适用于未来布局或呈现提供者的允许列表。观察结果具有历史性;提议的边界遵循 FR8 中的整体成员资格规则。
| 所有者 / 证据接缝 | 实际机制与观察结果 | 提议边界 / 验证 |
|---|---|---|
所有者:ToggleButton 与外部 ButtonGroup 的关联先于层存在;该层不会取代其自身的外部组。所有者源码:ButtonGroup.tsx 和 ToggleButton.tsx;提供者处理位于 ButtonGroupContext.tsx。(源码链接为大型片段;审计会比较相关部分。) |
机制上,ToggleButton 仍会消费 ButtonGroupContext,且没有特定于层的条件。由于 ButtonGroup 中不存在层相关处理,当层作为表面时,ToggleButton 的 ButtonGroup 成员关系不变。祖先 ButtonGroup 样式继续应用于已分组的 ToggleButton;未实现任何基于层的样式移除或替换。 | 边界:除非表面所有者显式建立自己的组,否则 ToggleButton 仍是外部 ButtonGroup 的成员。验证:活动 ButtonGroup 成员关系在 React DevTools 中显示为 ButtonGroup 上下文值;提议的纯文本实现不会对提供者连接做出特定于层的更改。 |
所有者:菜单和子菜单依赖显式的菜单自有尺寸,而非环境 SizeProvider 默认值;菜单弹出层/表面的构成包括菜单的 context和子菜单。 |
机制上,DropdownMenuContent 在渲染内容周围建立 DropdownMenuContext 和 DropdownMenuSubMenuContext;子菜单将父级的关闭回调传入其内容。该表面拥有的尺寸通过专用弹出层表面上的显式子组件(DropdownMenuItem、DropdownMenuSubMenu)表达。 |
边界:菜单表面拥有其项目/子菜单上下文;外部 SizeProvider/ButtonGroup 继续影响触发器,但不影响弹出层内容。验证:静态渲染探针显示菜单上下文是 DropdownMenuContent 的子项;祖先 SizeProvider 仅围绕触发器渲染。 |
所有者:Selector/Typeahead 弹出层表面当前在所有者上保留选项、活动选项、搜索和选择回调;弹出层由所有者 props 呈现。来源:.../Selector/Selector.tsx、.../Typeahead/BaseTypeahead.tsx。 |
机制上,Selector 和 typeahead 弹出层表面当前从其所有者接收相关 props;除 InputGroup 外,它们不依赖环境分组上下文。它们的弹出层渲染不会被本地 SizeProvider 或视觉组包裹。 |
边界:弹出层控件不受祖先 InputGroup/ButtonGroup 样式影响;任何内部分组都必须是显式的。验证:静态渲染探针确认该层本身不会在 Selector 的弹出层/typeahead 列表周围引入提供者。 |
所有者:表格筛选弹出层表面拥有筛选列 key、筛选值/草稿以及应用/清除回调。来源:.../Table/plugins/filtering/useTableFiltering.tsx。 |
机制上,当前代码在弹出层内创建 FilterStoreContext,并提供 columnKey、filter 和 draftFilter 的值/回调。它不会用任何祖先表格/布局上下文包裹弹出层;也不会将行密度或表格对齐作为默认值使用。 |
边界:筛选表面保留其本地布局和 store;周围的表格上下文不会为筛选弹出层设置样式。验证:静态渲染探针确认已应用的筛选行内容从弹出层内部接收 FilterStoreContext,且其内部未使用表格级提供者。 |
| ButtonGroup, Button | React 上下文提供方向/禁用状态;共享的 SizeContext 提供尺寸。Button 自行应用对兄弟组件敏感的圆角/分隔线规则,并抑制独立的阴影/按压效果处理。在 inline Dialog 与 fixed Layer 下进行静态渲染的探针产生了一个内部按钮,其带有 disabled 和来自外层组的 data-size="lg"。没有任何组祖先标记或组专属的继承 CSS 变量提供这些规则。 |
当 FR7 适用时,整个组成员身份随视觉方向、尺寸、连接圆角/分隔线、阴影效果处理以及组拥有的禁用状态一起终止。保留分组的触发器与显式内层 ButtonGroup。 |
| InputGroup, groupStyles, TextInput | 上下文携带成员身份及标签/描述 ID;SizeContext 携带尺寸。消费方应用 100% 高度/flex、负边框重叠、兄弟圆角,并跳过其常规 Field 包装器。两个探针均使内部 TextInput 获得 lg,并生成一个由外部与内部标签组合而成的无障碍标签。该上下文没有 disabled/status 布尔值:不要凭空引入一刀切的状态重置。 |
当 FR7 适用时,外部尺寸、连接边框/布局呈现以及组拥有的标签/描述关联随整个成员身份一起终止。保留显式编写的标签、Field 语义、status/disabled/read-only 属性以及局部 InputGroup。 |
| AvatarGroup context, Avatar | 上下文携带尺寸/形状/重叠;Avatar 添加环形/负重叠,并改变其工具提示的 Tab 停靠点。两个探针均在层内产生了 lg/square,且没有局部组属主。 |
当 FR7 适用时,整个组成员身份终止,包括尺寸/形状/环形/重叠以及成员身份拥有的工具提示可聚焦性。保留显式属性与无关交互;几何布局仍需浏览器验证。 |
| ToggleButtonGroup, ToggleButton | 上下文携带选中值、切换回调、尺寸与禁用状态。两个探针均从祖先组产生了一个按下的 lg 内部切换项。当存在 value 时,源码会将激活事件路由到该组的回调。 |
当 FR7 适用时,整个组成员身份终止,包括尺寸、选中值、禁用状态以及组回调属主。保留显式编写的属性/回调以及局部组。 |
| SizeContext | sizeProp ?? inherited ?? default;provider 包括 ButtonGroup/InputGroup 和 Toolbar/SideNav。该值没有来源信息,无法区分显式的通用 SizeProvider 与由组提供的默认值。 |
所有环境中的 SizeProvider 默认值都会在此停止,无论其来源如何(DEC-2、OQ2 已解决)。在该层内部建立的显式控制 props 和 provider 继续在这里生效。 |
| Collapsible group contexts | 状态上下文和展示上下文是相互分离的。Collapsible 已经清除了其子元素周围的展示;状态则有意保持分离。 | 保留现有的这一防护。在更改它之前,先核实任何绕过路径;不要把状态上下文仅仅视为一种分隔线样式。 |
| ListContext, MetadataListContext | 源码消费方分别继承密度/分隔线/列表标记,以及元数据方向/标签布局;未发现通用的层防护。对于这些路径,不声称已进行像素级或交互级复现。 | 等效的展示候选:在增加实现工作之前,先确认一种受支持的独立层组合。层内已有的组继续作为所有者。 |
| RadioList, CheckboxList, SegmentedControl, TabList, menu radio group | 这些上下文拥有集合值、回调、可用性、角色/名称,有时还包括尺寸。若干子 API 需要其 provider,缺少时会抛出异常。源码可达性并不能证明每种跨层组合是受支持的,还是偶然发生的。 | 保留无关的或内容局部的所有权,以及 FR7 不适用的所有权。在 FR7 下,整个祖先表面/组成员关系值会停止传递;需要这些值的消费方必须在该层内部建立其完整的 provider。 |
ButtonGroup 的 roving-focus 边界已经排除了嵌套的 groups/popovers;Button/InputGroup 尾部边缘选择器会跳过 [popover]/template 兄弟节点。它们保护的是外部触发器的成员资格,而不是弹出层内部的后代控件。请保持这些既有修复不变。基于新的 layer-content 标记对通用 useListFocus 进行条目过滤或事件所有权更改,均不属于本次视觉重置范围,且 MUST 从实现中还原。键盘所有权(包括现有的嵌套 group/popover 排除规则)保持不变。 |
||
| 源代码搜索还检查了 FormLayout、Table/Stepper 以及导航上下文/标记。它们作用域内的布局/呈现职责属于 FR7,无论本次审计是否点名;它们的语义/数据/交互/无障碍职责必须保持不变。 | ||
SegmentedControl 还为项圆角使用继承的私有 --_segmented-control-radius/--_segmented-control-padding 值;Tab/TabMenu 从 strip/container 几何中消费 --_tab-indicator-bottom。AvatarGroupOverflow 的私有重叠值是在其自身根元素上定义的。这些是需要检查的具体结构通道,而不是抹掉每个自定义属性的理由。RadioList 指示器和 Tab 悬停/激活标记为局部交互反馈提供样式。作用域内的指示器/行标记不是组上下文屏障;在没有匹配的后代和浏览器状态复现的情况下,不声称观察到标记泄露。 |
现有规范化:仅合并等价项¶
FR9 — 先前的修复是证据,不是删除清单。 只有当值、目标、级联优先级和受支持状态等价时,规范化才能移入共享边界。当等价性缺失时,局部类型角色、换行、颜色、几何和所有权保护 MUST 保持组件自有。
| 现有代码 | 发现与处置 |
|---|---|
| useLayer 基础排版 | 现有的 body 字体族/字号/行高是唯一等价的基线,已被纯文本实现移入私有共享重置中。对于这三条声明,不打算做任何 token/value 或优先级更改。 |
| Tooltip 绘制表面 | 显式的 body 排版、反色以及内容 wordBreak: break-word 都是有意为之。请保留它们;将内部声明向外移动可能改变受支持的覆盖行为,即使值相同。 |
| Toast | 使用 body 默认值处理尺寸/行距、表面反转和内容 overflowWrap: anywhere。这并不等同于用继承的实时 body 变量替换它们。保留它们。 |
| Lightbox、菜单行、键盘提示、图表/径向工具提示 | Lightbox 的说明文字通过 MediaTheme(component:Lightbox)下的 Text 渲染。菜单标签/辅助类型和起始对齐、较小的 nowrap 键盘提示以及紧凑的图表换行仍然是有意的局部呈现。不要将它们作为冗余重置删除。 |
| useLayer portal 写入上下文、padding 重置 | 矫正性 portal 在不快照 token 的情况下保留丢失的方向/书写模式。现有的 padding 边界重置其自身的结构变量。两者都保留;两者都不是通用分组或文本屏障。 |
| Button/InputGroup 端盖规则和 Collapsible/BottomSheetSwitcher 上下文守卫 | 已解决不同的成员资格/所有权问题。保留它们;文本边界不能替代兄弟分类、嵌套呈现隔离或 sheet 注册范围。 |
Item/TreeListItem/Collapsible/Stepper/Token/Thumbnail/ChatComposer 控件上的 all: unset |
局部 UA/控件重置,而非 layer 根继承修复。未提议新的 all/unset/revert layer 重置。ToastViewport 的 inset: unset 是几何属性;menuWidth 的 unset/revert 字符串是调用方提供的宽度关键字,路由到 inline-size 而非 min(),并非通用继承重置。 |
审计发现 Layer 或独立的原生根中不存在现有的通用 ButtonGroup/InputGroup 上下文屏障。React portal 保留上下文,原生 top-layer 绘制不会破坏选择器祖先关系。因此,上述分组控件泄漏在提议的纯文本重置后仍然存在。
实现要求¶
- IR1 — 有边界的样式,而非沙箱。 使用受支持的组件局部 CSS 声明。不要使用
all、font简写、通用/后代重置、全局[popover]/dialog选择器,或复制计算后的祖先样式。 - IR2 — 最小边界接线。 在包边界允许的情况下内部共享基线;在独立根处确保等效声明,而不要仅为共享样式创建公共 API。不要不必要地更改运行时效果、包装器、portal、交互逻辑或组合调用点。
- IR3 — 范围与权限保持分离。 架构和简洁的消费者文档体现这一已接受的决定;它们不重复独立策略。接受并不代表已发布行为或授权合并。验证不得用于扩大实现范围。
- IR4 — 包容性责任,有边界的实现。 Provider 隔离必须是私有的、感知所有权的,并在 FR4 内容根之间保持一致。按责任应用 FR7,包括未来的作用域布局/视觉 provider,而非本审计中复制的固定重置允许列表。不要清除无关上下文或自定义属性。当 FR7 适用时,整个表面/组成员关系在 FR8 下停止,而不分离视觉区域。不暗示 DOM 包装器、公共边界 API、语义角色、ARIA 中和、portal 或通用 CSS 重置;验证必须覆盖视觉隔离以及未改变的无关行为/可访问性。
平台支持¶
- 支持的功能/引擎下限:现有的浏览器支持策略适用;本规范不提高引擎下限。原生托管仍遵循其自身的支持契约。
- 不支持的行为:现有的显示回退必须保留相同的文本基线。此更改不会将其升级为原生 top-layer、定位或关闭的等效行为。
- 浏览器证据:实际的 CSS 继承、主题级联、换行和像素需要真实的 Chromium;DOM 单元环境中发出的声明不足以作为视觉证明。不会从 Chromium 输出中做出任何 Safari 特定的声明。
当前状态影响¶
实现后,architecture:layer-runtime 将投射基线所有权并链接此规范。Layer、useLayer 和 Dialog 的使用者指南将说明根/内容处的有意格式化,变更集将描述兼容性影响。家族成员资格、贡献者策略、主题应用语义或 AST-003 声明均无变化。
验证¶
| 契约 | 验证 | 代表性状态 | 变更或失败预期 |
|---|---|---|---|
| FR1, FR4 | 现有真实浏览器视觉回归和计算样式证据,覆盖所有受支持的 layer 内容根 | 两种 Layer 渲染器、原生/内联 Dialog、独立原生根、独立/切换的 sheets、提升/托管的 Toast、模态/非模态的 Drawer | 移除某一边界的基线会在浏览器比较中恢复继承的格式化。 |
| FR2, FR5 | 单元覆盖控件加上真实浏览器级联证据 | 嵌套/浅色/深色主题、LTR/RTL 和垂直书写、实时 body 令牌;编写的子元素强调/代码和直接根覆盖 | 宽泛重置、后代规则、冻结令牌或颠倒的优先级会使保留上下文/样式控制失败。 |
| FR1, FR6 | 实现 PR 中保留真实浏览器前后像素 | 正常主题 body DOM 和一个故意敌对的居中/斜体/大写/缩进/加空格/带阴影/预格式化的祖先;父级和子菜单 | 恢复继承的对齐会产生明显居中的敌对文本;正常基线保持不变。将突变标记为回归控制,而非历史来源。 |
| FR3, FR4 | 现有组件行为测试和浏览器检查 | 定位、焦点/关闭、标题和反色、点击穿透视口/非模态宿主 | 移除或重新排序的组件样式会使现有控件失败;不会推断出更广泛的交互契约。 |
| FR6, IR1–IR3 | 差异审查、现有 lint/类型/构建/知识检查 | 导出映射和桶文件、重置声明、架构投影、变更集 | 新的公共重置 API、广泛的选择器、工作流变更或未经所有者批准的批准声明会使审查失败。 |
使用现有视觉回归进行呈现,并使用已建立的组件测试来验证 FR7/FR8 行为。
检查敌对外层组和 SizeProvider 默认值下的视觉尺寸、密度、连接角/分隔线、重叠和布局。包括原生/内联 Dialog、现有的内联/校正性传送上下文 Layer 路径、固定 Layer,以及不添加宿主路径的独立根。保持外部触发器在视觉上分组,并让显式内部视觉/布局提供程序正常工作。按职责(而非仅按当前名称)验证未来风格的限定作用域呈现提供程序;嵌套 layer 将再次阻止环境呈现。
行为和可访问性检查会保留无关行为与显式属性,但成员关系拥有的值在 FR8 下停止除外。比较 ARIA、标签/描述、焦点/制表位、键盘所有权、禁用/只读和选中/按下状态、回调标识和结果、关闭,以及 DOM/AX 语义与现有行为。保持无关的语义/数据/交互上下文活跃且不变。保留 LayoutArea 的语义 DOM 元素和 useListFocus 现有的项/事件所有权。保留菜单单选/关闭、Selector/Typeahead 的活动选项/搜索/选择,以及 Table 筛选草稿/应用行为。验证成员关系拥有的状态随其上下文停止,而显式编写的禁用或选中属性仍然有效;不需要新的无障碍树边界。
真实浏览器检查确立呈现和保留的行为;静态渲染无法证明像素。移除视觉隔离屏障必须恢复匹配的视觉泄漏。更改无关的语义字段、ARIA、键盘路由、宿主或回调必须使保留控制失败。FR9 保留本地文本/换行以及现有的组尾/键盘防护不变。
浏览器截图及其来源属于 PR 证据;此样式决策不需要专门的无障碍规范、提交的故事矩阵或新的工作流/工件接线。测试成功是证据,而非所有者批准。
决策日志¶
DEC-1 — 已接受的中性阅读边界¶
参考: spec:AST-038/DEC-1
决策者: cixzhang, 2026-09-23
批准了 FR4 边界处的封闭 FR1 基线,保留 FR2/FR3,FR5 优先级,以及 FR6 的兼容性/无新 API 契约。这使得同一阅读任务不受偶然触发器格式的影响,同时不会抹除其主题或有意的内容样式。
已拒绝:仅处理 Dialog(其他层仍会继承);重置所有 CSS(会破坏无关的样式/上下文);重置文档级 dialog/popover 选择器(会改变非 Astryx 的 UI);保留所有环境排版(会保留已报告的问题);提供 opt-out prop 或公共重置工具(在现有样式接缝已足够的情况下,增加了永久的调用方选择)。
DEC-2 — 已接受的包容性布局提供者边界¶
参考: spec:AST-038/DEC-2
决策者: cixzhang,2026-09-23
批准 FR7:所有表面级布局、视觉、密度、尺寸、分组和呈现提供者默认在图层内容边界处停止,包括通用 SizeProvider 以及未来承担这些职责的提供者。这不是一个固定的允许列表。触发器保留在其所属分组中;独立图层内容不会隐式加入其视觉样式。DEC-4 澄清了语义成员身份和行为保持不变。主题与书写上下文得以保留。OQ2 已解决:分组来源与通用环境尺寸之间没有区别,因此不允许任何一种跨边界泄漏。
已拒绝:仅靠文本 CSS(无法阻止上下文成员身份);仅靠 portal(会保留 React 上下文并改变宿主);将隔离限制在当今已命名的分组(未来的呈现提供者会泄漏);重置所有后代的边框/圆角(会破坏合法的内容自有分组)。
DEC-3 — 已接受的显式表面/内容协议¶
参考: spec:AST-038/DEC-3
决策者: cixzhang,2026-09-23
历史记录(已由 DEC-4 收窄): FR8 的原始措辞要求语义/数据/交互提供者具备显式所有者协议,并单独提供布局/视觉内容上下文。它还将该规则应用于混合提供者。该措辞混淆了呈现与语义成员身份。DEC-4 移除了语义状态重置要求;它保留了现有的语义继承,并将显式内容提供收窄为视觉/布局所有权。FR9 对非等价局部样式的保留仍然适用。
DEC-4 — 仅视觉重置;行为与无障碍性不变¶
参考: spec:AST-038/DEC-4
决策者: cixzhang,2026-09-23
状态: 由 cixzhang 于 2026-09-23 批准,且仅授权合并此规范更正。该批准涵盖 DEC-1–DEC-4;下方历史性的混合提供者规则已由已批准的 DEC-5 修订。
已更正范围:仅视觉重置。精确保留 ARIA、焦点、选中状态、禁用/只读状态、回调、键盘所有权、关闭行为、语义/数据/交互上下文以及 DOM/AX 语义。视觉边界仅隔离文本、尺寸、密度、视觉分组、边框/圆角/分隔线以及作用域内的布局属性。其将视觉所有权与混合提供者分离的要求已被已批准的 DEC-5 取代。
这取代了对 DEC-2/DEC-3 的任何语义重置解释,以及早期 FR7/FR8 的证据记录。aria-disabled 的中和、新的 AX-disabled 隔离断言、语义分组角色以及纠正性 portal 托管均被排除。验证将证明视觉隔离以及行为/无障碍性保持不变;它不得创造新的 a11y 契约。FR1 的 theme-body 指标保持不变;这不是被拒绝的中性文档指标提案的复活。
已拒绝:整体清除混合上下文并在弹出层调用点重建选定的语义;更改禁用/选中状态以演示隔离;添加角色/ARIA/portal 以使样式边界成为无障碍边界;因为表面在视觉上独立就更改焦点或键盘所有权。
DEC-5 — 移除视觉上下文分离要求¶
参考: spec:AST-038/DEC-5
决策者: cixzhang,2026-09-24
状态: 由 cixzhang 于 2026-09-26 批准。
当 FR7 适用于由一个上下文承载的表面/分组成员身份时,该现有的整体值随之停止;视觉字段不会被分离。成员身份拥有的状态(包括禁用/只读状态)随之停止。无关的上下文和显式编写的 props 保持不变。这取代了 DEC-1–DEC-4 中相互冲突的分离与成员身份保留条款;所有其他范围及 FR1 基线保持不变。
未决问题¶
无。OQ1–OQ3 仍是历史性决策。已批准的 DEC-5 修订了分离视觉上下文的要求;规范批准与验证均不授权合并实现。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx