跳转至

Theme-local tokens system spec

{
  "scope": "global",
  "triggers": {
    "tokens": ["DEC-1", "DEC-2", "DEC-3", "DEC-4", "DEC-5", "DEC-6"]
  }
}

意图

让受维护的主题能够在组件覆盖中复用其自身的语义决策,而无需将该决策添加到 Astryx 的可移植令牌词汇表中。主题作者获得一条显式、可校验的主题族本地复用路径;组件和应用作者则继续使用他们今天所拥有的同一可移植令牌契约。

发布的 API 是一个可选的 DefineThemeInput.localTokens 字段。显式提供该字段即将该主题纳入契约;省略该字段则保留现有行为。本地令牌可以使用任何有效的 CSS 自定义属性名称声明,并通过完全相同的名称进行引用。前缀不会授予、保留或限制所有权。后代通过已注册的精确 extends 谱系继承注册状态,并且只能通过该谱系替换精确名称。仅凭发出的 CSS 不构成契约,但由其所属主题规范记录并发布的已注册定义则构成契约:其精确名称和语义含义在该主题族内是公开的,不可跨主题移植,也不用于 Core 组件源码。

本当前记录独立于任何特定主题是否已完成其自身的采用证据,管辖跨主题 API 及不变量。原始本地令牌表面已发布;2026-09-12 命名修订已被接受,等待其实施。主题本地名称、含义、值、映射和渲染证据仍归各采用主题的共置记录所有。

非目标

  • 更改现有 DefineThemeInput.tokens 路径的类型、接受的输入、运行时或构建行为、宽松的展开行为、名称、优先级、继承、输出或解析。
  • 添加 defineLocalTokens 辅助函数、第二个编写操作、较短的角色标识符、引用别名或并行的本地令牌 API。
  • 将主题本地名称添加到 TokenName、tokenVar、tokenVars、resolveThemeToken、生成的可移植令牌文档或 Core 组件源码中。
  • 创建应用程序消费方的令牌扩展机制。编译后的自定义属性是其受维护主题族的实现输出,并非应用程序代码依赖它的授权。
  • 定义任何采用主题的角色含义、值、组件映射或证据。这些属于该主题的共置记录。

需求

以下需求是当前的跨主题契约。

  • FR1 — 本地令牌是纯增量、可选且显式注册的。 DefineThemeInput 最多只能增加一个新的编写表面:可选的 localTokens。显式提供 localTokens 即将该主题纳入新契约。后代仅通过扩展已注册的精确基类来继承注册状态。既未提供该字段也未扩展已注册精确基类的主题保持未注册状态,且 MUST 生成字节等价的 DefinedTheme 数据、运行时行为、静态输出、包输出和解析行为。
  • FR2 — 现有令牌行为已冻结,本地值复用其值契约。 本契约 MUST NOT 更改 tokens 的类型、接受的输入、运行时处理、静态处理、宽松的未知键或广泛展开行为、名称、优先级、继承、输出或解析。现有转换、展开、外部 CSS 变量和旧版令牌引用 MUST NOT 收到新的警告、失败、重新解释或迁移要求。在选择性加入的 localTokens 字段内,每个值 MUST 接受完整的现有 TokenValue 契约:CSS 字符串或 [light, dark] 元组。运行时和静态构建 MUST 应用与现有 tokens 相同的值规范化语义,而不更改该现有路径或规范化主题名称。
  • FR3 — 一个精确名称贯穿每个阶段。 本地令牌声明 MUST 使用其完整的 CSS 自定义属性名称作为 localTokens 键。同一精确字符串 MUST 用于 var(...) 引用、DefinedTheme 数据、运行时 CSS、静态 CSS、继承替换以及生成的主题特定类型或元数据。任何转换都不得创建第二个标识符。
  • FR4 — 接受任何有效的自定义属性键。 每个新声明的 localTokens 键 MUST 是有效的 CSS 自定义属性名称,并且 MUST 逐字节保留。不得要求、保留、重写或解释任何前缀作为所有者或注册元数据。主题名称和本地令牌键相互独立;本契约不定义任何首选的替换命名模式。
  • FR5 — 本地使用保持在受维护的主题族内。 本地名称可以被定义它的受维护已注册主题以及通过其精确 extends 谱系注册的后代引用。它 MUST NOT 成为可移植的跨主题令牌或 Core 组件源码中的依赖。来自未注册旧版路径的单纯 CSS 输出不构成契约。一旦已注册主题发布在其共置主题级规范中记录的本地令牌,该精确名称和语义含义即成为该主题族的公共兼容性契约。
  • FR6 — 扩展遵循精确名称、注册状态和谱系感知。 后代仅从已注册的精确 extends 基类继承注册状态和声明。它只能通过重申该继承的完整名称来替换继承的本地令牌。新声明的名称归声明主题所有,无论其拼写如何。前缀、后缀或值相似性 MUST NOT 创建所有权或谱系,子主题 MUST NOT 声称另一主题的声明。
  • FR7 — 仅对已注册主题进行原子校验。 运行时和静态构建 MUST 共享一个递归校验器。对于直接注册或通过已注册精确基类注册的主题,它 MUST 在产生部分输出之前校验每个声明的自定义属性语法、精确所有者和谱系、与可移植 tokens 的冲突,以及本地令牌值、组件覆盖、媒体表面和适配之间精确声明引用中的循环。与有效本地声明精确匹配的适配 value.tokens 键 MUST 失败,以便写入使用 value.localTokens 并保留所有者、谱系和循环校验。var() 引用仅在精确匹配有效已注册声明时才是本地边;所有其他自定义属性引用保持外部。前缀没有校验含义。
  • FR8 — 未注册的旧版行为按原样保留。 当 localTokens 不存在且精确基类未注册时,运行时和静态构建 MUST NOT 为 CSS 自定义属性引用添加新的扫描、拒绝、警告、保留或解释。现有自定义属性继续不变。维护者可以保持该行为未注册,或通过提供 localTokens 显式迁移;任何前缀都不会改变任一路径。
  • FR9 — 源主题和构建主题保留同一条注册谱系。 源定义主题和构建主题 MUST 保留等价的精确本地令牌映射、注册状态和谱系元数据,以便后代接受、继承、替换、拒绝和发出相同的名称,而无需基础样式表。
  • FR10 — 已发布的名称和含义是兼容性义务。 一旦已注册的本地令牌发布,其精确名称和记录的语义含义即成为所属主题族的公共契约。重命名本地令牌或其已注册主题,或更改该含义,MUST 使用经过显式审查的迁移或别名,在其兼容窗口内保留先前的精确名称、含义和谱系契约。禁止静默键替换、语义扩展、所有者重新分配和推断性后代迁移。
  • FR11 — 共置主题规范拥有定义和映射。 每个主题本地令牌定义 MUST 位于所属主题的共置主题级规范中,包括其精确名称、语义含义、值、映射、兼容性和渲染证据。当长生成名称准确命名了其应用的每个上下文所共享的含义时,该名称是可接受的。添加映射属于主题规范兼容性审查:上下文 MUST 真正匹配记录的含义,并且 MUST 为其实际的明/暗和相关交互状态提供渲染证据。

编写形态

defineTheme 仍然是唯一的编写操作。每个 localTokens 键都是用于 var(...)、DefinedTheme、继承以及生成输出的完整 CSS 自定义属性名。该键按字节原样保留,且没有必需的前缀。值复用现有的 TokenValue 契约,并与现有 tokens 值一样进行完全相同的规范化。采用 theme:* 的记录拥有每个具体的角色、值和组件映射。

平台支持

  • 支持的功能/引擎基线:与现有 Web 主题相同的 CSS 自定义属性、light-dark()、主题作用域和浏览器支持。
  • 不支持的行为:无法保留局部角色及其谱系的平台编译器 MUST 明确拒绝该已登记输入,而不是静默省略它或将 CSS 拼写暴露为共享的跨平台 API。
  • 浏览器证据:每个采用的主题都在真实 Chromium 中验证其实际组件映射和颜色模式。名称、验证、继承以及运行时/静态一致性都是结构性的,且无需视觉证据即可测试。

当前状态影响

当前 main 保持其封闭的可移植核心/领域 token 词汇表,并随附一流的 localTokens 字段,采用基于前缀的原始键验证。2026-09-12 修正案仅放宽可接受的局部 token 键拼写;实现仍然待定。到达宽松旧路径的未知键仍可序列化,但只有显式的 localTokens 登记才会创建所有权、引用闭合和谱系验证。

  • architecture:theme-authoring-contract 负责可选的 localTokens 输入、其精确名称映射、显式登记状态、扁平化继承和谱系元数据;
  • architecture:theme-compilation 通过共享的运行时/静态编译器发出该精确映射,并仅对直接登记或通过已登记精确基类登记的主题应用一个递归验证器;
  • architecture:theme-tokens 继续负责未变更的可移植词汇表,并明确将主题局部名称排除在其公共辅助函数和文档之外。

这些当前架构记录反映了已批准的行为,并引用了适用的 AST-006 决策。在实现落地之前,与前缀无关的键接受仍是一个已命名的符合性缺口。草稿主题记录可以引用当前规范,同时保持其自身的值、映射和证据决策未解决。

