跳转至

主题创作契约

{
  "scope": "global",
  "triggers": {
    "theming": [
      "INV1",
      "INV3",
      "INV8",
      "INV9",
      "INV11",
      "INV12",
      "INV13",
      "INV14"
    ]
  }
}

该记录定义了主题作者可表达的内容,以及 defineTheme 如何将该输入规范化为一种自包含的主题表示。

目的

主题作者应只描述一次设计意图。运行时挂载和静态构建应消费相同的规范化结果,而不是各自独立地重新解释源配置。

系统模型

DefineThemeInput 接受:

  • 一个名称和可选的规范化基础主题;
  • 高阶颜色、字体排印、圆角和动效配置;
  • 显式语义 token 覆盖;
  • 可选的、主题族本地的 token 声明;
  • 组件目标/样式键覆盖,每一项可选地带有 @light 和 @dark 颜色模式块;
  • 图标和指示器注册表、componentIcons 插槽映射,以及 iconVariants 列表;
  • 语法 token;
  • onDark / onLight 表面覆盖;以及
  • 带固定命名宽度映射的有序环境 adaptations。

defineTheme 将该输入解析为扁平的 DefinedTheme。扩展主题包含其继承的已解析值,因此其规范化表示是完整的。独立构建不需要基础样式表。

规范化遵循唯一的优先级顺序:

  1. 已解析的基础主题;
  2. 根据颜色、字体排印、圆角和动效配置生成的值;
  3. 显式 token 覆盖;
  4. 生成的组件字体排印,随后是显式组件覆盖;
  5. 继承的和显式的媒体表面覆盖;
  6. 继承的和显式的主题本地声明,并对照已解析的 token、组件和媒体表面进行验证;以及
  7. 继承的和显式的图标/指示器注册表条目、componentIcons 条目,以及 iconVariants 列表。

显式值在其表面内胜出。组件映射按组件、样式键和 CSS 属性进行合并,而不是替换整个继承目标。在组件块、伪类块、颜色模式块、表面或适配规则中保持 undefined 的组件、样式键或值不会被设置:在样式键或颜色模式块中,继承值会保留,而重述的伪类块会整体替换继承的伪类块。null 保持其既有含义。根级 localTokens: undefined 与 extends: undefined 一样按名称被拒绝:根级 localTokens 或 extends 保持未定义几乎总是导入失败的结果。本地 token 保持 undefined 则不声明任何内容:适配规则写入谱系中任何主题都未声明的名称时,仍会以该名称失败,而对这类名称的 var() 引用保持为外部引用 (INV8)。

显式的图标、指示器或 componentIcons 条目会整体替换同一键的继承条目。显式的 iconVariants 列表会替换继承的列表;省略列表则继承。继承的函数条目保留定义它的主题的列表,因此仅当该列表和活动主题的列表都包含所请求的变体时,它才会收到该变体,否则收到 undefined。

icons 条目是 React 节点,或是接收 {size, variant} 的纯同步函数;有状态的 componentIcons 条目可以是接收插槽状态的纯同步函数。规范化主题会保留这些函数供 Astryx 解析使用。其公开读取保持普通值:DefinedTheme['icons'] 是节点值,每个函数在 {size: 'md'} 下读取;DefinedTheme['componentIcons'] 是名称、null 和静态请求的静态视图,解析器插槽被省略;DefinedTheme['iconVariants'] 是该主题的列表。在 defineTheme 内部,条目函数接收 variant,静态插槽请求和插槽函数也返回它,其类型为该主题列出的名称。

DefinedTheme['__componentIcons'] 按发布形态属于公开表面:其存在性和形状、当任一值为函数时存在的 componentIcons 插槽值,保持 spec:AST-017 兼容性。所有者选择了“接受 __componentIcons 为公开”(cixzhang,2026-11-11)。

边界与不变量

  • INV1 — 一个输入产生一个规范化主题。 运行时和构建消费者收到相同的 DefinedTheme;它们不实现各自独立的创作语义。
  • INV2 — 优先级是确定性的。 某个值的胜出者遵循文档规定的顺序,并且不依赖于该顺序之外的对象遍历。
  • INV3 — 扩展在语义上被展平。 extends 接受真实的 DefinedTheme,并向前携带其已解析 token、本地 token 所有者和谱系元数据、组件规则、媒体表面、适配与轴、图标、指示器、componentIcons 和 iconVariants。规范化后的子主题是完整的。
  • INV4 — 无效基础主题会明确失败。 传给 extends 的未定义值、命名空间或普通对象不能产生看似合理的部分主题。
  • INV5 — 显式 token 覆盖生成的刻度。 生成值提供连贯的默认值;显式语义 token 逐个 token 胜出。
  • INV6 — 组件覆盖深度合并。 重述一个 CSS 属性会在同一组件/样式键上保留继承的属性。颜色模式块以同样方式合并:在样式键的 @light 或 @dark 块中重述一个属性,会保留该块的其他继承属性。
  • INV7 — 表面覆盖一致地继承。 onDark 和 onLight 按顺序组合系统默认值、继承的表面值和本地覆盖。
  • INV8 — 本地 token 登记是显式的并跟踪所有者。 提供 localTokens,或扩展一个精确登记的基主题,会产生扁平的本地声明映射,以及精确的所有权和谱系元数据。每个声明键都是有效的 CSS 自定义属性名,且不与 tokens 冲突;所有权从不根据前缀推断。与有效已登记声明的精确 var() 匹配,在已验证的本地 token、组件、媒体表面和适配表面上是有主边。非精确引用保持为外部引用。已登记主题保留精确的所有者、谱系、冲突和循环验证;未登记主题保留其旧行为。
  • INV9 — 创作与输出是分离的系统。 本记录拥有规范化主题定义。共享编译器负责将其转换为样式;运行时和构建负责使用或保存该输出。
  • INV10 — 适配是有序的规范化意图。 每个有效主题都保留其完整的 sm/md/lg/xl/2xl 宽度映射、生成轴元数据,以及先继承后本地的 {when, value} 规则顺序。规则针对子主题的有效根元数据重新解析;它们不改变根 token 读取,也不引入身份、注册表、媒体表面或新的本地名称。
  • INV11 — defineTheme 只验证它自身构造的内容。 它负责主题创建和规范化。作为构造前置条件,它可以拒绝影响规范化主题行为或生成值的畸形输入。仅用于验证的创作或参考数据保持在 DefineThemeInput 和 DefinedTheme 之外。
  • INV12 — 主题 define* 辅助函数构造主题值。 它们将输入转换、派生或规范化为持久的类型化主题值,供当前受支持的消费者使用;仅验证并原样返回输入是不够的。
  • INV13 — 主题函数保留在解析之后。 函数式图标条目和插槽函数是纯同步的。Astryx 图标解析和枚举主题图标请求的构建工具(architecture:theme-compilation INV15)会调用图标条目;只有插槽解析会调用插槽函数。公开的主题读取返回节点、静态插槽值和变体列表,绝不返回函数。
  • INV14 — 变体列表是主题级别的。 iconVariants 列出整个主题支持的变体名称。它绝不是一个图标一个列表,也绝不与另一主题的列表合并。
  • INV15 — 动效是时长刻度之外的三个调节旋钮。 motion 在时长刻度之外接受 tempo(限制在 0.75–1.5)、character(crisp、standard、expressive)和 reducedMotion(system、always)。tempo 缩放每个时长 token,character 设置 --ease-entrance 和 --ease-move;在 tempo 为 1 且为 standard 时,这些 token 就是默认值。时长刻度的时长优先于 tempo,显式 token 同时优先于两者。扩展主题逐字段继承动效:子主题未设置的时长刻度字段或旋钮保留其基主题的值。每个时长在应用 tempo 之前的值会保留给忙碌指示器循环使用,这些循环从不跟随 tempo。tempo 和 character 都不影响手指跟踪、动量、橡皮筋回弹、屏幕键盘、按压模型的起始延迟、取消距离和点按闪动、悬停意图延迟、手势阈值、忙碌指示器循环,或 200 毫秒的减弱动效上限(spec:AST-108 FR4)。reducedMotion: 'always' 标记主题的根;凡是使减弱动效依赖于 prefers-reduced-motion 的机制,也同样会使其依赖于该标记(spec:AST-108 FR6)。适配规则可以设置 tempo 和 character,但绝不设置 reducedMotion。
  • INV16 — 颜色模式块属于其样式键。 样式键的 @light 或 @dark 值是一个样式块,带有样式键所接受的属性和伪类覆盖,并且仅在该元素的颜色模式为该模式时应用(architecture:theme-compilation INV18)。它是可选的且是叠加性的:没有颜色模式块的样式键按原样在两种模式下都应用。

此记录不拥有:

  • 语义化 token 名称/默认值;
  • 将 DefinedTheme 转换为样式规则,包括本地 token 输出、私有变量展开,以及级联/层(cascade/layer)行为;
  • 运行时挂载、作用域生命周期、根同步或 DOM 观察;
  • CLI 文件生成与打包;或
  • 哪些组件目标、状态和公共属性参与。

architecture:theme-compilation 拥有平台输出。对于 Web,运行时和静态构建使用同一个 CSS 编译器以及同一套受维护的样式表规则。未来可能出现的原生编译器可以将相同的主题定义转换为原生样式对象,而无需将 CSS 概念并入共享编写。运行时应用和 CLI 打包使用编译后的输出而不对其修改。参与的公共表面属于 architecture:component-theming-surface。

变更耦合

  • 准入标准要求:该字段或 define* 辅助构造产生了哪种规范化主题行为或生成值,运行时和静态构建如何消费它? 若没有具体答案,它就不得进入 Core 运行时编写。一个获准入字段的规范化、优先级、继承、校验、模板暴露和负面测试会一起变更。
  • 仅用于校验的主题数据保留在主题包测试、内部测试工具中,或由当前受支持的消费者使用的显式 CLI 检查器/doctor 工作流中。它不会仅仅为了共享校验器而进入 Core 运行时。
  • spec:AST-017 负责破坏性分类和迁移。当一个受维护的主题版本,其源码或构建在主题当前支持的 peer/依赖范围内,无法在未作修改的情况下与某个 Core 版本一起工作时,即使其规范化 token 和 CSS 未变,也会进入该路径。一个仅用于校验的 Core 字段、辅助工具或导出若导致该失败,就是真实存在的兼容性成本,而非无害元数据。有针对性且协调一致的破坏只能通过该兼容性负责人推进;此记录不定义其补救措施。
  • 本地 token 变更保留显式登记、有效的精确自定义属性名、精确的属主元数据、源码/构建谱系一致性,以及与可移植 tokens 的分离。前缀仅是属主约定:它们不授予、保留或限制属主权。同一个名称不能同时出现在两个映射中,否则 CSS 输出和可移植 token 辅助工具会解析出不同的值。
  • 更改优先级是一个兼容性决策,因为现有主题可能同时包含生成值和显式值。
  • 更改 ComponentStyleMap 合并行为时,需验证基础(base)、生成、显式和 on-media 组合;任何层都不得自创合并规则。
  • 新的生成尺度需声明它可能产生哪些语义 token,并确认显式 token 覆盖仍然生效。
  • 适配变更保留固定的条件词汇表、包含 from/排他 below 的宽度边界、作者编写的规则顺序、仅根节点的本地名称登记,以及源码/构建扩展一致性。
  • 运行时专用路径不可用的编写字段仍然被禁止。没有规范化主题效果的构建/CLI 元数据,只能为某个指定的当前受支持读取者存在,必须位于 DefineThemeInput 和 DefinedTheme 之外,且不得施加 Core/运行时兼容性负担。假设性的 sidecar 是不够的。

拥有代码

  • 内部纯函数 resolveThemeMotion(theme) 返回主题的动效旋钮、时长和缓动函数,供动画器和服务端代码使用;它不接触 DOM,也没有导入时副作用(spec:AST-108 FR6)。
  • packages/core/src/theme/defineTheme.ts 拥有公共输入、规范化 IR、编排和扩展行为。
  • themeAdaptations.ts 拥有固定断点/条件词汇表、校验、继承规则排序、轴线补全和具体规则写入。
  • syntax/defineSyntaxTheme.ts 在 defineTheme 采纳语法主题的 token 之前构建这些主题。
  • expandColorScale.ts、expandTypeScale.ts、expandRadiusScale.ts 和 expandMotionScale.ts 拥有各自的派生 token/组件值。
  • motionKnobs.ts 拥有动效旋钮的类型、默认值和钳制;themeMotion.ts 拥有它们生成的 token 和 pre-tempo 时长,以及动画器和服务端代码使用的纯读取 resolveThemeMotion。
  • mergeComponents.ts 拥有共享的深度合并规则。
  • onMediaTokens.ts 拥有反转表面(inverted-surface)覆盖的规范化。
  • localTokens.ts 拥有选择加入登记、有效的 CSS 自定义属性名、精确的属主元数据、引用闭包、循环检测、跨映射冲突拒绝,以及扁平化谱系。它不会从前缀推断属主权。
  • packages/cli/assets/theme.template.ts 是一个面向作者的投影,必须保持对齐;它不定义额外的语义。

决策规范

