跳转至

主题所有权、继承与物化系统规范

意图

主题作者需要知道某个主题是遵循另一个主题,还是仅仅将其作为起点。defineTheme({extends}) 有意保留对已解析基础主题的源依赖。当作者希望获得来自基础主题的修复、新的组件覆盖范围和其他更新时,这很有用;但依赖升级时,它也可能会改变子主题。

因此,Astryx 应支持两种明确的工作流:

  • 跟随: 保留 extends 并持续采用基础主题中的变更。
  • 自有: 将当前的编写输入解析为可审查的本地源代码,该源代码不再依赖于所选基础主题或可变的生成公式。

物化是生成完整自有快照背后的共享技术操作。它会解析继承的和生成的主题编写值,预览确切变更,并且仅通过单独的显式写入调用来写入等效的本地主题,而不是通过提示或从 stdin 读取。

非目标

  • 改变 defineTheme({extends}) 当前的含义或优先级。
  • 在本规范的拉取请求中移除 extends、排版、动效、圆角或颜色配置。
  • 定义色调调色板生成、可接受的调色板校验、语义颜色建议或上下文对比度分析。
  • 定义作者如何在 Astryx 内置刻度之外创建新的排版、间距、动效或圆角值。主题本地刻度扩展由独立的 AST-023 提案负责。
  • 承诺快照在 Astryx 包升级后冻结组件实现。它冻结的是主题编写输入,而不是消费这些输入的库代码。
  • 将任意的可执行 React 节点或函数序列化为普通数据。
  • 在没有作者可见的预览和明确的写入决策的情况下更新、覆盖或分离主题。

术语

  • 跟随主题: 具有 extends 关系的源代码。重新解析它可能会采用所选基础主题中的变更。
  • 完整自有快照: 包含公共主题编写契约所公开的每个已解析值的本地主题源代码。重现它不需要所选基础主题或可变的刻度生成行为。
  • 物化: 将继承的和生成的编写输入解析为显式、可审查的本地源代码。
  • 分离: 物化一个跟随主题并移除其 extends 关系。
  • 冻结: 物化选定的生成刻度,同时保留任何预期的继承关系。
  • 谱系绑定本地令牌: 一个主题本地名称,其声明和使用仅通过拥有它的已登记精确 extends 谱系有效。
  • 未解析的可执行值: 继承的图标、指示器、语法定义或其他工具无法安全地表示为生成源代码的值。

所有权

所有者 契约
AST-022 跟随与自有的选择、物化行为、预览、写入和等价性证据。
主题作者 所选生命周期、已提交输出、保留的依赖项和接受的视觉变更。
defineTheme 架构 当前的规范化、优先级、继承和支持的编写表面。
CLI 编写表面 发现、预览、源代码生成、回执、安全写入和可操作的失败。
调色板规范 调色板生成、可接受的调色板所有权和精确的调色板引用行为。

选择生命周期

该选择控制未来主题变更由谁负责。两种选项都不是普遍更好,因此编写工具必须在写入前解释两者。

选择 优势 权衡 最适合
使用 extends 跟随基础主题 源代码更小;接收来自基础主题的已审查修复、新的主题覆盖范围和协调更新;方便实现相关变体。 升级基础主题可能会改变子主题;审查者必须考虑继承的变更;重现源代码需要基础依赖。 有意与另一个主题保持一致的变体,尤其是当两者一起维护时。
获取完整自有快照 每个公共主题值都是显式且可在本地审查的;基础主题和 Core 默认值变更不会改变已保存的值;作者可以自由分叉。 源代码更大;作者需要维护复制的值;来自原基础主题的后续修复和新覆盖范围不会自动被采用。 优先考虑控制和视觉稳定性的产品或应用主题。
分离现有主题 保留主题当前已解析的值、名称和导入,同时结束之前选择的基础关系。 产生更大的待审查变更;未来的基础改进需要显式比较和采用。 作者后来决定拥有其当前外观的跟随主题。
冻结所选生成器 使所选生成值显式化,而无需完全分离。 保留的 base 和生成器依赖仍可能改变其他值;结果是部分物化,而非完全所有权。 适合希望控制某个尺度、同时有意在其他方面继续跟随 base 的主题。

CLI MUST 用这些术语描述所选结果。它 MUST NOT 将“self-contained”“detached”或“fully owned”用于仍然依赖未报告的 base 或可变生成器的输出。

要求

显式生命周期选择

  • FR1 — 跟随(following)与拥有(owning)是不同的承诺。 工具从现有主题创建新主题时,MUST 将跟随 base 和取得完全自有的起点作为显式选择提供给用户。它 MUST 说明跟随会接收后续的 base 变更,而自有则接受本地维护,并且 MUST 要求在写入前通过显式选项选择其一。当该选项缺失时,CLI MUST 返回可用选项,不写入文件也不读取 stdin。工具 MAY 根据作者陈述的目标推荐一种选择,但 MUST NOT 静默选择它,也不得将 extends 描述为完全独立的副本。
  • FR2 — 跟随保留当前 extends 语义。 跟随主题保留其 base 依赖,并且可在有意的依赖更新后采用 base 已解析的 token、组件、媒体表面、图标、指示器、语法和本地 token 变更。生成的 DefinedTheme 仍会被扁平化以供消费,但运行时或构建时的扁平化 MUST NOT 被描述为源代码独立性。
  • FR3 — 自有起点写入本地源码。 仅将 base 作为起点选择时,MUST 创建完全自有的快照。后续对所选 base 或 Core 主题默认值的更改 MUST NOT 改变其已保存的主题值,除非作者显式运行迁移或比较工作流。

物化边界

  • FR4 — 物化涵盖可配置的主题表面。 该操作 MUST 考虑继承值以及由当前排版、动效、圆角和颜色配置生成的值。它 MUST 保留显式 token 和显式组件的优先级。它 MUST 还盘点本地 token、onDark、onLight、语法、图标和指示器,而不是静默丢弃它们。
  • FR4a — Detach 无法原样复制绑定于谱系的本地 token。 在移除 extends 之前,工具 MUST 检查继承的本地 token 声明、所有者元数据和每个可达引用。继承的名称仅在其精确注册的 base 谱系内有效;将该名称复制到分离后的主题中会使其成为外来声明,并通过当前校验器失败。因此,Detach MUST 在写入前停止,并要求在拥有方主题规范下审查显式的本地 token 迁移。该迁移 MUST 将受影响的名称映射到分离后主题的命名空间,重写每个可达的声明和引用,并保留已发布 token 合约所需的任何兼容别名。如果作者没有选择此类迁移,工具 MUST 保留 extends,报告谱系依赖,并且 MUST NOT 将结果描述为分离或完全自有。
  • FR5 — 物化生成可供创作的源码,而不仅是编译输出。 仅凭 CSS 或 JavaScript 构建产物是不够的,因为它不能为作者提供可编辑的主题定义。输出 MUST 适合使用受支持的主题工具链进行提交、审查和重建。
  • FR5a — 完全所有权包括所有已解析的公共主题值。 完全自有的快照 MUST 写入公共主题创作合约公开的每个值,包括当前等于 Core 默认值的值。仅记录差异的输出仍依赖未来的 Core 默认值,因此 MUST NOT 被标记为完全自有。
  • FR5b — 创作投影与运行时表示分离。 物化 MAY 生成更大、完全显式的源码投影,以便作者读取、编辑、审查和重建每个已解析值。该投影本身 MUST NOT 强制所发布主题携带相同扩展数据。
  • FR5c — 预览显示大小权衡。 写入前,预览 MUST 显示源码投影和等效的编译/运行时输出,包括与当前主题相比所产生的 CSS、JavaScript 和包体积影响。当所选所有权选择会增加运行时成本时,检查或编辑已解析视图 MUST NOT 被描述为无运行时成本。
  • FR5d — 收据和创作元数据不进入运行时产物。 收据、来源信息、比较证据和仅创作元数据 MUST 保留在 sidecar 或开发输出中,并且 MUST NOT 打包到运行时 CSS、JavaScript 或包导出中。等效的运行时输出 MUST 保留现有紧凑表示,或使用等效的去重形式。Detach MAY 仅在作为显式、已预览的所有权权衡时接受实际体积增加。
  • FR6 — 主题所有权有诚实的边界。 物化冻结可通过当前公共创作合约表达的主题值。它 MUST 说明所使用的 Astryx 版本,并且 MUST NOT 声称冻结内部组件标记、主题合约之外的默认样式、浏览器渲染或未来包行为。
  • FR7 — 主题拥有的调色板引用保持自有。 对同一主题已提交调色板文件中精确值的引用默认仍为引用;无需替换为复制的十六进制值。当调色板属于另一个包时,工具 MUST 要求通过显式选项选择保留该可见依赖,或将当前值复制到本地。

可执行值与失败行为

  • FR8 — 可执行值需要保留源码的处理。 生成的源代码 只有在作者有意保留并报告该依赖时,MAY 通过显式导入来保留图标、指示符、语法定义或其他可执行值。 完全拥有的快照 MUST 将继承自所选基础主题的值替换为等效的本地自有源代码,或替换为不导入原基础主题的作者提供的本地引用。 当工具无法安全构建或验证该源代码时,操作 MUST 报告具体字段并在写入前停止。 如果作者改为保留基础主题导入,则预览和回执 MUST 报告这一点,且结果 MUST NOT 被标记为完全拥有或独立于来源。 工具 MUST NOT 将可执行值字符串化、省略或替换为占位符。
  • FR9 — 写入是原子性的且由作者主动选择。 预览是默认行为。写入需要显式的作者动作,使用临时目的地,验证完整结果,并且仅在成功后替换目标文件。没有单独的显式覆盖选项时,MUST NOT 覆盖现有已修改的输出。Detach 会通过添加其解析值并移除 extends 来更新所选现有主题;它不会创建第二个主题,也不需要调用方更改导入。
  • FR10 — 部分物化是显式的。 作者 MAY 只冻结选定的生成刻度,同时继续跟随基础主题。预览和回执 MUST 标识每个保留的依赖。部分操作 MUST NOT 被标记为已分离或已拥有。

等价性与审查

  • FR11 — 前后解析结果等价。 成功的完整物化 MUST 在相同 Astryx 版本下比较原主题与提议主题。Token、组件覆盖、media-surface 覆盖、本地 Token 声明、本地 Token 所有者和谱系元数据以及注册表选择 MUST 匹配。存在差异时会阻止写入,除非作者显式选择记录预期变更的单独迁移。对于本地 Token 迁移,等价性证据 MUST 额外显示旧到新的名称映射、每个重写的引用、应用该映射后等价的解析行为,以及任何必需的兼容别名。编译后的差异 MUST 仅限于记录的改名和别名,并包含在预览和大小比较中;未说明的外部或未声明名称阻止写入。
  • FR12 — 预览说明后果。 在写入之前,工具 MUST 显示已移除的基础主题或生成器依赖、将要创建或更改的文件、未解析的可执行值、保留的依赖以及精确的语义摘要。视觉比较 MAY 补充此证据,但 MUST NOT 替代结构比较。
  • FR13 — 每次写入都有回执。 回执 MUST 包含工具和 Astryx 版本、源主题标识、原始基础主题标识和版本(如适用)、所选操作和表面、输入与输出摘要、保留的依赖、生成的文件路径以及验证结果。它 MUST NOT 在运行时被要求。
  • FR14 — 重复输出是稳定的。 在相同的源、版本、选项和环境无关输入下,物化 MUST 生成逐字节相同的文件和回执,除非明确排除调用时间。
  • FR14a — 未来比较是只读的。 完全拥有的快照 MAY 之后使用回执元数据与其原基础主题的较新版本进行比较。该比较 MUST 被显式请求,MUST 显示提议的结构和视觉差异,并且 MUST NOT 更新自有源代码或自动重建继承。

兼容性与迁移

  • FR15 — 在迁移方案存在之前,现有便捷 API 保持稳定。 现有 defineTheme 排版、动效、圆角或颜色配置背后的实现 MUST NOT 静默采用不兼容的生成行为。版本控制、弃用或替换需要先有受支持的比较和物化路径。在受支持的调色板生成器、显式映射工作流、视觉比较、迁移命令、文档和兼容性测试夹具可用之前,defineTheme({color}) MUST NOT 被标记为已弃用。移除需要后续的破坏性发布。
  • FR16 — 旧版颜色迁移是显式的。 将 defineTheme({color}) 迁移到作者拥有的色调调色板 MUST 使用当前受支持的调色板生成器,生成可审查的调色板和令牌映射,并呈现由此产生的视觉和结构差异。它 MUST NOT 在未更改的源码下将旧版 HCT 实现替换为新配方。
  • FR17 — 生命周期命令使用平实的语言。 CLI MAY 暴露不同的 detach 和 freeze 命令,或采用另一套经过评审的措辞。帮助和输出 MUST 以“跟随更新”与“拥有快照”的方式来解释结果。命令 MUST 保持非交互:选择和写入批准使用显式选项或单独的预览与写入调用,绝不使用提示或 stdin。仅使用内部术语 materialize 不足以指导用户。
  • FR18 — 当前调色板相关工作不受阻碍。 AST-022 管辖后续的生命周期工具。它 MUST NOT 延迟保留当前 defineTheme 边界的已接受调色板、调色板生成、验证或主题采用工作。

建议的作者流程

启动主题

Choose Neutral as a base
            |
            +-- Follow Neutral
            |      Keep extends; receive reviewed Neutral changes on upgrade
            |
            +-- Use as a starting point
                   Generate owned local source; no Neutral theme dependency

变更现有主题

Inspect dependencies
        |
        +-- Detach from a base
        |      Inspect inherited local-token lineage
        |      Migrate lineage-bound names or stop
        |      Resolve inheritance and remove extends
        |
        +-- Freeze generated values
               Replace selected scale config with explicit local values

Preview -> verify equivalence -> explicit write invocation -> atomic write -> receipt

确切的命令名称仍是实现层面的决策。一种可能的分法是 astryx theme detach 用于处理继承,astryx theme freeze 用于处理生成的刻度(scales),两者都由同一个物化引擎支撑。

当前状态影响

目前,defineTheme({extends}) 会将基础主题正确扁平化为解析后的 DefinedTheme,从而使运行时和静态构建能够消费一个自包含的结果。然而,源作者仍然保留着对导入的基础主题的依赖。更新该包并重新构建,可能会改变继承的主题值。

排版(Typography)、动效(motion)、圆角(radius)和旧版颜色辅助函数也会在规范化过程中生成值。它们的简洁意图很有用,并且仍然受支持,但在源不变的情况下更改公式可能会改变输出。本规范不引入此类更改。它定义了未来的逃生舱口,让作者可以保留简洁配置,或有意地冻结当前结果。

CLI 拥有主题模板和构建输出,但目前并未提供一种通用操作来移除 extends、展开所有受支持的生成刻度、保留源级注册表引用,并验证等价的作者源。该实现遵循此提议的契约。在内置刻度之外创建新值属于相关的作者工作,但由 AST-023 独立规定。

验证

契约 验证 代表性失败情形
FR1–FR3 针对跟随(follow)与自有起点(owned-start)选择的 CLI 选项和源输出夹具 缺失选择时提示或写入;复制的主题仍导入其选定的基础主题;或跟随主题被描述为独立的。
FR4–FR7 覆盖生成器、继承、局部令牌、媒体表面和调色板引用的全表面夹具 受支持的表面消失、优先级改变,或主题自有的调色板引用被无谓地切断。
FR4a 带继承声明和引用的 Neutral 派生分离夹具,包含或不包含显式的局部令牌迁移 extends 被移除而 Neutral 拥有的名称仍属外部;或操作声称拥有所有权,却保留了未报告的谱系依赖。
FR5b–FR5d 源/运行时投影夹具、编译体积比较和工件边界检查 查看解析后的主题会膨胀运行时输出,或收据和作者元数据被发送给消费者。
FR8–FR10 可执行注册表所有权和基础升级夹具、覆盖、部分冻结和注入失败测试 先前的基础升级后,自有的图标发生变化;导入依赖被隐藏;目标被部分覆盖;或保留的继承被隐藏。
FR11–FR14 规范化主题等价性、确定性快照、收据模式和预览测试 前后静默不同;相同运行之间输出变化;或收据遗漏依赖。
FR15–FR18 兼容性夹具和旧版颜色迁移比较 未更改的便捷配置渲染不同;迁移隐藏了颜色差异;或生命周期工作阻塞了调色板基础。

完成标准

仅当以下条件全部满足时,本规范才会从 proposed 变为 shipped:

  • 主题创建提供显式的跟随与自有起点选择;
  • 受支持的分离/冻结表面已记录文档,并带有非破坏性默认值;
  • 完整和部分物化涵盖当前每个 DefineThemeInput 表面;
  • 分离夹具证明:绑定谱系的局部令牌要么接受显式、验证过的迁移,要么在任何写入之前阻止 extends 的移除;
  • 作者投影与紧凑的运行时工件分开,预览显示源以及编译/包体积的后果;
  • 不可表示的可执行值在写入前失败,并附带可操作的指导;
  • 当先前的基础升级时,完全自有的可执行注册表夹具保持不变;同时,有意保留的导入被报告为依赖,并阻止“完全自有”的主张;
  • 在一个固定的 Astryx 版本下测试前后结构等价性;
  • 生成的源和收据是确定性的;
  • 旧版颜色迁移使用受支持的调色板生成器,且不静默改变现有 defineTheme({color}) 行为;以及
  • 消费者指南清楚地区分主题源所有权与冻结 Astryx 组件库本身。