兼容性与采用

  • 采用是按所维护的主题系列进行的,且是可选的。现有主题不会仅仅因为该字段存在而被迁移。
  • 省略 localTokens 且不扩展已登记精确基类的主题,在 DefinedTheme、运行时、静态和包输出方面保持字节等价。其 CSS 自定义属性引用不会受到新的扫描、拒绝、警告、保留或解释。
  • 登记接受任何有效的自定义属性键。要迁移现有自定义属性,维护者必须显式地在 localTokens 中声明该精确键;前缀不影响资格或所有权。
  • 现有 tokens 和外部变量行为保持字节等价,包括宽松的广泛展开和运行时输入。
  • 发布后,局部名称和文档化含义成为公开的主题系列兼容性义务;它们永远不会成为可移植的跨主题或全局 Core token 承诺。来自未登记旧路径的单纯自定义属性发出并不会创建该契约。
  • 每个局部定义和映射都位于所属包的配套主题规范中。每个新映射在采用之前都要审查其上下文是否真正匹配文档化含义,并提供渲染证据。
  • 后代兼容性遵循显式登记和精确谱系。已发布的已登记主题或 token 重命名,或语义含义变更,都要求在后代移动之前提供显式迁移或别名。
  • 基础设施实现自带其自己的 Changeset。后续采用的主题输出变更则带有单独的发布说明。

验证

契约 验证 代表性状态 变更或失败预期
FR1, FR2, FR8 旧版类型、运行时、构建、解析和字节输出夹具 省略字段;直接 tokens;广泛展开;类型转换;外部自定义属性;可移植引用 向省略字段路径添加扫描会改变旧版行为。
FR2 局部 TokenValue 一致性夹具 CSS 字符串;[light, dark] 元组;引用值;运行时/静态归一化;现有 token 对照 局部值拒绝现有形式、在不同路径中归一化不同,或改变现有 tokens 对照。
FR3, FR4 精确名称编写、类型和输出夹具 具有不同前缀的有效自定义属性键;无效自定义属性键;精确引用;运行时和静态输出 任何阶段重写键,或因前缀而改变有效性/所有权。
FR5, FR6, FR9 源码基座与构建基座的注册/谱系夹具 根主题选择加入;子主题继承精确基座;子主题精确替换;子主题新角色;未注册及无关名称 子主题因拼写而非精确谱系获得所有权,或源码/构建的注册结果不一致。
FR7, FR8 运行时与静态构建共用的递归验证器夹具 精确声明的引用;外部引用;可移植碰撞;适配 value.tokens 碰撞;谱系不匹配;循环;未注册主题 已注册主题的错误产生部分输出、路径不一致、本地写入绕过 value.localTokens,或前缀改变引用分类。
FR10, FR11 主题包兼容性夹具、同地主题规范与发布评审 精确名称;文档化含义;已注册主题重命名;本地令牌重命名;含义变更;别名窗口 已发布名称或含义被静默更改、定义缺少所有者,或后代失去其继承的契约。
FR11 逐映射的主题规范评审加聚焦的渲染证据 精确角色含义;映射的组件/状态;亮色/暗色;相关交互状态 映射在文档化含义之外使用令牌,或未经上下文渲染证据即发布。

完成标准

AST-006 仍保持 shipped 状态;当 2026-09-12 命名修订的实现连同已发布的契约满足以下标准时,即达成符合性:

  • 可选的 DefineThemeInput.localTokens 是唯一新增的本地令牌编写入口,且其存在是根注册的触发条件;
  • 没有 localTokens 且没有已注册精确基座的主题须被证明字节等价,且不产生新的自定义属性扫描、拒绝或警告;
  • 本地值接受现有两种 TokenValue 形式——CSS 字符串和 [light, dark] 元组——并且运行时/静态归一化与现有 tokens 值路径一致,且不改变该路径;
  • 每个有效的 CSS 自定义属性键都被接受,并在声明、var(...) 使用、DefinedTheme、源码/构建继承以及输出结果中逐字节保留,且不附带任何前缀语义;
  • 后代仅从已注册的精确基座继承注册;拼写绝不会创建所有权或谱系;
  • 对于已注册主题,自定义属性语法、令牌碰撞、精确所有者与谱系以及循环失败在运行时和静态路径上均为原子且一致;
  • 构建后的主题保留足够的注册与精确谱系元数据,以供没有基础样式表的后代使用;
  • 每个已发布的本地定义由其同地的主题级规范拥有,其精确名称和语义含义在该主题家族内被视为公共兼容性契约;
  • 每个新增映射都须通过主题规范兼容性评审,并提供渲染后的亮色/暗色及相关交互状态证据,以证明其上下文确实符合文档化含义;
  • 公共可移植令牌类型、辅助工具、文档和 Core 组件源码不得将本地名称暴露为跨主题 API;以及
  • 每个采用者的同地 theme:* 记录拥有其名称、含义、值、映射、迁移和渲染证据。

决策日志

以下决策由 cixzhang 批准,作为当前规范的一部分。

