跳转至

Theme family build behavior spec

意图

主题包作者应能编译一个相关的主题族,而无需发布每个成员重复的已解析声明。调用方选择该族并提供一个稳定的键。构建会生成一个包含所有成员的 <key>.css、一个导出每个完整成员的 <key>.js,以及一个匹配的 <key>.d.ts。消费者只需加载一次 CSS,并按身份标识切换主题。

公开的 PR #5687 展示了用户需求及所需的级联结果。其分别加载的基础文件和成员文件不是可接受的输出:它们可能不完整、依赖加载顺序、遗漏零增量成员,并且在源绑定冲突时产生无效的 JavaScript。替代方案使用一个聚合输出三元组,使消费者永远无需自行组装该族。

非目标

  • 在本规范拉取请求中实现编译器、CLI 或生成的构件。
  • 添加新命令、错误码、或按成员划分的族入口点,或除回执的 base(FR2)之外的任何响应字段。
  • 加强现有主题构建的文件系统失败、清理或发布保证。
  • 添加或更改可移植/全局令牌词汇、组件 API 或主题值。

要求

输入与输出

  • FR1 — 所选主题构成一条有效谱系。 所选主题必须构成一棵连通的、无环的 extends 树,且恰好有一个根。每个所选非根成员的父级也必须被选中。根可以扩展该族未选中的主题:其 CSS、导出和声明会像根独立构建时一样携带该基础,并且模块会导入一个包基础,用于根从该基础继承的注册表。该包是必需项:当它未安装,或未导出根所导入的基础时,构建会失败并指明该包和主题,且绝不会在缺少该基础的情况下构建根。该基础就是根自身的 extends 所指定的那个,其来源可追溯:来自包的导入即为包基础;来自项目文件的导入,或根自身文件定义的主题,即为本地基础。提供注册表的本地根基础会被拒绝,并会指明需要选择的基础。重复的名称或身份、缺失的祖先以及循环,必须在族输出发布前失败;缺失的祖先会被命名,并同时指明以其为基础的成员。任意深度的后代均有效;一个族不限于一个根及其直接子级。
  • FR2 — CLI 生成一个调用方键控的输出三元组。 稳定的命令形式为:
astryx theme build --family <base> <children...> --family-key <key>

--family-key <key> 在配合 --family 使用时是必需的;在写入任何输出之前,若缺少它则命令会被拒绝。它仅命名 <key>.css、<key>.js 和 <key>.d.ts。族键只是文件名主干:它不会改变成员的身份标识或序列化的 data.name,也不会建立第二种输出目录约定。该键使用现有的安全小写连字符(kebab-case)文件名规则。族模式可与 --check 组合使用,但拒绝与 --watch 和 --out 一同使用;其他选项保留所属构建的现有语义。它不添加错误码。其回执仅在根扩展了该族未选中的主题时添加一个字段 base({theme, package, export});package 指明基础来源的已安装包(这是输出的要求),对于本地基础(FR1)则为 null;export 是根导入该基础所使用的名称,对于根自身文件定义的主题则为 null。任何其他响应变更遵循 spec:AST-017。

可观察的族行为

  • FR3 — 一个样式表对每个成员都是完整的。 <key>.css 必须包含每个所选成员所需的全部由主题编写的 CSS。对于每个成员,每个生成的声明及由此产生的计算样式,必须在所有受支持的主题表面上与该成员完整的独立构建相匹配。完整性遵循 spec:AST-066:成员仅贡献其显式编写的 --color-data-* 覆盖;规范默认值来自消费方的 StyleX 数据变量组,位于主题构建之外。消费者不得加载、排序或发现另一个族样式表。
  • FR4 — 主题身份标识选择正确的级联。 在 <key>.css 加载后,选择或切换成员只需更改主题身份标识。后代的不同值必须胜过继承值,无需消费者进行特异性处理,也不依赖样式表顺序。嵌套根遵循 spec:AST-066:相同和不同的身份标识都会继承所有未指定的数据值,而子级仅替换其显式编写的子集。兄弟根保持隔离;不相关的同层样式表,无论物理顺序如何,都会产生相同的胜出者。
  • FR5 — 确定性输出保留零增量成员。 等效的所选集合必须产生字节完全相同的 CSS、JavaScript 和声明,无论参数顺序如何。没有视觉增量的成员仍具有其可选择的身份标识、完整的 JavaScript 导出和声明。
  • FR6 — JavaScript 和类型暴露每个完整成员。 <key>.js 必须是一个不含 CSS 的标准 ESM 模块,为每个所选成员提供一个完整的已解析导出。当不同的主题源复用相同的本地绑定名称时,它必须能够被解析和导入。<key>.d.ts 必须在支持的 TypeScript 模块解析方式下描述每个成员导出。CSS、JavaScript 和类型的就绪状态保持相互独立。

失败、检查与兼容性

  • FR7 — 成功意味着一个完整的键控结果。 无效的谱系、键或成员必须在命令报告成功之前失败。成功的构建必须展示全部三个预期的键控文件,且字节为最新。失败的构建不得对混合、缺失或过期的预期集合报告成功。这并未定义比现有主题构建更强的持久性保证。
  • FR8 — --check 验证预期的键控输出。 在相同的族选择和键下,--check 必须重新生成预期的 CSS、JavaScript 和声明输出,并使用现有的主题构建检查语义比较这三个文件。它必须报告缺失或过期的预期文件,且不写入生成的输出。此契约不增加对无关或多余文件的检测或清理。
  • FR9 — 现有命令和构件路径保持兼容。 独立命令和普通的多文件命令、输出名称、生成的 JavaScript/类型、主题名称、继承关系以及消费者导入路径都保持其原有含义。spec:AST-066 有意从每种主题构建模式中移除规范数据默认值,仅保留编写的限定作用域数据覆盖;族模式不得保留已被取代的原始全局数据块。族选择本身仍然保持可选启用。