开放问题

  • CLI 应该暴露 detach、freeze 还是两者? Detach 移除基础主题关系;freeze 将选定的生成刻度转换为显式值。它们使用相同的物化引擎,但传达不同的结果。是单个引导命令更清晰,还是分离的动词让后果更安全?
  • 大型组件映射应如何表示? 单个生成的主题文件易于导入但难以审查。将令牌、组件覆盖、媒体表面和注册表拆分为确定性模块更清晰,但会产生更多文件。哪种源形态最能平衡可审查性与忠实重建?
  • 什么算作等价? 一个调色板引用及其当前十六进制值今天可能渲染相同,但未来行为不同。calc() 表达式及其当前计算结果也是如此。等价性是否应要求相同的作者意图、相同的规范化主题数据、相同的编译输出,或一个文档化的组合?

决策日志

DEC-1 — 让作者显式选择遵循还是自有

参考: spec:AST-022/DEC-1 决策者: rubyycheung, 2026-09-04

无论主题的继承选择如何,调色板仍由其主题自有。主题作者可能合理地倾向于独立的来源,或继续接收基础主题的更新,因此工具会说明这两种后果,并要求作者做出选择。它可以根据所述目标推荐某个选项,但不会默默代替作者选择。

DEC-2 — 使用同一物化引擎处理继承与生成的标度

参考: spec:AST-022/DEC-2 决策者: 待定

基础主题脱离与标度冻结都将已解析的创作行为转换为显式源。即使 CLI 使用不同的面向用户的动词,单一引擎也能提供一致的预览、等价性、写入和收据保证。

DEC-3 — 在迁移可审查之前保留现有生成器行为

参考: spec:AST-022/DEC-3 决策者: rubyycheung, 2026-09-04

在主题源保持不变的情况下替换其背后的公式,会破坏视觉兼容性。在作者能够显式地比较、物化并接受替换之前,现有辅助工具保持稳定。

DEC-4 — 将继承的可执行值转为自有,或报告保留的依赖

参考: spec:AST-022/DEC-4 决策者: rubyycheung, 2026-09-04

稳定的图标、指示器和语法导入仅对作者有意保留的依赖保持显式。完全自有的快照不能从其先前的基础主题导入可执行值,因为之后的基础主题升级可能会改变该值。工具改为写入等价的、自有的本地源,或要求作者在后续调用时提供本地引用。保留基础主题导入会被视为已报告的依赖,并使结果不能被描述为完全自有。

DEC-5 — 保留本地自有的调色板引用

参考: spec:AST-022/DEC-5 决策者: rubyycheung, 2026-09-04

对同一主题已提交调色板的引用会维持一个自有的唯一事实来源,并默认保持为引用。外部调色板依赖需要显式的保留或复制选择。

DEC-6 — 仅在请求时比较将来的基础主题

参考: spec:AST-022/DEC-6 决策者: rubyycheung, 2026-09-04

收据保留先前基础主题的身份和版本,以便作者日后请求比较。比较不会更新主题,也不会重新创建继承关系。

DEC-7 — Detach 更新现有主题

参考: spec:AST-022/DEC-7 决策者: rubyycheung, 2026-09-04

Detach 仅作为退出先前选择的 extends 关系的途径存在。它会将已解析的值添加到所选主题,并移除 extends,同时保留主题名称和调用方的导入。版本控制和必需的预览提供前后对比;该操作不会创建第二个主题。

DEC-8 — 完全自有涵盖每个公共主题值

参考: spec:AST-022/DEC-8 决策者: rubyycheung, 2026-09-04

仅包含差异的文件仍会继承未指定的 Core 默认值,因此并非完全自有。完全自有的快照包含通过公共主题创作契约可获得的每一个已解析值,即使该输出更大。

DEC-9 — Detach 需要对已继承的本地 Token 进行显式迁移

参考: spec:AST-022/DEC-9 决策者: rubyycheung, 2026-09-05

物化无法通过复制名称使受谱系约束的本地 Token 具备可移植性。移除确切的基础谱系会使该声明在当前验证器下成为外部声明。因此,Detach 会停下来等待经过审查的本地 Token 迁移;如果作者改为保留谱系,则结果会继续遵循该基础主题,并且不是完全自有的。

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