修订 — 使本地令牌名称与前缀无关

决策者: cixzhang,2026-09-12

localTokens 接受任何有效的 CSS 自定义属性键。前缀对有效性、所有权、注册或谱系没有影响。本修订取代先前记录在 FR4、FR6–FR8、DEC-2、DEC-3 和 DEC-4 中的命名模式和保留前缀条款。精确键保留、显式注册、所有者元数据、精确 extends 谱系、继承、可移植令牌碰撞检查和循环检查仍然有效。本修订不定义任何替代命名模式。

DEC-1 — 在不改变 tokens 的前提下增加一个可选的本地令牌字段

参考: spec:AST-006/DEC-1 决策者: cixzhang,2026-08-31

使用一个纯粹新增的可选 DefineThemeInput.localTokens 字段。显式提供该字段即注册主题;精确后代可从已注册基座继承该注册。保持 defineTheme 作为唯一的编写操作,并保留所有现有的 tokens 类型、输入、运行时、构建、展开、优先级、继承、输出和解析行为。没有 localTokens 且没有已注册精确基座的主题,无论自定义属性拼写如何,都保持字节等价。

已否决:defineLocalTokens 辅助函数、并行 API、根据键拼写的隐式注册、对可移植令牌词汇表的模块扩充,或对现有令牌路径的更严格验证。

DEC-2 — 保留一个精确、与前缀无关的名称

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

localTokens 声明接受任何有效的 CSS 自定义属性键。声明键即 CSS 变量,引用使用同一个逐字节相同的名称。任何前缀都不被要求、保留、重写或解释,主题名称也不决定该键。本决策不定义任何优先的替代命名模式。

已否决:生成名称、引用别名、隐藏规范化,以及任何基于前缀改变有效性或所有权的命名规则。

DEC-3 — 将替换绑定到精确的扩展谱系

参考: spec:AST-006/DEC-3 决策者: cixzhang,2026-08-31;修订于 2026-09-12

后代仅从已登记的精确 extends 基类继承登记,并且仅当继承的精确名称通过该谱系到达时,才可以替换它。新声明归声明它的主题所有,无论其拼写如何。源码主题与构建主题保留等价的登记与谱系元数据。已发布的已登记主题或令牌重命名需要显式的迁移或别名。

已否决:基于前缀、后缀或值的所有权或谱系推断、外部所有者声明,以及扩展期间的静默键重写。

DEC-4 — 验证精确登记的声明图

参考: spec:AST-006/DEC-4 决策者: cixzhang,2026-08-31;修订于 2026-09-12

运行时与静态构建共享同一个精确校验器。在直接或继承登记之后,它检查自定义属性语法、可移植令牌冲突、精确所有者与谱系元数据,以及精确声明引用之间的循环。只有当引用与有效的已登记声明精确匹配时,它才是局部的;每个不匹配的自定义属性引用仍保持为外部引用。未登记的主题不会收到新的扫描、拒绝或警告。前缀在分类中不起任何作用。

已否决:基于前缀的分类、宽泛的外部变量校验器,或利用新字段来收紧遗留运行时的宽松性。

DEC-5 — 所属主题规范定义公开的主题族契约

参考: spec:AST-006/DEC-5 决策者: cixzhang,2026-08-31

主题本地令牌定义应放在所属包内同置的主题级规范中。一旦发布,精确的令牌名称与语义含义便成为该受维护主题族内的公开兼容契约,即使该令牌不可跨主题移植,也不打算用于 Core 组件源码。仅凭未登记遗留路径的输出是不够的;显式的登记、发布和主题规范才能确立该契约。

当长生成名称能准确描述主题应用它的每个上下文时,它是可以接受的。因此,添加任何映射都是一次主题规范兼容性审查:该上下文必须确实表达文档所记载的角色,并且必须为其实际的浅色/深色(light/dark)及相关交互状态提供渲染证据。

已否决:将本地名称视为全局可移植令牌或一次性实现细节、在所属主题规范之外定义它们,以及在恰好共享同一值的上下文中复用名称。

DEC-6 — 复用现有的完整 TokenValue 契约

参考: spec:AST-006/DEC-6 决策者: cixzhang,2026-08-31

localTokens 接受现有的完整 TokenValue 契约:一个 CSS 字符串或 [light, dark] 元组。在这个新的可选(opt-in)字段内,运行时与静态构建都应用现有 tokens 所使用的相同值规范化语义。这复用了既有的 light/dark 编写模型,同时不改变现有 tokens 路径,也不引入另一种值形态。

已否决:仅将本地值限制为 CSS 字符串,或定义本地特有的模式语法与规范化。

未决问题

在跨主题 API 层面没有未决问题。采用主题规范可以保留可检查的渲染证据门禁;这些门禁不会重新开启对其所有权、精确名称和语义含义的讨论。

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