AST-006 的决策 1–4 和 6 确立了已发布的主题本地编写形态、登记、精确名称保留、继承、共享校验和值契约。其 2026-09-12 修订使键的有效性和属主权与前缀无关,同时保留精确的属主元数据、谱系、冲突、循环和旧版未登记行为。AST-012 的决策 1–4 确立了固定宽度映射、命名的封闭条件、有序规则级联,以及源码/构建适配元数据一致性。AST-017 的决策 1 负责已发布兼容性的分类和迁移。AST-087 的决策 2、7、9 和 10 确立了函数图标条目、节点值公共读取、主题级 iconVariants 列表,以及 componentIcons 的静态公共视图。AST-108 的决策 1 确立了三个动效旋钮,并保持按角色区分的动效值为内部。

已知符合性与验证缺口

与前缀无关的 localTokens 键接受已被认可但尚未发布。当前校验器仍要求使用原始主题派生前缀,并用该前缀对本地引用进行分类。在该实现落地之前,INV8 中与前缀无关的条款是当前权威,但不是强制执行。现有的显式登记、属主、谱系、冲突、循环和旧版未登记行为仍然已发布。

resolveThemeMotion 的角色表已被接受但尚未落地(spec:AST-108 FR6):目前还没有任何 spring 读取动效旋钮。在这些旋钮落地之前,FR6 的这部分只是当前权威,尚未强制执行。

reducedMotion: 'always' 已被接受但尚未落地(spec:AST-108 FR6、INV15):公开的 motion 类型没有 reducedMotion 字段;每个主题都像 'system' 那样遵循每个人的设置;并且没有任何东西标记主题的根——组件样式、动画器、prefers-reduced-motion 的脚本读取器,以及按动效键控的适配规则,都还不会以该标记作为 reduced motion 的依据。在此之前,INV15 和 FR6 的这一部分只是当前权威,尚未强制执行。

INV9 缺口:DefinedTheme 中名称以 __ 开头的字段(__icons、__iconEntryVariants、__componentIcons、__built、__inputTokens、__localTokenOwners、__localTokenLineage、__onDark、__onLight、__adaptations、__adaptationRules、__axes)是可触达的公共表面,而本记录未为它们定义任何契约。

INV13 缺口:DefinedTheme['__componentIcons'] 和 DefinedTheme['__icons'] 是可触达的,并返回主题的插槽函数和函数图标条目。

验证

不变量 证据 失败信号
INV1, INV2, INV5 defineTheme.test.ts 以及具有代表性的运行时/构建一致性 运行时和构建对同一输入的解释不同,或生成值优先于显式令牌
INV3, INV4 扩展和无效基础(invalid-base)测试 子主题需要基础样式表,或静默接受非主题基础
INV6 跨基础/生成/显式规则的组件合并测试 重复声明某个属性会丢弃继承的组件样式
INV16 colorModeBlocks.test.ts 通过 extends 进行的合并测试、生成的排版刻度规则,以及继承的媒体表面 颜色模式块被合并丢弃,或使没有颜色模式块的主题发生变化
INV7 onMediaTokens.test.ts 和生成的表面规则测试 子主题丢失继承的表面定制,或表面优先级发生变化
INV8 AST-006 运行时/静态验证器以及源码/构建产物继承测试 有效名称因其前缀而失败、所有权由拼写决定,或谱系/引用/冲突/循环检查出现分歧
INV10 themeAdaptations.test.ts 和 CLI 构建夹具 宽度元数据、规则顺序或子主题的重新解析在源码主题与构建后主题之间出现分歧
INV11 DefineThemeInput/输出差异以及运行时/构建夹具 仅用于验证的数据进入了规范化主题,或生产性输入失去构建验证
INV12 Core 主题导出差异、构造值证据以及当前使用方的调用点 主题的 define* 辅助函数仅检查输入并原样返回该输入
INV13, INV14 defineTheme.test.ts 针对函数条目、插槽函数和列表的类型与规范化测试 公开读取返回函数、子主题合并变体列表,或某个条目看到另一个主题的名称
INV15 themeMotion.test.ts 覆盖 tempo 边界、characters(动效特征)、时长刻度、显式令牌和扩展 令牌偏离其旋钮、旋钮优先于刻度或显式令牌、继承的旋钮丢失,或跟随 tempo 形成循环
主题/Core 兼容性 在目前支持的 peer/dependency 范围内,以最低 Core 版本对受维护的主题源码/构建产物进行验证 主题更新静默要求范围内更高的 Core 版本,或绕过 spec:AST-017 路径
创作投影 scripts/check-theme-template.test.mjs 某个受支持的创作概念在模板中缺失或被错误表述

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