主题编译¶
{
"scope": "global",
"triggers": {
"theming": [
"INV2",
"INV3",
"INV4",
"INV6",
"INV9",
"INV10",
"INV15",
"INV16"
]
}
}
此记录定义了一个主题定义如何变为可用的样式。
目的¶
主题作者只需定义一次主题。在 Web 上,在运行时使用主题与提前构建主题必须产生相同的 CSS 行为。
其他平台可能需要不同的输出。例如,未来的原生编译器可能会生成样式对象而非 CSS。它仍应从相同的主题定义开始。
系统模型¶
编译器从主题创作系统接收 DefinedTheme。
当前的 Web 编译器的工作方式如下:
generateThemeRules将可移植令牌、主题本地令牌和组件覆盖项转换为 CSS 规则。- 有序的适配规则在根规则之后编译为独立的媒体块。块保留作者的顺序,绝不会被合并或进行值差异比较;媒体表面覆盖项在其之后编译。
- 同一代码会添加状态规则、媒体表面规则、作用域和层。
- 当主题未提前构建时,
Theme提供者会挂载这些规则。 - CLI 将这些规则保存到 CSS 中,并打包相关的 JavaScript 和类型。
- 构建后的主题保留本地令牌所有权、有效宽度点、生成轴元数据和规范化后的有序规则,并会被标记,以便提供者不会再次编译或注入它。
- 构建后的主题在其 JavaScript 中携带函数图标条目、
componentIcons函数和iconVariants列表,因此构建后的解析会返回与运行时主题相同的节点。构建无法携带的函数会导致构建失败。
对于基础组件目标规则中的顶层声明,编译器按原样保留通用 CSS 属性。当保证属性需要到达内部绘制器时,受检注册表还会将其转换为一到多个私有变量,并且当将其应用于目标元素会产生错误时,可能会替换源声明。经审核的公共语义自定义属性作为直接的作者输入传递。契约禁止直接的私有 --_* 输入;当前的运行时、构建、伪规则和媒体表面一致性差距如下所列。
未来的平台编译器可能会将相同的主题转换为不同的输出类型。平台特定的细节保留在该编译器内部。
边界与不变量¶
- INV1 — 一个定义可以有多种输出。 作者不会为相同的共享主题意图维护单独的定义。
- INV2 — Web 只有一个编译器。 运行时和静态构建调用相同的代码将主题转换为 CSS。
- INV3 — 挂载和保存不会改变规则。 提供者挂载编译后的 CSS。CLI 保存并打包它。两者都不会产生不同的主题行为。
- INV4 — Web 使用单一的级联契约。 运行时和构建后的 CSS 使用相同的作用域、
astryx-theme层、组件覆盖项和消费者优先级。 - INV5 — 保证属性保持可观察。 当直接保留保证的目标属性能产生承诺的效果时,编译器会直接保留它。如果内部结构阻止了这一点,一个受检注册表条目可以将公共属性路由、转换或分发到一个或多个私有组件变量;实现选择不能改变该属性承诺的含义。
- INV6 — 私有变量保持私有。 私有
--_*变量是编译器/组件的实现细节。主题作者使用拥有它们的保证属性。运行时和构建的创作路径必须拒绝直接的私有值,而不是将它们作为貌似合理的输出发出。 - INV7 — 公共语义变量有意地直接传递。 仅当组件主题契约允许时,经审核的公共自定义属性才是直接的作者输入,因为没有任何保证的 CSS 属性可以表达这种需求。编译器必须保留它,而不能将私有机制变成公共 API。
- INV8 — 通用属性不会因编译而成为承诺。 通用样式流水线可能会发出目标保证集之外的属性。仅凭输出并不能使其效果或兼容性成为公共契约的一部分。
- INV9 — 平台细节不进入共享创作。 CSS 选择器、层、作用域和自定义属性属于 Web 编译器。原生编译器可以使用原生的样式对象。
- INV10 — 共享意图保持相同的含义。 令牌或受支持的组件覆盖项在所有输出中含义相同。仅平台特有的功能具有明确的支持边界。
- INV11 — 主题本地名称保持精确且与前缀无关。 对于已注册的主题,编译器在可移植声明旁边发出规范化后的
localTokens映射,而不会重写名称或值。前缀既不授予也不限制所有权。对有效已注册声明的精确引用会保留所有者、血统、冲突和循环验证;非精确引用保持外部引用。运行时和静态输出使用相同的规则,并且无效的已注册输入会在任一路径写入部分 CSS 之前被拒绝。 - INV12 — 适配顺序是可观察的。 根声明首先发出,适配块按作者顺序保持独立,媒体表面覆盖项最后发出。重复的条件和后续恢复根的写入会被精确保留;运行时和静态输出使用相同的块。
- INV13 — 声明保持在其边界内。 Web 编译器只拒绝会导致其 CSS 声明/规则边界逸出或失效的作者属性名或值。它会丢弃该声明并继续生成主题的其余部分,包括继承和条件表面。边界检查会保留有效的作者 CSS 字节,包括带引号的分号/花括号、data URL、转义、闭合注释、嵌套函数、带厂商前缀的名称和
!important。它不是一个属性-值语法验证器。旧版未注册令牌值保留其历史字符串插值;此检查不得为null之类的值引入崩溃。现有的构造验证(包括原子化的已注册本地令牌验证)保持独立且不变。 - INV14 — 报告不会改变编译。 被丢弃的声明会产生运行时警告,并出现在现有静态构建收据的
warnings中。现有的generateThemeRules、generateThemeRulesSplit、generateThemeCSS、generateOnMediaCSS和generateAdaptationCSS操作可以接受一个可选的warnings?: string[]收集器。提供它只会追加警告文本,而不会将该文本写入控制台;它不会改变生成的 CSS、清除现有的数组条目、改变验证或修改主题。省略则保留正常的运行时警告行为。此传输不会引入回调 API、导出的诊断/选项类型、主题元数据或结构化诊断模式。与旧核心配对的 CLI 保留该核心现有的编译行为;它不会假装检测旧核心无法报告的内容。 - INV15 — 构建后的图标解析与运行时匹配。 构建后的主题会将每个图标请求和插槽请求解析为与其运行时主题相同的节点,并且其公共图标和插槽导出是相同的节点值和静态视图。生成或子集化图标资源的构建工具将主题的请求枚举为每个条目的键,包含四种尺寸中的每一种,并且要么没有变体,要么有一个该条目在
spec:AST-087FR4 下可以接收的变体;它绝不会枚举该条目无法接收的变体,例如只有子主题为其继承的条目列出的名称。 - INV16 — 生成的兼容角色保留声明局部性和 CSS 级联。 当 Web 编译器从另一个公共令牌派生状态角色时,别名会在其语义源有效的主题作用域内发出,包括可达的适配和媒体组合。嵌套主题从其最近的提供者派生,而不是保留其父级的别名。作者编写的目的地角色、源顺序、
!important、inherit、具体值和循环保留其正常的 CSS 含义。运行时和静态输出使用相同的派生。 - INV17 — 主题生成确立每个状态角色。 对于主题未设置的每个
architecture:theme-tokensINV11 内容或文本角色,Web 编译器会在主题的生成 CSS 中、在运行时和主题构建中派生一个,因此只设置状态填充色的主题仍会编译为完整的状态集。规范化后的DefinedTheme只保留主题设置的令牌;非 CSS 解析(architecture:theme-tokensINV6)应用相同的派生。主题通过extends继承的角色视为已设置;父级仅派生的角色会从子级自己的颜色中再次派生:--color-on-<status>是主题的浅色或深色内容颜色(--color-on-dark或--color-on-light),取与主题的--color-<status>对比度更高者;当两者在其上的对比度都未达到 4.5:1 时,取纯白或纯黑,对比度更高者。--color-text-<status>是在每种颜色模式下,与主题的默认页面和卡片表面达到 4.5:1 对比度的亮度下的填充色相。--color-icon-<status>和--color-border-<status>是--color-text-<status>的别名,因此主题的文本值(已设置或已派生)会到达它们,除非主题也设置了它们。--color-on-<status>-muted是在默认表面上的主题浅色状态填充色上达到 4.5:1 对比度的亮度下的填充色相。
填充色从不派生:主题未设置的 --color-<status> 或 --color-<status>-muted 属于 Core。当主题设置了某种测量所依据的颜色时,角色会再次派生:填充色、浅填充色、默认页面或卡片表面,以及浅色和深色内容颜色。当填充色不是彩色时,文本和浅填充内容采用 Core 对该状态的固有色调,因此派生文本保持彩色。当这些计算所测量的颜色不是具体颜色(例如未解析的引用)时,它无法被测量,因此对于该状态,文本和浅填充内容角色会别名为主题匹配的色调文本令牌(--color-text-blue、-green、-yellow 或 -red),而 --color-on-<status> 保留主题或 Core 的值。这些别名携带主题自身的值:它们不是派生值,因此 INV11 的下限仅在 Core 和第一方主题中约束它们,这些主题使用具体颜色。主题设置的值总是优先于派生值。派生值在其来源设置的范围内发出(INV16),运行时和静态输出会派生相同的值。
- INV18 — 颜色模式块仅在其模式中生效。 Web 编译器将组件样式键的
@light或@dark块(属性、伪类覆盖和伪元素)编写为规则,这些规则仅在与元素颜色模式一致的地方匹配,正如 Theme 所解析的那样。在媒体表面之外,主题根的data-theme决定模式,而非light或dark的根模式遵循系统偏好。在主题的媒体表面内部,最近的表面决定:块在围绕元素的最近的媒体表面属于其模式时生效,因此深色表面内的浅色表面仅采用浅色块。这适用于交替模式嵌套最多五层的情况;更深时,块不会写出任何内容。模式条件位于样式键的选择器上,位于任何伪类、按压状态或伪元素之前,不增加特异性,也不增加作用域邻近性,因此块在表面上的权重与在根处相同。这些规则遵循样式键自身的规则,因此在其模式下,块覆盖样式键的值;在另一种模式下,它不写出任何内容:所有其他规则(包括上下文中的基础层规则)在该处照常应用,如同没有该块一样。块采用与样式键相同的派生变量和容器内边距。在媒体表面上,仅写出该表面模式的块。没有颜色模式块的主题在其 CSS 中就没有模式规则。 - INV19 — 正文字体令牌可触及主题根之外的文本。 当主题声明
--font-family-body时,Web 编译器为作用域根赋予font-family: var(--font-family-body)。Core 的重置在reset层以零特异性将相同声明赋予html,且无回退,body继承该声明。因此,库在主题根之外添加到body的文本(例如用于测量标签的 span)会使用该令牌在页面根处命名的字体。若页面没有样式表定义该令牌,则使用浏览器默认字体。应用自身的html或body字体优先生效。
本记录不拥有:
- 令牌名称和默认值,包括主题局部名称的含义;
DefineThemeInput、局部令牌注册与谱系、继承或编写优先级;- 哪些组件部分和属性是公共主题 API;或
- 编译后的提供程序嵌套、根同步和 DOM 观察。
变更耦合¶
- 任何对 web 主题如何变为 CSS 的更改都应属于共享编译器,并通过运行时挂载和 CLI 构建输出进行测试。Theme 提供程序和 CLI 可以挂载或打包编译后的规则;它们不得实现自己的主题到 CSS 转换。
- 添加或更改保证属性路径时,需使用目标的精确
guaranteedProperties声明,并添加代表性的编译器和运行时证据,证明该属性对该目标结构部位产生了其承诺的效果。仅凭目录成员资格并不构成保证。如果需要私有扩展,应在同一更改中更新受检注册表和组件元数据。 - 添加或更改公共语义自定义属性时,需验证直接运行时和构建输出、默认/回退行为,以及拒绝任何私有别名。
- 通用属性透传保持尽力而为,除非组件主题记录将该属性纳入保证集合,否则不得将其记录或测试为兼容性保证。
- 更改作用域或层输出时,需要对源码构建和发布构建进行测试。
- 更改局部令牌的发出或打包时,需验证精确名称的运行时/静态一致性、原子性失败,以及构建主题谱系元数据的保留。
- 更改自适应输出时,需验证已编写块的顺序、重复条件、根恢复写入、媒体表面优先级、派生组件降级,以及源码/构建扩展的一致性。
- CLI 和 core 独立版本化,因此 CLI 针对不支持自适应的 core 编译自适应是一种受支持的搭配,而不是损坏的安装。这种搭配仅限于自适应能力,而不是针对任意旧 core 的通用兼容方案:没有自适应意图的主题构建并发出与以往相同的 CSS,而有效的规则、自定义宽度映射,以及存在但格式错误的自适应元数据,都算作意图,并在生成任何输出之前以
ERR_CORE_INCOMPATIBLE失败。没有规则的完整默认宽度映射在两条路径上都是无操作,因为这就是 core 写入每个已解析主题和每个已发布构建主题的内容。两条路径都不允许在缺少自适应规则的情况下输出 CSS。当可用时,意图从已解析的元数据中读取;由于早于自适应机制的 core 会将其擦除,因此构建还会记录每个原始defineTheme()输入,并将其与它生成的主题关联起来。只有所选主题的谱系才起作用,因此图中其他未使用的自适应主题不会导致普通构建失败。如果所选谱系包含未观测到的源包——无论是异步回退绕过拦截,还是 CommonJS 到达无法包装的 core 命名空间——构建都会失败关闭(fail closed)。构建包产物通过其保留的元数据保持可观察。当旧 core 省略__axes时,捕获的原始排版、颜色、半径和运动元数据也会被保留,因此,扩展该产物的当前 core 子级能够像从源代码解析一样精确地解析部分自适应轴。对于没有自适应意图的主题,生成的 CSS 在两个 core 之间完全相同;生成的 JavaScript 和@generated来源信息可能不同,因为它们会记录已解析的元数据和 core 版本,因此升级后--check可以合理地报告差异(drift)。 - 添加平台编译器时,需指明其支持的共享概念,并测试它们保持相同含义。不受支持的概念应明确失败,而不是消失。
- 声明边界更改需验证扫描器的正例和反例、局部丢弃时邻近项保留、旧版令牌生成,以及令牌、局部令牌、变体、伪状态、媒体表面、自适应、继承和 Heading 回退规则的运行时/构建一致性。Collector 测试需验证追加文本、有无 collector 时 CSS 均不变,以及构建回执。
- 构建打包可以更改,而无需更改编译后的主题行为。
代码归属¶
generateThemeRules.ts负责 Web 编译器和规范 CSS 输出,包括同一作用域块中的可移植声明和主题本地声明。Theme.tsx为未提前构建的主题挂载编译后的 CSS。derivedVarRegistry.ts负责从保证的公共属性到私有组件变量的受检映射。- 组件的
.doc.mjs中的theming.derived[]镜像这些映射;theming.vars[]区分经审阅的公共语义变量与私有实现变量。 packages/cli/api/theme/build/build.mjs保存并打包编译后的 CSS。其私有变量诊断目前是非阻塞的;拒绝该输入是一项已命名的符合性差距,而非现有强制机制。它还负责对已安装核心的适配能力检查:基线生成是必需的,并且,在编写、解析或构建的输入中,有效或畸形的适配意图都会要求调用generateAdaptationCSS。core-interception.mjs负责捕获作者输入及其生成轴:它为正在加载的主题提供一个核心,该核心的defineTheme被包装起来,用于将每个原始输入记录到其返回的主题上;同时报告无法覆盖的加载器路径,从而让被擦除的意图永远不会以“干净”的状态通过。- 未来的平台编译器将在此边界之后使用同一个
DefinedTheme。
决策规范¶
AST-006 的决策 2 和 4(经 2026-09-12 修订)确立了与前缀无关的本地令牌名称,以及针对已登记主题的原子化共享验证。AST-012 的决策 3 和 4 确立了有序适配块以及源代码/构建元数据的对等性。AST-087 的决策 2 和 9 确立了函数图标条目,以及构建解析和图标图稿工具使用的、有限的主题级变体列表。系统负责人还另行选择了一个定义,包含平台特定输出,以及保证、尽力而为、公共语义和私有实现这几个层级。
验证¶
| 不变量 | 证据 | 失败信号 |
|---|---|---|
| INV1, INV2, INV3 | 编译器导入,以及运行时/构建对比测试夹具 | 运行时和构建使用不同的主题转 CSS 逻辑,或产生不同的 Web 规则 |
| INV4 | generateThemeRules.test.ts 以及源代码/分发级联测试 |
作用域或层顺序因输出路径而异 |
| INV5 | 现有按属性测试夹具(部分覆盖;缺口见下文) | 保证的属性能编译,但无法产生其承诺的可观察效果 |
| INV6, INV7 | 现有注册表和 CLI 公共变量测试(部分覆盖) | 私有变量变为可编写,或经审阅的公共语义变量在构建/运行时失败 |
| INV8 | 组件目标元数据与兼容性审查 | 成功的通用输出被当作有保证的公开行为 |
| INV9, INV10 | 另一编译器发布时的平台编译器测试 | CSS 细节进入共享编写内容,或共享主题意图悄然消失 |
| INV11 | defineTheme.test.ts 和 build.test.mjs 中的本地 token 测试夹具 |
运行时/静态输出重写本地名称、产生不一致,或在失败后留下部分输出 |
| INV12 | themeAdaptations.test.ts 与 CLI 适配构建测试夹具 |
规则块被合并/重排/丢弃,surface 失去优先级,或运行时/静态 CSS 产生分歧 |
| INV18 | colorModeBlocks.test.ts 输出测试、build-theme.color-mode-blocks.test.mjs(CLI 构建的 CSS),以及 colorModeBlocks.a11y.chromium.spec.ts(ColorModeBlocks 故事:Theme 的模式、系统偏好、既非前者也非后者的模式、嵌套的 Theme、媒体在一个及更多深层级上呈现、在根节点和 surface 上同样显式设置 Text 和 Heading props、一次按压、Pagination 的当前页以及文本字段的状态边框保持在另一种模式下) |
模式块应用在另一种模式下,覆盖了那里的一条基础层规则,或更改了没有块的 Theme 的 CSS |
| INV19 | generateThemeRules.test.ts(scope-root 字体规则)、reset.test.ts(html 规则,body 上则没有),以及 reset.font.a11y.chromium.spec.ts(在 body 中 span 内测量 label 时,其绘制宽度与 Theme 根节点一致;没有 token 的页面保持其字体) |
在 body 中测量或绘制的文本使用的字体与页面根节点处的 token 不同,或没有 token 的页面更改了字体 |
| 不变量 | 证据 | 失败信号 |
| - | - | - |
| INV13, INV14 | 声明扫描器、生成器、Theme 挂载、CLI 回执测试,以及现有的主题族 Chromium 守护 | 一条不安全声明破坏相邻项,有效 CSS 发生变化,legacy Token 生成崩溃,或报告流程改变 CSS |
| 已构建主题 | Theme 与 CLI 构建测试 | 运行时重新编译已构建主题,或构建输出遗漏规范规则 |
| INV15 | 包含 function 条目、slot 函数、variant 列表,以及被替换列表下的继承条目的 CLI 构建 fixtures,并与运行时解析结果进行比较 | 构建与运行时的图标不一致,function 被静默丢弃,或工具枚举了某条目无法接收的 variant |
| INV16 | Root、适配、媒体、嵌套主题,以及 CLI 构建的 status-alias fixtures | 生成的角色逃逸出其源作用域,覆盖作者角色,改变级联含义,产生循环,或因输出路径不同而不同 |
| INV17 | 一个仅设置四个状态填充的最小自定义主题(在运行时及通过 CLI 构建编译),以及设置浅色填充、灰色填充、未解析填充、未解析卡片表面、仅表面、仅色调文本 Token、仅在适配规则内设置填充的主题,还有一个 extends 了某个设置状态角色的主题的主题;其中每个也通过非 CSS 解析读取 |
内容或文本角色缺失,在浅色或深色模式下未达到 INV11 下限,变为灰色,忽略主题设置的值,或在运行时、构建与非 CSS 解析之间出现差异;图标或边框角色未跟随文本角色;填充被派生;或继承角色被再次派生 |
已知的一致性与验证差距¶
在编译器无法测量的内容之上放置的 onDark/onLight 媒体表面内,主题在该处设置的状态填充会获得其派生内容,但其文本和浅填充内容是以 INV16 别名而非派生值的形式到达其角色的。在适配规则内部,每条规则的派生值只将该规则与根主题组合,因此同时匹配且各自设置了可测量颜色的规则,尚不能根据它们的组合来派生。
声明边界强制和 INV13–INV14 中的 warnings-array 收集器已被接受但尚未发布。上文中的验证义务描述的是实现验收,而非现有强制实施。
前缀无关 localTokens 键接受已获接受,但尚未发布。当前编译器仍要求使用原始的主题派生前缀,并用该前缀对局部引用进行分类。在实现落地之前,INV11 的前缀无关条款是当前的权威依据,而非强制实施;精确名称输出以及现有的 enrollment、owner、lineage、collision、cycle 和 legacy-unenrolled 行为仍保持已发布状态。
以上剩余的不变量描述了已获批准的当前契约。以下已发布行为尚不符合要求,且不得视为强制执行:
- 私有作者输入未得到端到端的拒绝。
themeBuild在回执/日志中将直接的--_*值报告为错误,但仍继续编译并输出它们。其校验仅检查components下的顶层声明;嵌套的伪声明和媒体表面组件会绕过该校验。运行时defineTheme没有等效校验,会接受这些值。后续修复必须在 CSS 生成之前沿两条路径递归地拒绝直接私有变量,并证明运行时/静态行为一致。 - 嵌套的伪组件声明绕过了派生展开。 根位置、适配中以及
onDark.components/onLight.components下的顶层组件声明使用derivedVarRegistry,包括replaces和容器展开。这些表面上的嵌套伪声明仍直接序列化属性。后续修复必须让嵌套伪元素走同一组件声明降级路径,并为普通映射、replaces和容器内边距提供一致性夹具。 - 保证属性覆盖并非机器完备。 共享目录是规范性的,但组件文档模式没有针对每个目标的
guaranteedProperties声明。因此 CI 无法证明某个目标理性支持其选定的目录子集或经评审的增补。后续修复必须添加并迁移该元数据,然后在声明的目标/属性对缺少输出路径和可观察的运行时证据时使其失败。
这些不变量是管理实现与评审的已批准规则。上述不符合项是违背该契约的已发布缺陷,而非拟议行为。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx