跳转至

StyleX data-token 归属系统规范

预构建的 Core CSS 携带 data-token 默认值

预构建模式下的公共 dataVars 入口包含编译后的 var() 引用,而非 defineVars() 调用。使用该入口以及随附 Core CSS 的应用程序没有任何 StyleX 提取步骤来实体化被引用的默认值。因此,Core 的预构建样式表将该组作为其公共 CSS 契约的一部分来携带;主题是否存在并不控制其可用性。

意图

Astryx 在其其他设计 Token 所在的同一个公共 StyleX Token 系统中,持有一个规范的 56-token 数据调色板。组件导入公共 StyleX 变量对象,而不是构造字面量 var(--color-data-*) 字符串。当基于源编译的消费者使用该组时,StyleX 编译器会发出该规范组;对于不使用该组的基于图的源构建,则省略该组。无论消费者是否导入该组,Core 的预构建 astryx.css 和 @astryxdesign/build PostCSS 集成都会包含该组。

一个具体主题仅在其现有主题 donut 内发出该主题显式编写的 data-token 值。它绝不携带规范默认值或原始全局 data-token 块。未指定的数据颜色使用 StyleX 默认值和正常的 CSS 继承;嵌套主题仅更改它编写的子集。

公共 CSS 自定义属性名称、JavaScript Token 解析、生成的 JavaScript 标记以及三条现有的全局 color-scheme 规则保持稳定。运行时和构建时主题编译产生相同的稀疏作用域覆盖。

StyleX 0.19 在模块/组边界(而非按属性)对 defineVars 进行 tree-shaking。这 56 个数据变量有意形成一个语义组:当模块未使用时,基于图的源构建发出零个数据默认值;当任一成员被使用时,发出全部 56 个。预构建的 Core 样式表和 @astryxdesign/build PostCSS 集成始终包含完整组。该契约不声称提供编译器并未提供的 Token 粒度剪裁。

非目标

  • 更改 56 个规范数据默认值的名称或值。
  • 添加单独的 CSS 默认值资源,或保留并行的纯 JavaScript Token 族作为独立的事实来源。
  • 使具体主题重复它们并未编写的默认值。
  • 对三条现有全局 color-scheme 选择器进行作用域化、重命名或重新设计。
  • 更改作用域化的 prose 默认值、非 data-token 声明、组件覆盖、适配、MediaTheme 规则、图标输出或类型增强。
  • 在 FR3 对其 PostCSS 集成的 data-group 保证之外,定义单独的 @astryxdesign/build 源构建组合契约。
  • 超出 FR17 中 breaking-minor 要求的发布调度和版本控制。
  • 满足此公共契约的等效内部实现仍然有效。

要求

规范源、公共 API 和类型

  • FR1 — 公共 StyleX 源拥有所有派生的视图。 已检入的 dataTokens.stylex.ts 模块 MUST 是所有 56 个名称和默认值的唯一规范源。它包含 stylex.defineVars() 消费的静态对象字面量,并导出公共 dataVars 对象。

生成过程 MUST 读取该 .stylex.ts 源并产出:

  1. 现有的普通 dataTokenDefaults 兼容视图,而不将 StyleX 值模块导入普通的 token-resolution 图中;
  2. DataTokenName 以及主题输入验证清单;
  3. 任何生成的文档清单。

    dataTokenDefaults MUST NOT 独立于 dataVars 进行手工维护。当生成的值、名称或类型偏离规范 .stylex.ts 源时,仓库检查 MUST 失败。规范文件 MUST 保留静态对象字面量,因为 StyleX 拒绝将导入的对象作为 defineVars() 参数。

  4. FR2 — 数据变量是显式的公共 StyleX 子路径。 Core MUST 从 @astryxdesign/core/theme/dataTokens.stylex 导出 dataVars。每个现有的公共自定义属性名称保持逐字节稳定,例如:

import {dataVars} from '@astryxdesign/core/theme/dataTokens.stylex';

const positive = dataVars['--color-data-categorical-green'];

包导出 MUST 使用与 @astryxdesign/core/theme/tokens.stylex 相同的 source、types 和 default 条件结构;现有的 StyleX sideEffects 声明继续覆盖源模块。该聚焦子路径可防止普通的 Theme、token-resolution 或非数据组件导入在源编译中将 StyleX 变量组作为副作用保留。在预构建模式下,同一个公共入口提供编译后的 var() 引用;加载 @astryxdesign/core/astryx.css MUST 提供其默认值,而无需消费者的 StyleX 编译步骤。

  • FR3 — Tree-shaking 在组边界处是真实的。 基于图的源编译——即编译从产品导入可达的模块——若未从数据 StyleX 子路径进行任何值导入,MUST 不发出任何 --color-data-* 默认声明。保留任何 dataVars 值导入的图 MUST 发出一个包含全部 56 个默认值的规范 StyleX 变量组。导入一个成员并不要求剪除其他 55 个。

@astryxdesign/build PostCSS 集成编译 Core 发布的每个模块,而不是可达图。无论产品是否导入 dataVars,其输出 MUST 恰好包含一个规范的 56 变量组,包含每个规范名称和值。

即使没有 Core 组件消费它,Core 的预构建 @astryxdesign/core/astryx.css MUST 也恰好包含一个规范的 56 变量组。包的编译后公共 dataVars 入口暴露了此样式表 MUST 定义的 CSS 引用;消费者导入无法从已编译的入口触发提取。此例外仅适用于预构建的 Core 样式表和上述 PostCSS 集成,不适用于基于图的源编译或具体主题。

分发输出 MUST 保持依赖感知:被引用的跨包 StyleX 变量依赖在卫星样式表及其必需的提供方样式表中恰好出现一次。其提供方已声明该组的数据消费包 MUST NOT 重复声明;在没有该提供方的情况下,必须发出保留组。除显式 Core 分发例外外,未被引用的组保持不出现。打包证据 MUST 报告保留组的原始与压缩成本。

受支持的源码与分发集成 MUST 将所发出的变量组放入 @layer astryx-base,与其它 Astryx StyleX 输出一致。未分层的 StyleX 流水线不在 FR8–FR10 的创作主题覆盖保证范围内,MUST 被诊断或记录,而不是被默不作声地声称等效。

消费者行为

  • FR4 — 支持 CSS 的消费者使用公共对象。 Astryx TypeScript 与 TSX 消费者在向 StyleX、DOM 样式或 SVG 表现属性传递选定值时 MUST 导入 dataVars。他们 MUST NOT 构造字面量 var(--color-data-*) 字符串。这包括默认 prop 值,例如蜡烛图的上涨/下跌颜色。

CanvasRenderingContext2D 及其它非 CSS API MUST NOT 接收 dataVars 的 var() 引用。它们 MUST 使用现有的、具体模式解析后的 JavaScript 路径,例如 resolveThemeToken() 或 useTheme().token(),与 FR13 保持一致。生成的兼容视图保持该解析器源自同一规范 .stylex.ts 源。

在预构建模式中,原始 CSS 与消费者代码可以引用稳定的 var(--color-data-*) 名称而无需回退:预构建的 Core 样式表在 FR3 下定义了完整组。源码构建的产品通过 dataVars 读取数据颜色,这会在源码图中保留该组。@astryxdesign/build 的 PostCSS 集成始终在 FR3 下发出该组;基于图但未导入 dataVars 的源码构建会使原始引用未定义,这是不受支持的。显式的本地回退在每种模式中仍然有效。文档 MUST not 暗示主题样式表本身会物化默认值。

  • FR5 — 直接 SVG 与 DOM 值正确绘制。 直接传给 SVG 表现属性或 DOM 样式的 dataVars 值 MUST 编译为稳定的 var(--color-data-*) 引用。在源码编译中,导入 MUST 保留变量定义模块;在预构建模式中,Core 的样式表 MUST 在 FR3 下提供该组。默认值与主题覆盖后的值 MUST 绘制出预期的填充和描边。未声明的数据变量会将蜡烛图主体绘制为黑色并丢失其影线描边;该状态 MUST NOT 再次出现。

稀疏主题输出

  • FR6 — 具体主题仅发出显式创作的数据值。 运行时与静态主题编译 MUST 在默认值解析之前识别创作输入集。对于每个显式创作的 --color-data-* 名称,具体主题在其现有的 astryx-theme 圆环中发出该声明:
@layer astryx-theme {
  @scope ([data-astryx-theme="ocean"]) to ([data-astryx-theme]) {
    :scope {
      --color-data-categorical-blue: light-dark(#0077B6, #48CAE4);
    }
  }
}

一个没有创作任何数据值的主题不发出任何内容。部分创作集合恰好发出该子集。解析后的默认值、兼容映射以及继承的父级值 MUST NOT 被序列化,仿佛这些值由该主题创作。

  • FR7 — 主题构建绝不发出原始全局数据默认值。 运行时 <Theme> 注入以及独立的、多文件的或家族 theme build 输出均不得在 :root、html、body 或其它圆环外选择器上发出规范的数据默认值。主题编译 MUST not 调用、内联或保留与原始 generateDataTokenDefaultsCSS() 等价的内容。由源码消费者或 Core 分发在 FR3 下保留的规范 StyleX 组,是唯一的 CSS 默认值所有者。

移除旧的默认值块 MUST NOT 移除其层序副作用。每个独立的、多文件的、家族以及运行时主题输出 MUST 保留一条显式的顺序注册,等效于:

@layer reset, astryx-base, astryx-theme;

该注册不包含任何数据声明。无论主题 CSS 还是组件 CSS 先加载,它都保持 astryx-base 位于创作的主题覆盖之下。

级联行为

  • FR8 — 嵌套主题继承所有未指定的数据值。 同身份与不同身份的嵌套主题使用正常的自定义属性继承。未创作任何数据值的子主题继承父主题的有效值。创作了子集的子主题仅在其圆环内替换该子集;所有被省略的名称继续继承。仅更改身份不会重置调色板。

  • FR9 — 同级根针对创作覆盖保持隔离。 一个 Theme 根中的作用域覆盖 MUST NOT 影响同级 Theme 根。两个根都从同一个保留的 StyleX 规范组解析未指定的名称。

  • FR10 — 动态身份切换仅选择创作的增量。 在必需的 reset < astryx-base < astryx-theme 顺序下,并且当所有目标主题样式表都已加载时,更改根的主题身份 MUST 精确地添加、移除或替换所选主题创作的数据子集。每个被省略的名称恢复到继承的 StyleX 默认值或祖先值。层顺序注册后,物理样式表顺序 MUST NOT 改变优先级胜出者。选择了一个 CSS 缺失的构建主题,仍属于不完整的消费者配置。

  • FR11 — 浅色与深色保持现有解析。 规范与创作的 light-dark() 数据值 MUST 像其它 StyleX 变量一样,从有效的 color-scheme 解析。显式浅色、显式深色、系统模式、MediaTheme、同主题嵌套和不同主题嵌套保留现有模式契约。

可用性与 JavaScript 兼容性

  • FR12 — 可用性取决于编译模式,而非主题是否存在。 基于图的源码构建如果编译后的消费者未保留 dataVars,则不包含数据变量默认值。Core 的预构建样式表始终在 FR3 下保留该组,因为仅编译后的公共入口本身无法发出定义,而 @astryxdesign/build 的 PostCSS 集成始终保留它,因为它会编译所有已发布的 Core 源码。在每种模式下,标准 StyleX 0.19 输出都会在 :root 上声明完整组,外加其变量组类,这与现有规范 StyleX token 组完全一致。此全局声明是所选规范 token 系统可接受的编译器后果;它 MUST NOT 被归因于主题构建或由主题构建重复发出。

在受支持的 Astryx 源码和分发集成中,发出的组 MUST 被包装在 @layer astryx-base 中。裸 StyleX 转换会发出相同的选择器,但不带 layer;在文档根节点上,该未分层默认值的优先级高于分层的主题覆盖,并可能导致 portal 颜色错误。此类流水线不在主题覆盖保证范围内,MUST 被明确诊断或记录。

仅需在主题内使用数据变量的消费者,MUST 在组件结构中强制执行该使用边界。本契约并不声称一个保留的 StyleX defineVars 组不会出现在未启用主题的 DOM 中。

  • FR13 — JavaScript token 解析保持兼容。 现有的 dataTokenDefaults、domainTokenDefaults、tokenDefaults、resolveThemeToken()、resolveThemeTokens()、useTheme().token() 和 useTheme().tokens 名称及返回结构仍然可用。它们的规范数据值源自 FR1。此项工作 MUST NOT 将 token API 变成计算样式读取器,也不得改变其现有的 provider/no-provider 语义。

运行时、构建与家族一致性

  • FR14 — 运行时与构建后的主题输出是等价稀疏增量。 对于相同的主题输入,运行时和静态编译会发出相同的作者编写的数据名称、值、layer、选择器和 donut 边界。两条路径都不会发出默认值。生成的 JavaScript 仍为 __built: true;该标记继续表示具体主题 CSS 已加载且跳过运行时编译。不会添加回退数据注入或第二个标记。

  • FR15 — 家族输出仅包含成员所撰写的子集。 一个家族 CSS 文件在每个选定成员的身份下包含该成员的显式数据覆盖。零数据增量的成员不贡献任何数据声明。该家族文件绝不重复规范 56。嵌套成员遵循 FR8,切换遵循 FR10,且家族文件最多发出一次全局 color-scheme 策略。

全局 color-scheme 兼容性

  • FR16 — 完整 bundle 可以保留一条兼容的全局环境策略。 具体 bundle 可以继续发出且仅发出以下三条规则:
@layer astryx-theme {
  :root { color-scheme: light dark; }
  html[data-theme="light"] { color-scheme: light; }
  html[data-theme="dark"] { color-scheme: dark; }
}

一个独立的具体 bundle 若发出该策略,则 MUST 发出全部三个字节等价的选择器、声明及 layer 所有权。主题 MUST NOT 对该策略进行专门化、部分发出、重排或以其他方式偏离。独立 bundle 只能在完整集合的形式下省略该策略。家族聚合保留其现有的以身份为作用域的 color-scheme 组合;本规范既不重新设计该组合,也不将其视为新的具体主题策略。这些环境声明不允许主题构建在全局发出数据默认值。

兼容性、迁移与文档

  • FR17 — 所有权转移采用破坏性 0.x 路径。 第一个移除主题构建全局默认值的发布 MUST 使用仓库的破坏性变更流程:为受影响的 0.x 包发布一个 minor 版本、一个 breaking Changeset,以及迁移说明。此破坏对于以下对象是可观察的:图未保留 dataVars 的原始数据变量消费者、依赖具体主题 CSS 来定义全局变量的消费者,以及仍包含旧根块(root block)的生成产物。

  • FR18 — 迁移优先使用公共导入,而非兼容性 CSS。 Astryx 组件、fixture、示例和测试的迁移,在源码支持 StyleX 时,MUST 将可构造的字符串字面量替换为 dataVars 引用。升级工具和重新生成 MUST 拒绝过时的原始根默认值。升级工具不检查直接的原始消费者,MUST NOT 要求为它们提供回退。已带有显式回退的原始 CSS 和生成模板仍然有效。迁移 MUST NOT 添加旧的全局数据主题模式、provider prop、sidecar 样式表、任意主题包装器或凭空发明的回退颜色。

  • FR19 — 主题输入验证与 CLI 输出保持真实。 每个稳定的数据名称仍然是有效的主题输入,每个未知名称仍然会被拒绝。主题构建保持其当前的 CSS/JS/声明文件名及配对,但生成的 CSS 和文档 MUST 将数据声明描述为作者编写的稀疏覆盖。--check 和升级验证 MUST 使仍包含规范根块或主题作用域内非作者编写默认值的旧产物失败。

  • FR20 — 消费者文档须区分三条路径。 文档 MUST 展示:(1) 面向支持 StyleX 的组件代码使用 dataVars,这是源码构建所采用的路径;(2) 对于需要具体模式解析值的 API,使用 JavaScript token 解析;(3) 在预构建模式下使用原始 CSS 自定义属性,此时由 @astryxdesign/core/astryx.css 提供默认值,或使用显式回退。文档 MUST 如实说明整组 tree-shaking,并将 color-scheme 兼容性和发布工作排除在此变更之外。

平台支持

  • 支持的浏览器下限:现有的主题、StyleX 和 @scope 矩阵。
  • 不支持的行为:低于该下限的浏览器保留现有的支持策略;不添加全局主题构建数据回退。
  • 浏览器证据:在 Verification 中,跨该矩阵的真实 Chromium 计算样式和已绘制的 SVG 值。

当前状态影响

公开 StyleX 数据组拥有规范 CSS 默认值;兼容性、类型、验证和文档视图均源自它。基于图的源码编译保留整组 tree-shaking。Core 的预构建样式表为编译后的公开 dataVars 入口提供同一组,无需消费者编译步骤或运行时 Theme 注入,且 @astryxdesign/build PostCSS 集成始终发出它。

具体独立主题与家族主题仅包含作者定义的作用域覆盖。嵌套主题继承省略,JavaScript 解析保持兼容,全局 color-scheme 规则、构建标记、文件名及成对的 CSS/JS/type 输出均不变。

architecture:theme-compilation 拥有运行时/静态稀疏主题输出。 architecture:theme-application 拥有 provider 嵌套和样式生命周期。 architecture:theme-tokens 拥有共享词汇表和派生的兼容性视图;本记录的 FR3 拥有预构建和 PostCSS 数据组可用性保证。在该保证之外,spec:AST-080 管理 @astryxdesign/build。

验证

Contract Verification Representative states Mutation or failure expectation
FR1–FR3 生成器漂移、公开导出、图感知编译器、PostCSS 集成及包 CSS 测试 无导入的基于图源码图;未导入 dataVars 的开发与生产 PostCSS 构建;预构建 Core;一个保留成员;跨包 provider 对;原始/gzip 大小 普通默认值漂移;公开键更改;未使用的基于图源码发出 data vars;预构建 Core 或 PostCSS 构建省略或更改任意项;一次使用发出少于/多于 56 项;重复组
FR4–FR5 源码审计、编译器 fixture、组件测试、真实 Chromium 直接 SVG fill/stroke;DOM 样式;Canvas 具体解析;显式 props;规范 green/red;作者定义覆盖 字面量构造保留;直接 CSS 值未保留定义;Canvas 收到 var();body 呈现黑色或灯芯消失
FR6–FR7 运行时/静态/家族结构与层顺序测试 零/一/多个作者定义名称;全部 56 个规范名称;:root/html/body 扫描;组件 CSS 之前/之后的主题 CSS 被省略的默认值被序列化;作者定义值在环形图之外;原始默认值保留;层顺序翻转
FR8–FR11 真实浏览器级联矩阵 相同/不同嵌套;父/子子集;兄弟节点;动态切换;light/dark/system/MediaTheme;portal;分层与未分层源 CSS 省略导致重置;兄弟泄漏;顺序/模式改变胜者;未分层根节点静默宣称覆盖对等
FR12–FR16 编译器/运行时/构建对等与环境策略测试 无数据消费者;保留的分层组;运行时与构建主题;独立与家族 color-scheme 组合 Theme 存在时发出默认值;构建/运行时不一致;家族重复默认值;全局策略分歧
FR17–FR20 Changeset、codemod、CLI 检查、文档及再生成 fixture 字面量组件/fixture 使用;预构建与源码构建中有/无 fallback 的原始 CSS;旧 root 构件;普通/家族构建 无破坏性说明;不安全的自动重写;陈旧构件通过;原始用法升级失败;文档声称主题 CSS 提供默认值或 token 粒度剪枝

真实浏览器验证 MUST 独立断言规范值与作者定义值,而不是复用生成器输出作为判定基准。它 MUST 在移除变量声明后复现黑色主体/不可见灯芯状态,然后在公开 StyleX 导入后证明 SVG fill 和 stroke 正确。它 MUST 覆盖默认、显式 prop、父覆盖、子子集覆盖、相同/不同嵌套身份、兄弟节点、动态切换、light/dark 值,以及从文档根继承的 portal 内容。非 CSS 验证 MUST 通过 JavaScript token API 解析相同的规范颜色和作者定义颜色,并断言 Canvas 赋值永远不会收到 var() 引用。未分层的 StyleX 输出 MUST 是红色臂:它必须证明受支持的集成为何将规范默认值包裹在 astryx-base 中,而不是被报告为等价。

编译器验证 MUST 通过基于图的流水线编译一个未使用的入口和一个单成员消费者。未使用输出包含零个 --color-data-* 默认值;保留输出在 StyleX 变量组中恰好包含每个规范名称一次。它 MUST not 声称按属性剪枝。PostCSS 集成验证 MUST 在未导入 dataVars 的产品上运行文档化配置,分开发和生产模式,并将输出与规范源码比较:每个名称和值恰好一次,声明在 @layer astryx-base 内的 :root 上。分发验证 MUST 证明 Core 的预构建样式表恰好定义全部 56 个规范值一次,且 satellite/provider 对不会重复该组。仅使用预构建 CSS 与编译后的公开 dataVars 入口的生产应用 MUST 在 light/dark 两种模式及两种样式表加载顺序下渲染规范值和作者定义值。报告保留组的原始与 gzip 增量。

主题输出验证 MUST 枚举全部 56 个规范名称,并且如果独立的、多文件的、族(family)的或运行时主题 CSS 中出现未经作者编写的规范值,则验证失败。它 MUST 在主题构建产生的任何原始 :root 数据声明,以及显式 reset, astryx-base, astryx-theme 顺序注册被移除时失败。全局 color-scheme 验证会单独比较具有代表性的输出 bundle 中的完整独立三规则策略,断言不输出的独立 bundle 不包含这三种规则中的任何一种,并保持现有族组合不变。

完成标准

合规要求:

  • 一个规范的 .stylex.ts 源、一个公共 dataVars 导出,以及生成的兼容性/类型/验证视图;
  • 在基于图的源码构建中进行真实的全组 tree-shaking,在 PostCSS 集成输出中包含完整组,并保证显式的预构建 Core 可用性,同时进行依赖感知的卫星去重;
  • Astryx 消费者已完成迁移,且不存在可构造的原始 data-var 字符串;
  • 在运行时、独立、多文件和族模式下,有稀疏 donut 覆盖和零主题构建原始默认值;
  • JS token API 和主题输入兼容性;
  • 真实的 Chromium SVG/级联证据,包括未声明变量的红色分支(red arm);
  • 下游主题产物的重新生成和迁移证据;以及
  • 独立架构评审加上绿色 CI。

决策日志

DEC-1 — 公共 StyleX 变量拥有规范 CSS 默认值

参考: spec:AST-066/DEC-1 决策者: cixzhang, 2026-10-01

数据调色板加入规范的 StyleX token 系统。已签入的 .stylex.ts 模块拥有名称和默认值,组件通过稳定的 CSS 名称导入其公共对象。普通 JavaScript 默认值、类型、验证和文档仍是生成的兼容性视图,而不是第二套手工维护的权威。

已拒绝:保留 dataTokenDefaults 作为独立的 CSS 生成器输入。那是一种并行的元数据架构,曾导致消费者与已输出 CSS 不一致。

DEC-2 — 对一个语义化 56 变量组进行 tree-shake

参考: spec:AST-066/DEC-2 决策者: cixzhang, 2026-10-01

StyleX 0.19 在其模块被保留时会输出完整的 defineVars 组,且无法裁剪单个对象属性。一个数据调色板组匹配现有 colorVars 模型,保持公共 API 连贯,并提供诚实的源码编译 0-或-56 边界。预编译包 CSS 在跨包时仍然保持图感知,FR3 中明确给出的 Core 发行版例外除外;它不使用仓库级文件扫描。DEC-10 将该边界限定到基于图的源码构建。

已拒绝:声称 token 粒度剪枝,或仅为了模拟该效果而将调色板拆分成多个文件。两者都会让 API 和维护成本超出已展示的编译器能力。

DEC-3 — 主题输出仅包含作者编写的增量

参考: spec:AST-066/DEC-3 决策者: cixzhang, 2026-10-01

主题构建负责定制化,而非规范可用性。它仅在正常 donut 中序列化显式数据输入,绝不输出原始根默认值块。它保留一个仅声明层的引子(prelude),因此即使移除该块,在 CSS 加载顺序变化时也不会颠倒 astryx-base 和 astryx-theme。

已拒绝:将 56 个默认值复制到每个主题,并保留一个无条件根块。前者重复默认值;后者让主题存在本身(而非实际 StyleX 使用)拥有调色板。

DEC-4 — 嵌套省略继承

参考: spec:AST-066/DEC-4 决策者: cixzhang, 2026-10-01

相同或不同的嵌套主题会继承所有未指定的自定义属性,并且只替换作者编写的那部分。仅凭相同的标识(identity)并不会重置调色板。

已拒绝:将省略的值视为作者请求规范默认值。

DEC-5 — 当组被保留时,接受标准 StyleX 根输出

参考: spec:AST-066/DEC-5 决策者: cixzhang, 2026-10-01

stylex.defineVars(defaults) 会在 :root 以及一个变量组类上输出其组。这与现有 token 组是相同的规范机制。因此本决策中的严格边界是所有权:未使用的基于图的源码图不输出任何内容;Core 发行版和 PostCSS 集成在 FR3(DEC-10)下保留该组;主题构建永远不会全局输出数据默认值。

已拒绝:承诺保留的规范 StyleX 变量不会出现在未主题化的 DOM 中。标准 defineVars 无法做出这种承诺;手动限定作用域的并行声明或无条件 Theme 类会与所选的真实来源和 tree-shaking 模型相矛盾。

DEC-6 — 保持 JavaScript 解析兼容性

参考: spec:AST-066/DEC-6 决策者: cixzhang, 2026-10-01

现有解析器名称、形状和模式行为继续通过生成的兼容性视图提供。这样可以在不将已经需要具体值的调用方强推到 DOM computed-style API 的情况下,更改 CSS 所有权。

已拒绝:删除 dataTokenDefaults 或将 useTheme 改为级联读取器。修复 CSS 所有权都不需要这两项。

DEC-7 — 保持一个兼容的全局 color-scheme 策略

参考: spec:AST-066/DEC-7 决策者: cixzhang, 2026-10-01

这三条 root/html 规则有意配置浏览器范围内的 light-dark() 和 UA 行为。完整的主题 bundle 可以在完全一致时重复它们,也可以省略整组。测试会防止特化或部分输出。

已拒绝:对 color-scheme 打包进行作用域限定或拆分。

DEC-8 — 通过原子堆栈和破坏性次版本进行迁移

参考: spec:AST-066/DEC-8 决策者: cixzhang, 2026-10-01

实现将规范公共 StyleX 所有权、消费者迁移和主题生成器清理分开,使每次评审只有一个变更理由。该版本使用破坏性的 0.x 次版本,并带有重新生成和消费者诊断。

已拒绝:遗留的全局数据模式。它会让新产物继续依赖本决策所移除的行为,并使运行时/静态所有权依赖于模式。

DEC-9 — 预构建 Core CSS 定义公共数据变量条目

参考: spec:AST-066/DEC-9 决策者: cixzhang, 2026-10-20

预构建的公共 dataVars 条目包含 CSS var() 引用,且没有存留的 defineVars() 调用。预构建 CSS 的使用者无法通过导入该已编译对象来保留默认值。因此,Core 的样式表包含单一规范组,就像它的其他公共 token 默认值一样。基于图的源码编译保留零或 56 规则(DEC-10);主题仅包含显式编写的增量。固定成本是一组 56 个声明,而不是第二个源码或新的运行时模式。

否决:要求预构建使用者编译源码 token 条目,因为这会破坏预构建 CSS 契约及其文档化的导入路径。

DEC-10 — 源码构建通过 dataVars 读取数据颜色

参考: spec:AST-066/DEC-10 决策者: cixzhang, <pending>

原始 var(--color-data-*) 字符串是预构建路径:Core 的样式表定义该组(FR3、DEC-9)。源码构建通过 dataVars 读取数据颜色,这会在基于图的流水线中保留该组,并将 DEC-2 的零或 56 边界保留在那里。@astryxdesign/build 的 PostCSS 集成会编译 Core 发布的每个模块,因此其输出总是在 astryx-base 中携带完整组。该决定将 DEC-2 的源码边界和 DEC-5 的未使用图规则限定到基于图的源码构建。升级工具不需要为原始使用者提供回退(FR18);在基于图的源码构建中,没有 dataVars 导入的原始字符串不受支持(FR4)。

否决:一种推断构建模式并要求回退的升级检查,因为没有任何项目信号能够可靠区分预构建与源码构建。

弃用与清理记录

IFIX-0009 — 主题停止发出原始全局数据颜色默认值

字段 值
id IFIX-0009
cleanup CLN-0016
package @astryxdesign/core, @astryxdesign/cli
surface Theme 运行时和 theme build(独立模式与 family 模式)为每个主题发出的、未限定作用域的原始 :root 规范数据颜色默认值块
authority FR6(具体主题仅发出显式编写的数据值)、FR7(theme build 绝不发出原始全局数据默认值)和 FR12(可用性取决于编译模式,而非是否存在 Theme)。所有者:spec:AST-066:cixzhang
reproducer 使用最新的稳定包,未编写任何数据颜色的主题会在未限定作用域的根块中发出每个规范数据默认值,无论是在运行时 CSS 中还是在 theme build 输出中
affected 直接读取原始数据颜色自定义属性、依赖主题来定义它、且未编译 dataVars 使用者的 CSS;以及已检入应用的过期生成主题 CSS
matrix 未编写数据颜色的主题:之前有每个规范默认值;之后无。作者覆盖:之前和之后都会发出,并限定在其主题范围内。StyleX dataVars 使用者:之前和之后绘制值相同。全局 color-scheme 规则:不变
coexistence 公共 dataVars 组通过保留的源码编译或预构建 Core 样式表提供规范值;单独的编译导入不会发出 CSS
migration 通过公共 dataVars 组读取数据颜色,或在主题中编写所需的值。重新生成已构建的主题 CSS
codemod astryx upgrade 会运行一个验证器,拒绝过期的生成 CSS;直接原始使用者不需要 codemod
downstream 维护中的文档和模板通过 dataVars 读取数据颜色
rollback 从最终补丁基线恢复运行时和 theme build 输出中的原始默认值块
harm of delay 每个主题持续发布一个没有任何使用者也能存活的第二个全局调色板,并且可能与规范的 StyleX 组不一致
harm of apply 当 CSS 读取原始数据变量时,如果没有 dataVars 或作者提供的值,那么在迁移完成之前,变量会以未设置的状态进行绘制。
transition 此前无迁移
state proposed
open decision 除批准此提议记录及其清理之外,无其他未决决策。

CLN-0016 — 从主题输出中移除原始全局 data-color 默认值

字段 值
id CLN-0016
lifecycle IFIX-0009
delta 运行时和构建后的主题仅输出作者提供的数据值,并将其限定在相应主题内。显式层顺序与全局 color-scheme 规则保持不变
rollback 从最终补丁基线恢复原始默认块
state pending — 将随其 [breaking] Changeset 在已声明的小版本中落地

未决问题

无。

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