证据与替代实施的关系

  • FR10 — PR #5687 是证据,而非替代实施。 其重复度量、谱系证据和级联实验可为替代工作提供参考。其公开的“基础加成员”消费模型已被取代。替代方案 MUST 通过一个聚合的 CSS/JS/d.ts 输出,满足上述完整性、加载顺序、零增量和绑定安全性行为。

当前状态影响

当前 main 为每个主题构建一套完整的 CSS、JavaScript 和声明集。实施本已接受修订案将增加上述可选家族命令行为。spec:AST-066 另行从独立版和家族版主题 CSS 中移除规范数据默认值,仅保留每位成员编写的限定作用域数据覆盖,并将规范默认值发射指派给公开的 StyleX 消费者图。它不改变键控三元组、成员导出、声明或选择命令。

本规范本身不改变任何运行时、编译器、CLI、生成产物或包,也不新增 Changeset。

验证

契约 所需证据 失败信号
FR1–FR2 图与 CLI 组合测试 缺少祖先或出现循环构建;键改变身份;家族模式发射了键控三元组以外的内容
FR3–FR5 独立等价性测试夹具及真实 Chromium 组件、散文、适配、媒体行为、编写的受限数据子集、嵌套相同/不同身份、兄弟根、逆序或零增量状态存在差异;实参顺序改变字节
FR6 ESM 解析/导入、TypeScript 和绑定冲突测试夹具 导出不完整或缺失;复用的局部名称破坏解析;声明与导出不一致
FR7–FR9 无效输入、写入失败、检查及独立回归测试夹具 无效输入报告成功;成功构建暴露混合、缺失或过期字节;检查对其误报通过;独立输出在 spec:AST-066 数据默认值移除之外发生变化

真实浏览器验证 MUST 仅加载 <key>.css,外加普通消费者 StyleX 输出,并演练每个选定身份、代表性组件与散文、媒体行为、每位成员编写的受限数据子集、跨嵌套相同与不同身份的父级编写数据覆盖、兄弟根、零增量成员,以及两种顺序下的无关同层样式表。结构测试 MUST 证明字节确定性、家族 CSS 中零规范数据默认值、完整 ESM 导出、匹配类型及冲突安全导入。现有独立测试夹具 MUST 在 spec:AST-066 之外保留所有行为。

完成标准

本规范保持 accepted 状态,直至一个替代实施证明:

  • 为直接与嵌套后代生成一个确定性的键控 CSS/JS/d.ts 三元组;
  • 单一样式表即可提供完整的独立等价主题行为,包括 spec:AST-066 编写的稀疏数据覆盖、零规范默认值及嵌套继承;
  • 可选择的零增量成员与冲突安全的聚合 JavaScript/类型;
  • 构建与 --check 无法对混合、缺失或过期的预期键控文件报告成功;以及
  • 真实 Chromium 行为及独立构建在 spec:AST-066 规范数据默认值移除之外保持不变。

决策日志

修订案 — 采用 StyleX 数据令牌所有权

决策者: cixzhang,2026-10-01

spec:AST-066 改变了用于衡量家族成员的独立行为:规范数据默认值来自一个保留的公开 StyleX 变量组,而每个主题身份仅发射其编写的受限数据子集。本修订案更新了 FR3、FR4、FR9、验证及 DEC-2,且不改变家族命令、键控输出三元组、图契约或完整成员原则。

修订案 — 将规范保持在可观测边界

决策者: cixzhang,2026-09-12

已接受的 2026-09-11 文本将家族输出契约与另一套内部架构耦合在一起。本修订案将该设计从行为契约中移除。此前任何家族专属内部架构要求均不再有效;仅以本修订记录中的可观测要求为准。

本修订案保留单文件家族结果、确定性顺序、嵌套谱系、零增量身份、完整聚合导出、绑定安全性、正确级联及真实浏览器证明。

DEC-1 — 发射一个键控家族输出三元组

参考: spec:AST-034/DEC-1 决策者: cixzhang,2026-09-11;修订于 2026-09-12

家族命令发射 <key>.css、<key>.js 和 <key>.d.ts。CSS 包含所有成员,ESM 导出每个完整成员,声明描述这些导出。必需的 --family-key 仅更改文件名。逐成员家族输出与消费者运行时组装被拒绝,因为它们将图与加载顺序工作交还给消费者。

DEC-2 — 在单一样式表中保留完整成员行为

参考: spec:AST-034/DEC-2 决策者: cixzhang,2026-09-11;修订于 2026-09-12

每个选定身份产生的可观测主题 CSS 行为与其完整独立构建相同。后代差异优先,无需消费者管理的加载顺序或特异性提升,包括组件、散文、适配及媒体行为。在 spec:AST-066 下,规范数据默认值来自保留的公开 StyleX 组;相同与不同嵌套身份继承每个未指定值,并仅覆盖其编写的受限子集。家族 CSS 不含规范数据默认值。

待解决问题

无。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx