组件样式编写架构¶
{
"scope": "global",
"triggers": {
"styling": ["INV1", "INV2", "INV3", "INV4", "INV5", "INV6", "INV7"]
}
}
目的¶
Astryx 组件样式应编译为有效的受维护 CSS,与受支持的消费方样式可预测地组合,将关系状态保持在被预期组件的作用域内,并避免没有运行时职责的 DOM 包装元素。
这份记录拥有七个组件级编写结果。它不重新定义语义令牌、公共主题目标、可扩展的 prop 轴、公共样式 props、图标解析、双向性,或 React Server Component 边界。
系统模型¶
组件自有的样式始于 Core 或 Lab 组件源码,并通过仓库中受维护的 StyleX 管线编译。编写者可选择三类工作:
- CSS 可解析的呈现。 浏览器可以从 CSS 推导出视觉状态、关系、响应式条件、回退或过渡。
- 行为状态。 JavaScript 拥有 CSS 无法推导的信息或交互。组件只向 StyleX 暴露由此产生的样式输入。
- 负有职责的结构。 DOM 元素之所以存在,是因为它拥有语义、行为、ref、格式化上下文,或子元素边框盒之外的外间距——而不仅仅是为了转移样式。
被锁定的 StyleX 能力注册表决定了受维护的管线当前支持的语法和辅助函数。能力条目和 lint 匹配器是带版本号的强制执行事实,而不是永久的架构词汇。依赖能力的审查只有在注册表记录的 StyleX 版本与审计修订版中安装的包版本匹配时才可测试。不匹配则无法测试,既不证明符合也不证明违反。
边界与不变量¶
- INV1 — 组件本地样式通过 StyleX 编译。 已发布的、组件自有的样式声明使用仓库中受维护的 StyleX 编译路径。单独拥有的全局 CSS、主题编译器输出和消费方编写的样式仍归其具名所有者所有,且不在本不变量范围内。当受维护的 StyleX 路径支持相同结果时,组件本地原始 CSS 仍处于范围内。
- INV2 — CSS 拥有 CSS 可解析的呈现。 当锁定的浏览器和 StyleX 能力集可以在 CSS 中推导出视觉状态、关系、响应式条件、回退或过渡时,组件代码不通过 React 状态、Effects、观察器或动画帧记账来重新创建该呈现。JavaScript 仍然适用于 CSS 无法推导的行为或信息。
- INV3 — 声明保持有效且可静态组合。 受支持的组件 StyleX 输入可编译为有效的受维护 CSS,并保留独立的属性组合,而不需要运行时的属性移除或属性键去重语义。精确的简写、重置和 null 模式是带版本号的工具规则,而不是永久的架构词汇。
- INV4 — 关系状态是组件作用域的。 祖先、后代和兄弟样式仅对预期的组件自有关系作出反应。来自无关外部容器的状态 MUST NOT 激活内部组件的视觉状态。作用域标记是当前的机制,而不是永久的契约措辞。
- INV5 — 每个包装元素都有具名的职责。 包装元素仅在其拥有语义角色、行为或 ref、子元素无法在不改变自身契约的情况下吸收的格式化上下文,或子元素边框盒之外的外间距时存在。当子元素拥有兼容的可承载样式的 DOM 表面时,仅将样式转移给该子元素的包装元素就可以移除。当子元素没有兼容的表面时,包装元素也可以改由自己拥有该边界。仅凭源码清晰度不构成规范性职责。
-
INV6 — 组件大小被报告,且仅触控成本被纳入预算。 每个变更组件代码或样式的拉取请求都需要以 base 对照 head,报告每个变更组件的 import 所拉取的 JavaScript gzip 大小(包括其传递依赖模块),以及该组件在其包样式表中的 gzip CSS 增量(
spec:AST-080FR8)。仅在粗指针上运行且为单个组件增加超过 2 KB gzip JavaScript 或 1 KB gzip CSS 的特性会被标记。其拉取请求要么从共享的内部触控模块(architecture:react-component-runtimeINV13)中取得那部分 JavaScript——无论多少组件使用它们,页面只会加载一次——要么为该成本提供理由。被标记的组件若延迟了由交互揭示的表面(architecture:component-import-boundariesINV1),则只计算其立即加载的 JavaScript。对于被标记的 CSS,其拉取请求需要为该成本提供理由,因为该 CSS 保留在包样式表中(spec:AST-080FR1、FR8)。大小按默认压缩级别的 gzip 计算,1 KB 为 1,024 字节;按照spec:AST-080FR8 测量 CSS 的方式,组件的 JavaScript 大小是包含其 import 及该 import 所到达的每个模块的单个 bundle 的 gzip 大小。共享的 JavaScript 值表(例如手势或弹簧调校表)只向组件提供该组件使用的行:导入一个组件不会拉取只有其他组件会读取的行。该规则仅涵盖调校表:StyleX 变量组遵循spec:AST-066FR3,消息目录遵循architecture:internationalizationINV15。 -
INV7 — 组件由最小 DOM 构建。 每个组件在静止和打开状态下,都为其拥有的每个语义或交互角色渲染一个元素,为当前主题目标所绘制的每个可主题化部件渲染一个元素(
architecture:component-theming-surfaceINV4),并且只有在 INV5 指明其职责的地方才使用包装元素:语义角色(包含 ARIA 需求)、行为或 ref、格式化上下文、外间距,或子元素无法承载的样式承载边界。状态和变体通过那些元素上的属性、类和样式来表达,绝不要通过额外元素。伪元素承载没有语义角色的装饰,且绝不重复内容。内容只渲染一次:不需要用于测量或预留空间的隐藏孪生元素,因为 CSS 可以在显示内容的元素上对其进行尺寸设定和预留(INV2)。主题运行时可以在每个文档中拥有一个共享的、空的、aria-hidden 探测元素,它位于所有组件的 DOM 之外,仅用于读取平台文本大小;它不渲染任何内容,不是主题化目标,并随最后一个根 Theme 一起移除。一个层只挂载一个呈现。唯一的第二副本是以下场景中的瞬时副本:退出、呈现切换、从触发器提升(architecture:layer-runtimeINV15),或面板之间的交接,例如design:reduced-motionDR2 要求的交叉淡入淡出;AppShell 在侧边导航折叠或展开期间的旧内容包装(component:AppShellFR17);SideNav 轨道在折叠或展开期间的旧状态(component:SideNavFR6);或可重排项目被拖拽期间的一个移动预览(design:ordered-collection-reordering)。这类副本由一种 Core 机制统一创建,而不是由每个组件各自创建,并在过渡结束后的 1 秒内被移除。在该共享机制出现之前,层自身的退出、呈现切换或交接副本,或可重排集合自身的拖拽预览,属于已记录的符合性缺口,而不是例外。对组件的修改应优先移除或合并节点;任何新增元素都需要根据此不变量,用改动前后的实测元素数量来证明合理性。由此产生两个预算:- 静止状态的表面组件 — Button、IconButton、ToggleButton、Item 及其他列表行、SegmentedControl、Switch、Badge、文本及其他输入框、CheckboxInput 和单选控件:在任何指针下,都不能超出其角色、其可主题化部件以及 INV5 指明的包装元素,且不能有重复内容。指针特定的呈现是对相同元素上的属性和样式的更改;伪元素仅作为装饰代替元素。
- 打开状态的层 — Popover、BottomSheet、DropdownMenu、ContextMenu、Lightbox 和 Dialog:只挂载一个呈现,除上述瞬时副本外不得重复挂载内容;在粗指针下,打开的层拥有的元素数量最多不超过细指针下的数量(超出部分仅能来自
spec:AST-017FR60 和 DEC-29 集合规定的打开层配额)。
好的做法:当分段控件中选中标签的字体加粗变重时,仅在该标签元素上使用 CSS 即可保持分段的宽度不变;Popover 只挂载一次面板,并通过样式更改其位置和呈现形式。不好的做法:为了预留宽度而保留一份隐藏的标签副本;同时挂载一个 sheet 和一个 popover,且其中一个处于隐藏状态;仅为了承载触摸样式而添加一个包装元素。
组件只有在拉取请求中说明例外情况时才能超出预算,且须说明现有元素为何无法胜任这项工作,并给出前后测得的元素数量。每个例外都作为独立的所有者决策进行记录,记录于组件当前记录中;若组件没有记录,则记录于本记录中。无论哪种方式,例外都必须通过规范所有者的审批门槛,任何例外均不会被静默接受。元素数量是组件 story 在静止与展开状态下,分别在精细指针与粗略指针下,document.body.querySelectorAll('*').length 的计算值。
编写指南¶
以下指南有助于满足上述不变量,但不会单独产生永久的 API 或兼容性要求:
- 在添加原始 CSS 或 JavaScript 变通方案之前,请查阅
internal/stylex-capabilities/CAPABILITIES.md。优先使用受支持的 CSS 原生机制。 - 对于与方向相关的样式,使用逻辑属性和逻辑值。规范的双向性所有者决定例外情况以及可观察的 RTL 行为。
- 以当前 StyleX 版本和仓库 lint 规则所接受的形式使用长属性、回退值和显式重置值。这些被接受的确切形式可以在不改变 INV3 的前提下演进。
- 通过悬停能力来约束仅悬停可见的视觉增强,同时在交互所有者的管理下,保留可操作的键盘、点击和触摸路径。
- 当不存在语义主题角色,且该值是已命名的组件设计决策时,组件本地的几何样式可以使用字面量。主题令牌权限决定可复用的语义角色是否应属于可移植令牌词汇表。
- 组合进宿主中的次要渲染路径可以依赖该宿主的结构和样式。对于该路径,INV5 适用于 DOM 所有者,而不是要求每个分支都看起来像组件的默认渲染。
只有当指南的偏离破坏了上述不变量或其他当前所有者时,它才构成架构违规。
委派权限¶
本记录不吸收相邻的审计规则:
- 图标与内联 SVG。
architecture:icon-resolution-and-component-slots和 Icon 组件契约拥有语义字形解析的权限。当内联 SVG 重新实现了本应属于共享注册表的字形时,即为缺陷;只要组件自己拥有语义和可访问性,组件自有的非字形矢量形状仍然允许。图标作用域以及全局/主题解析的变更仍归图标和主题编写所有者负责。 - 令牌与字面量。
architecture:theme-tokens拥有可移植语义值。本记录不建立通用的字面量允许清单。 - 目标、结构与可扩展轴。
architecture:component-theming-surface拥有目标准入、绘制结构、继承/委派、反扩散、保证属性,以及哪些视觉轴可被主题扩展的权限。 - 公共样式与 DOM 契约。
architecture:public-component-api拥有BaseProps、xstyle、className、style、ref 可达性,以及针对无根、拥有 SVG、提供者、覆盖层或其他非 DOM 所有者的组件的例外情况。 - 双向性。 另一个当前的 RTL/方向性所有者必须定义通用的逻辑方向结果。物理属性的 lint 和辅助语法是执行证据,而非本记录所提供的权限。
- React 模块边界。 另一个当前的 RSC/模块边界所有者必须定义客户端入口点、指令放置、混合/服务端安全桶、构建输出保留以及 RSC 可用导出。本记录不会将
'use client'的放置变成样式策略。 公共导入会急切到达哪些模块,包括通过交互和可选功能揭示的面,由architecture:component-import-boundaries负责。
审计行路由¶
本记录为以下内容提供共享权限:
- Q6 / T14: 通过 INV5 界定包装责任,通过 INV7 界定最小化构建;
- 通过 INV3 实现 Q7 背后的持久可组合性结果;
- T8: 通过 INV1–INV2 界定组件本地 StyleX 降级与 CSS-over-JS 所有权;
- 通过 INV3 实现 T9 背后的有效降级结果;
- T10: 通过 INV2 界定 CSS-over-JS 所有权;以及
- T11: 通过 INV4 界定关系状态隔离。
其他预期行仍归现有或未来的所有者:
- Q4 / T17: 图标架构与 Icon 组件契约;
- T2b: 主题令牌架构;字面量示例仍属审计指南;
- T13: 未来的当前双向性所有者以及 lint 执行;
- T18: 图标解析/作用域与主题编写规范化;
- T19: component-theming-surface 轴准入以及公共 API 可达性;
- T20: public-component-api 及其 BaseProps 执行;
- T27: component-theming-surface;数值目标计数区间仍属审计启发式;以及
- T30: 未来的当前 RSC/模块边界所有者。
变更耦合¶
当组件变更添加或修改以下内容时,触发聚焦式样式编写审查:
- 原始/全局样式表,或组件本地非 StyleX 样式路径;
- 仅用于实现呈现性 CSS 可自行推导之效果的 JavaScript 状态、Effect、观察器或动画帧;
- 固定能力集之外的 StyleX 构造;
- 可能阻止消费者独立组合属性的简写/重置/空(null)行为;
- 祖先、后代或兄弟元素的视觉状态;
- 围绕单个组件或单个视觉子元素的 DOM 包装,或任何新增的元素、伪元素或挂载的呈现物(INV7);
- 组件自有的、可能表示共享语义字形的内联 SVG;或
- 仅在粗略指针下运行的代码或样式,或组件所读取的共享值表(INV6)。
评审检查此处拥有的不变量,并在作出裁决之前遵循上述委派的权限。
所属代码¶
packages/core/src/和packages/lab/src/— 组件所拥有的 StyleX 声明和渲染结构。internal/stylex-capabilities/— 版本化的 StyleX 能力事实与扫描。internal/eslint-plugin-astryx/— 当前编写模式的强制约束;lint 实现本身并不定义永久架构。
决策规范¶
spec:AST-080/DEC-4— 每个拉取请求都会报告组件的 JavaScript 和 CSS 大小;仅用于触摸的 JavaScript 超过 2 KB 或仅用于触摸的 CSS 超过 1 KB 会被标记,且共享值表只包含组件使用的行(INV6)。spec:AST-080/DEC-5— 触摸原语来自共享的内部触摸模块,或者其成本合理性已得到说明;任何组件都不得自行懒加载(INV6)。spec:AST-017/DEC-26— 组件由最小化 DOM 构建,设有两个预算和一个由所有者记录的例外路径;减少 DOM 是兼容的(INV7)。
图标、主题令牌、组件主题、公共 API、双向性以及 RSC 的所有者保留上述委派的决策。
验证¶
| 不变量 | 证据 | 失败信号 |
|---|---|---|
| INV1 | StyleX 能力扫描与组件源码变更 | 已发布的组件样式在没有其他具名所有者的情况下绕过了受维护的降级路径,包括在该路径也能产生相同结果时使用组件本地原始 CSS |
| INV2 | 等效的 CSS/JS 变更测试夹具和真实浏览器中的呈现 | JavaScript 重新创建了可由 CSS 解决的呈现、闪现中间状态,或与 CSS 条件不一致 |
| INV3 | StyleX 编译测试夹具和独立的消费者属性覆盖变更 | 输入降级为无效 CSS,或者更改一个受支持的属性时,无法在不移除另一个属性的情况下组合 |
| INV4 | 嵌套的无关联所有者的浏览器测试夹具,覆盖 hover、focus-within、active 和 disabled 状态 | 外部组件的状态激活了内部组件的视觉处理 |
| INV5 | 默认与宿主组合渲染路径中的包装器变更 | 移除包装器不会改变任何语义、行为/ref、格式化上下文、外部边框间距或承载所需样式的 DOM 边界 |
| INV6 | 对 base 的拉取请求体积报告,附带值表导入夹具 | 变更的组件没有 base 对 head 的 gzip JavaScript 或 CSS 数据;仅触及型(touch-only)特性超过每组件 2 KB gzip JavaScript 或 1 KB gzip CSS 却未被标记;导入组件时拉取了仅其他组件会读取的值表行 |
| INV7 | Story 元素数量(document.body.querySelectorAll('*').length)在静止与展开状态、精确指针与粗指针下,以 base 对 head 对比,并检查渲染结果是否包含重复内容 |
超出组件角色、可主题化部件和 INV5 包装器范围的元素,或内容出现重复或隐藏的孪生元素;状态或变体被渲染为额外元素;伪元素使内容重复出现;在瞬态副本之外挂载了具有两种呈现的层,内容被挂载两次,粗指针下的元素数量多于精确指针且超出 spec:AST-017 FR60 的允许范围,组件自身创建的瞬态副本,或超过 1 秒仍未移除的副本;新增元素没有测量计数,或预算超限却没有记录归属者豁免;出现第二个重排预览,或拖放后仍残留的预览 |
| INV7 (probe) | dynamicType.test.ts 共享探针、清理与能力门控用例;Theme.test.tsx 嵌套 Theme 和无能力用例 |
文档中存在多个探针;嵌套 Theme 创建的探针;最后一个根 Theme 卸载后仍残留的探针;引擎没有 font: -apple-system-body 时出现的探针 |
| Capability registry | 依据已安装的 StyleX 包生成注册表 | 记录的 StyleX 版本与已安装的 StyleX 版本不一致,导致依赖能力的用例无法测试 |
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx